Vodič za razvojne programere

Autentifikacija

Izradite API ključ na nadzornoj ploči u odjeljku Postavke, API i webhookovi. Ključevi počinju s ss_live_, pripadaju jednom radnom prostoru i mogu se ograničiti na određene projekte. Šaljite ključ kao bearer token u svakom zahtjevu:

curl https://www.amaposta.com/api/v1/me \
  -H "Authorization: Bearer ss_live_…"

Odgovor sadrži naziv ključa, njegove dozvole i radni prostor. Svaki ključ ima jednu ili više dozvola:

Svaki ključ može slati 120 zahtjeva u minuti. Nakon toga dobit ćete 429 s kodom rate_limited; pričekajte malo i pokušajte ponovno.

Projekti i kanali

Objave pripadaju projektu. Izlistajte projekte kojima vaš ključ ima pristup, a zatim kanale u jednom od njih. Za odabir kanala ili promjenu njegova teksta trebat će vam njegov ID.

curl https://www.amaposta.com/api/v1/projects \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/channels \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Kanal ima provider (youtube, instagram, tiktok, x, facebook, custom ili sandbox), status (active, expiring, needs_reconnect, error ili disabled) i vrste objava koje podržava u polju supports.

Prenesi medije

Slike i videozapisi prenose se jednom po projektu i mogu se koristiti u neograničenom broju objava. Postoje tri načina prijenosa.

Izravan prijenos

Pošaljite datoteku kao multipart form data u polju naziva file. Najprikladnije za datoteke do nekoliko stotina MB.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -F "[email protected]"

Prijenos velikih datoteka unaprijed potpisanim URL-om

Zatražite URL za prijenos, pošaljite bajtove izravno u pohranu metodom PUT, a zatim javite Amaposti da ste završili.

# 1. Ask for an upload URL. The response is {"media": { … }, "upload_url": "…"}
curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/uploads \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "batch-142.mp4", "content_type": "video/mp4", "size_bytes": 48213844}'

# 2. Upload the bytes to upload_url
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file batch-142.mp4

# 3. Finish the upload
curl -X POST https://www.amaposta.com/api/v1/media/$MEDIA_ID/complete \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Uvoz s URL-a

Dajte Amaposti javni URL i ona će preuzeti datoteku u pozadini. Ovaj korak možete i preskočiti te proslijediti media_url pri izradi objave.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/import \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.example.com/batch-142.mp4"}'

Svaki prijenos vraća medijski objekt. Njegov status prelazi iz pending u processing pa u ready (ili failed, uz error). Nakon obrade sadrži width, height, duration_ms i sličicu. Periodično provjeravajte GET /api/v1/media/{id} ili slušajte webhook media.ready. Vraćeni url potpisan je i valjan 12 sati.

Izradi objavu

POST /api/v1/projects/{project_id}/posts izrađuje jednu objavu s isporukom za svaki kanal. Amaposta je prilagođava svakoj platformi: naslovi se šalju samo ondje gdje postoji polje za naslov, hashtagovi postaju oznake na YouTubeu, a drugdje dio teksta.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-142" \
  -d @- <<'JSON'
{
  "kind": "video",
  "title": "How we roast a batch in 12 minutes",
  "description": "From green beans to first crack. We filmed one batch start to finish.",
  "hashtags": ["coffee", "behindthescenes"],
  "media_url": "https://cdn.example.com/batch-142.mp4",
  "cover_url": "https://cdn.example.com/batch-142-cover.jpg",
  "overrides": {
    "<x-channel-id>": {
      "description": "Batch 142 is out: green beans to first crack in 12 minutes."
    },
    "<youtube-channel-id>": {
      "options": { "privacy": "unlisted" }
    }
  },
  "schedule": { "mode": "queue" },
  "external_ref": "episode-142",
  "metadata": {
    "pipeline": { "name": "nightly-cut", "run": "2026-10-17" }
  }
}
JSON

Polja

Odgovor je objava, uključujući po jedan zapis u deliveries za svaki kanal.

Sigurni ponovni pokušaji

