Průvodce pro vývojáře

Ověření

V přehledu v Nastavení, API a webhooky vytvořte API klíč. Klíče začínají ss_live_, patří jednomu pracovnímu prostoru a lze je omezit na vybrané projekty. V každém požadavku posílejte klíč jako bearer token:

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

Odpověď uvádí název klíče, jeho oprávnění a pracovní prostor. Každý klíč má jedno nebo více oprávnění:

Každý klíč může odeslat 120 požadavků za minutu. Po překročení dostanete 429 s kódem rate_limited; chvíli počkejte a zkuste to znovu.

Projekty a kanály

Příspěvky patří do projektu. Vypište projekty dostupné klíči a pak kanály v jednom z nich. Pro cílení na kanál nebo úpravu jeho textové verze budete potřebovat jeho 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"

Kanál má pole provider (youtube, instagram, tiktok, x, facebook, custom nebo sandbox), status (active, expiring, needs_reconnect, error nebo disabled) a typy příspěvků, které supports uvádí jako podporované.

Nahrát média

Obrázky a videa se nahrávají jednou do projektu a lze je použít v libovolném počtu příspěvků. K dispozici jsou tři způsoby.

Přímé nahrání

Pošlete soubor jako multipart form data v poli s názvem file. Nejvhodnější pro soubory do několika set MB.

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

Předem podepsané nahrávání velkých souborů

Vyžádejte si URL pro nahrávání, odešlete bajty metodou PUT přímo do úložiště a pak sdělte Amaposta, že je hotovo.

# 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"

Importovat z URL

Předejte Amaposta veřejnou URL a soubor se stáhne na pozadí. Tento krok můžete také přeskočit a při vytváření příspěvku předat media_url.

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"}'

Každé nahrání vrátí objekt média. Jeho status přechází z pending na processing a ready (nebo failed s polem error). Po zpracování obsahuje width, height, duration_ms a miniaturu. Pravidelně dotazujte GET /api/v1/media/{id} nebo naslouchejte webhooku media.ready. Vrácená url je podepsaná a platí 12 hodin.

Vytvořit příspěvek

POST /api/v1/projects/{project_id}/posts vytvoří jeden příspěvek s doručením pro každý kanál. Amaposta ho přizpůsobí platformě: názvy jdou pouze tam, kde je pole pro název, hashtagy se na YouTube stanou štítky a jinde součástí textu.

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

Pole

Odpovědí je příspěvek včetně jedné položky deliveries pro každý kanál.

Bezpečné opakované pokusy

Požadavky se v síti mohou ztratit. Při vytváření příspěvku pošlete hlavičku Idempotency-Key a opakování se stejným klíčem vrátí příspěvek z prvního pokusu místo vytvoření dalšího. Použijte stabilní hodnotu z vašeho systému, například ID úlohy nebo epizody. Klíče se zkracují na 200 znaků.

Plánovat a publikovat

Pomocí POST /api/v1/posts/{post_id}/schedule naplánujte koncept, publikujte ho nyní, přidejte ho do fronty nebo ho odeberte z kalendáře.

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"}'

• atPublikuje v zadaný čas až dva roky dopředu.
• nowPublikuje okamžitě.
• queueVybere nejbližší volný publikační čas pro kanály příspěvku v příštích 12 týdnech.
• unschedulePřesune příspěvek zpět do konceptů.

Před naplánováním se spouštějí stejné kontroly jako v editoru. Pokud některá selže, požadavek vrátí 400 se zprávou, například Před naplánováním opravte: YouTube vyžaduje název. Plánování vyžaduje oprávnění posts:publish nebo projekt se zapnutým schvalováním; v takovém případě příspěvek počká ve schránce ke kontrole.

Číst příspěvky a doručení

Vypište příspěvky projektu s filtrem status (stavy oddělené čárkou nebo inbox, queue či history), obdobím from/to, limit a offset. Odpověď má tvar {"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"

Příspěvek má celkový status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial nebo failed) a jedno doručení pro každý kanál:

"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
  }
]

Stavy doručení jsou pending, scheduled, publishing, processing, published, failed a cancelled. DELETE /api/v1/posts/{post_id} příspěvek odstraní.

Chyby

Všechny chyby mají stejnou strukturu: objekt error se stabilním code, zprávou message k zobrazení uživatelům a někdy také s fields (zprávy pro jednotlivá pole) a hint.

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

Webhooky

Přidejte endpoint v Nastavení, API a webhooky, vyberte požadované události a zkopírujte jeho podpisový tajný klíč. Amaposta pro každou událost odešle metodou POST JSON na vaši URL. Jakákoli odpověď mimo 2xx nebo chybějící odpověď do 15 sekund vede k opakování s prodlužujícími se intervaly. Trvale selhávající endpointy se vypnou a správci dostanou oznámení.

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=…"
  }
}

Ověřte podpis

X-Amaposta-Signature má tvar t=<unix seconds>,v1=<hex>, kde v1 je HMAC_SHA256(secret, t + "." + body) nad nezpracovaným tělem požadavku. Vypočítejte ho sami, porovnejte v konstantním čase a odmítejte stará časová razítka, abyste zabránili opakovanému zneužití požadavků.

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", ""))

Kanál s vlastním API publikuje na HTTPS endpoint, který provozujete: váš CMS, nástroj pro newslettery nebo platformu, kterou Amaposta zatím nepodporuje. Je v kalendáři a má stejné kontroly, schvalování a opakované pokusy jako ostatní kanály. Při publikování příspěvku Amaposta odešle jeden POST pro každé doručení:

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

Váš API klíč. Název hlavičky a předpona (výchozí Bearer) se nastavují u kanálu.

Idempotency-Key

ID doručení. Opakovaný pokus stejného doručení posílá stejný klíč, takže můžete přeskočit již dokončenou práci.

X-Amaposta-Delivery

Znovu ID doručení pro vaše protokoly.

X-Amaposta-Signature

Podepsáno jako webhooky vlastním podpisovým tajným klíčem kanálu.

Jak odpovědět

• 2xxPublikováno. Volitelně vraťte {"id": "…", "url": "…"} a odkaz se zobrazí u příspěvku.
• 401, 403Klíč byl odmítnut. Kanál se označí pro opětovné připojení a správci jsou informováni. Tyto stavy nepoužívejte pro nesprávný podpis.
• 5xx, 408, 429Dočasné. Amaposta opakuje pokus s prodlužujícími se intervaly.
• Ostatní 4xxPříspěvek se označí jako neúspěšný s vaší zprávou a někdo ho může opravit a stisknout Zkusit znovu.

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 });
});

Váš endpoint musí být dostupný z internetu; přesměrování se nesledují. Při připojování kanálu ho Amaposta ověří požadavkem GET na URL kontroly stavu, pokud jste ji nastavili, jinak požadavkem OPTIONS na endpoint.

Kanál Sandbox se chová jako skutečný, ale nic neopustí Amaposta. Použijte ho pro vytvoření a otestování celé integrace: příspěvky se plánují, vysílají, publikují nebo selhávají a spouštějí stejné webhooky. Kanály Sandbox jsou zdarma ve všech tarifech a nepočítají se do limitu kanálů.

Při přidávání vyberte jeho chování:

• Vždy úspěšnéKaždý příspěvek se publikuje.
• Občas selhatVyzkoušejte selhání a opakované pokusy bez čekání na skutečný výpadek.
• Vždy selhatOtestujte zpracování událostí post.failed.
• Připojení s vypršelou platnostíPodívejte se, jak vypadají upozornění a odkazy pro opětovné připojení po vypršení přístupu.