Mreže gube zahtjeve. Pošaljite zaglavlje Idempotency-Key pri izradi objave i ponovni pokušaj s istim ključem vratit će objavu iz prvog pokušaja umjesto izrade druge. Upotrijebite stabilnu vrijednost sa svoje strane, poput ID-ja zadatka ili epizode. Ključevi se skraćuju na 200 znakova.

Zakazivanje i objavljivanje

Zakažite nacrt, objavite ga sada, dodajte u red ili uklonite s kalendara pomoću POST /api/v1/posts/{post_id}/schedule.

curl https://www.amaposta.com/api/v1/posts/$POST_ID/schedule \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "at", "at": "2026-10-20T07:00:00Z"}'

• atObjavljuje u zadano vrijeme, do dvije godine unaprijed.
• nowObjavljuje odmah.
• queueZauzima sljedeći slobodan termin objavljivanja za kanale objave u sljedećih 12 tjedana.
• unscheduleVraća objavu među nacrte.

Prije zakazivanja pokreću se iste provjere kao u uređivaču. Ako neka ne uspije, zahtjev vraća 400 s porukom poput Ispravite prije zakazivanja: YouTube zahtijeva naslov. Za zakazivanje je potrebna dozvola posts:publish ili projekt s uključenim odobravanjem; u tom slučaju objava čeka među pristiglim zahtjevima za pregled.

Čitanje objava i isporuka

Izlistajte objave projekta, filtrirane prema status (statusi odvojeni zarezom ili inbox, queue ili history), razdoblju from/to, uz limit i offset. Odgovor je {"items": […], "total": n}.

curl "https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts?status=queue" \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Objava ima ukupni status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial ili failed) i jednu isporuku po kanalu:

"deliveries": [
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "status": "published",
    "url": "https://www.youtube.com/watch?v=…",
    "error": null,
    "published_at": "2026-10-20T07:00:41Z"
  },
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a9-…",
    "status": "failed",
    "url": null,
    "error": {
      "code": "endpoint_unavailable",
      "message": "Your endpoint returned 503 Service Unavailable",
      "hint": "Amaposta will retry with backoff."
    },
    "published_at": null
  }
]

Statusi isporuke su pending, scheduled, publishing, processing, published, failed i cancelled. DELETE /api/v1/posts/{post_id} uklanja objavu.

Pogreške

Svaka pogreška ima istu strukturu: objekt error sa stabilnim code, porukom message koju možete prikazati ljudima, a ponekad i s fields (poruke po poljima) i hint.

{
  "error": {
    "code": "validation",
    "message": "Please fix the highlighted fields.",
    "fields": {
      "kind": "Use text, image or video."
    }
  }
}

Webhookovi

Dodajte krajnju točku u odjeljku Postavke, API i webhookovi, odaberite željene događaje i kopirajte njezin tajni ključ za potpisivanje. Amaposta za svaki događaj šalje JSON vašem URL-u metodom POST. Svaki odgovor osim 2xx, ili izostanak odgovora unutar 15 sekundi, pokreće ponovni pokušaj uz sve dulje razmake. Krajnje točke koje trajno ne uspijevaju isključuju se uz obavijest administratorima.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Amaposta-Webhooks/1.0
X-Amaposta-Event: post.published
X-Amaposta-Event-Id: 0192b7e0-…
X-Amaposta-Signature: t=1792479641,v1=5f2b0c…

{
  "id": "0192b7e0-…",
  "type": "post.published",
  "created_at": "2026-10-20T07:00:41Z",
  "project_id": "0192a3f1-…",
  "data": {
    "post_id": "0192b7c8-…",
    "delivery_id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "provider": "youtube",
    "external_id": "…",
    "url": "https://www.youtube.com/watch?v=…"
  }
}

Provjerite potpis

X-Amaposta-Signature je t=<unix seconds>,v1=<hex>, gdje je v1 vrijednost HMAC_SHA256(secret, t + "." + body) nad izvornim tijelom zahtjeva. Izračunajte je sami, usporedite u konstantnom vremenu i odbacite stare vremenske oznake kako biste spriječili ponovnu reprodukciju zahtjeva.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (string or Buffer).
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

import hashlib
import hmac
import time


def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Kanal s vlastitim API-jem objavljuje na HTTPS krajnjoj točki kojom vi upravljate: u vašem CMS-u, alatu za biltene ili na platformi koju Amaposta još ne podržava. Prikazuje se na kalendaru te ima provjere, odobravanje i ponovne pokušaje kao svaki drugi kanal. Pri objavljivanju Amaposta šalje jedan POST po isporuci:

POST /amaposta/publish HTTP/1.1
Authorization: Bearer <your API key>
Content-Type: application/json
Idempotency-Key: 0192b7d4-…
X-Amaposta-Delivery: 0192b7d4-…
X-Amaposta-Signature: t=1792479600,v1=9ac41e…

{
  "id": "0192b7d4-…",
  "type": "post.publish",
  "created_at": "2026-10-20T07:00:00Z",
  "content": {
    "kind": "video",
    "title": "How we roast a batch in 12 minutes",
    "text": "From green beans to first crack. We filmed one batch start to finish.",
    "hashtags": ["coffee", "behindthescenes"],
    "media": {
      "url": "https://…",
      "content_type": "video/mp4",
      "size_bytes": 48213844,
      "width": 1080,
      "height": 1920,
      "duration_ms": 58000,
      "filename": "batch-142.mp4"
    },
    "cover": null,
    "options": {}
  },
  "post": {
    "id": "0192b7c8-…",
    "external_ref": "episode-142",
    "scheduled_at": "2026-10-20T07:00:00Z",
    "metadata": {
      "pipeline": { "name": "nightly-cut" }
    }
  },
  "project": { "id": "0192a3f1-…", "name": "Spring launch" },
  "channel": { "id": "0192b7a9-…", "name": "api.example.com" }
}

Authorization

Vaš API ključ. Naziv zaglavlja i prefiks (zadano Bearer) postavljaju se na kanalu.

Idempotency-Key

ID isporuke. Ponovni pokušaj iste isporuke šalje isti ključ pa možete preskočiti već obavljen posao.

X-Amaposta-Delivery

Ponovno ID isporuke, za vaše zapisnike.

X-Amaposta-Signature

Potpisano kao webhookovi, vlastitim tajnim ključem kanala za potpisivanje.

Kako odgovoriti

• 2xxObjavljeno. Neobavezno vratite {"id": "…", "url": "…"} i poveznica će se prikazati uz objavu.
• 401, 403Ključ je odbijen. Kanal se označava za ponovno povezivanje, a administratori se obavještavaju. Nemojte koristiti ove statuse za neispravan potpis.
• 5xx, 408, 429Privremeno. Amaposta pokušava ponovno uz sve dulje razmake.
• Ostali 4xxObjava se označava kao neuspjela uz vašu poruku pa je netko može ispraviti i pritisnuti Pokušaj ponovno.

app.post("/amaposta/publish", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.get("X-Amaposta-Signature") ?? "";
  if (!verifySignature(req.body, signature, process.env.AMAPOSTA_SIGNING_SECRET)) {
    return res.status(400).json({ message: "Bad signature" });
  }
  const delivery = JSON.parse(req.body);
  const item = await publishToYourSystem(delivery.content, req.get("Idempotency-Key"));
  res.json({ id: item.id, url: item.url });
});

Vaša krajnja točka mora biti dostupna s interneta; preusmjeravanja se ne slijede. Pri povezivanju kanala Amaposta provjerava krajnju točku zahtjevom GET na vaš URL za provjeru ispravnosti, ako je postavljen, ili zahtjevom OPTIONS na krajnju točku.

Kanal Sandbox ponaša se poput pravog, ali ništa ne napušta Amapostu. Upotrijebite ga za izradu i testiranje integracije od početka do kraja: objave se zakazuju, ulaze u eter, objavljuju ili ne uspijevaju i pokreću iste webhookove. Kanali Sandbox besplatni su u svakom paketu i ne ulaze u ograničenje broja kanala.

Pri dodavanju odaberite kako će se ponašati:

• Uvijek uspijevaSvaka objava uspijeva.
• Povremeno ne uspijevaPogledajte pogreške i ponovne pokušaje bez čekanja stvarnog prekida rada.
• Uvijek ne uspijevaTestirajte obradu događaja post.failed.
• Istekla vezaPogledajte kako izgledaju upozorenja i poveznice za ponovno povezivanje kada pristup istekne.