Vývojárska príručka

Overovanie

V paneli v časti Nastavenia, API a webhooky vytvorte kľúč API. Kľúče začínajú na ss_live_, patria jednému pracovnému priestoru a môžu byť obmedzené na určité projekty. Kľúč posielajte ako bearer token pri každej požiadavke:

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

Odpoveď uvádza názov kľúča, jeho oprávnenia a pracovný priestor. Každý kľúč má jedno alebo viac oprávnení:

Každý kľúč môže odoslať 120 požiadaviek za minútu. Po prekročení dostanete 429 s kódom rate_limited; chvíľu počkajte a skúste to znova.

Projekty a kanály

Príspevky patria do projektu. Zobrazte projekty, ktoré váš kľúč vidí, a potom kanály jedného z nich. Na zacielenie kanála alebo prepísanie jeho textu budete potrebovať 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á provider (youtube, instagram, tiktok, x, facebook, custom alebo sandbox), status (active, expiring, needs_reconnect, error alebo disabled) a podporované druhy príspevkov v supports.

Nahrať médiá

Obrázky a videá sa nahrávajú raz pre každý projekt a možno ich použiť v ľubovoľnom počte príspevkov. Sú tri spôsoby nahrávania.

Priame nahrávanie

Pošlite súbor ako multipart form data v poli s názvom file. Najvhodnejšie pre súbory do niekoľkých stoviek MB.

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

Vopred podpísané nahrávanie veľkých súborov

Vyžiadajte si URL na nahrávanie, odošlite bajty priamo do úložiska metódou PUT a potom oznámte Amaposta, že ste skonč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"

Importovať z adresy URL

Zadajte Amaposta verejnú URL a súbor stiahne na pozadí. Tento krok môžete aj vynechať a pri vytváraní príspevku odovzdať 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é nahratie vráti objekt média. Jeho status prechádza z pending cez processing na ready (alebo failed s error). Po spracovaní obsahuje width, height, duration_ms a miniatúru. Pravidelne volajte GET /api/v1/media/{id} alebo počúvajte webhook media.ready. Vrátená url je podpísaná a platí 12 hodín.

Vytvoriť príspevok

POST /api/v1/projects/{project_id}/posts vytvorí jeden príspevok s doručením pre každý kanál. Amaposta ho prispôsobí jednotlivým platformám: názvy sa posielajú len tam, kde je pole pre názov, hashtagy sa na YouTube zmenia na značky a inde na text v príspevku.

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

Polia

Odpoveďou je príspevok vrátane jedného záznamu v deliveries pre každý kanál.

Bezpečné opakované pokusy

V sieti sa požiadavky môžu stratiť. Pri vytváraní príspevku posielajte hlavičku Idempotency-Key a opakovaný pokus s rovnakým kľúčom vráti príspevok z prvého pokusu namiesto vytvorenia druhého. Použite stabilnú hodnotu zo svojho systému, napríklad ID úlohy alebo epizódy. Kľúče sa skrátia na 200 znakov.

Plánovať a publikovať

Naplánujte koncept, publikujte ho ihneď, pridajte ho do frontu alebo ho odoberte z kalendára pomocou 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"}'

• atPublikuje v zadanom čase, až dva roky dopredu.
• nowPublikuje ihneď.
• queuePoužije najbližší voľný časový úsek pre kanály príspevku v nasledujúcich 12 týždňoch.
• unscheduleVráti príspevok medzi koncepty.

Pred akýmkoľvek naplánovaním sa spustia rovnaké kontroly ako v editore. Ak niektorá zlyhá, požiadavka vráti 400 so správou, napríklad Pred naplánovaním opravte: YouTube vyžaduje názov. Plánovanie vyžaduje oprávnenie posts:publish alebo projekt so zapnutým schvaľovaním; v takom prípade príspevok čaká v schránke na kontrolu.

Čítať príspevky a doručenia

Zoznam príspevkov projektu, filtrovaný podľa status (stavy oddelené čiarkou alebo inbox, queue či history), obdobia from/to, limit a offset. Odpoveď 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"

Príspevok má celkový status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial alebo failed) a jedno doručenie na 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čenia sú pending, scheduled, publishing, processing, published, failed a cancelled. DELETE /api/v1/posts/{post_id} odstráni príspevok.

Chyby

Každá chyba má rovnakú podobu: objekt error so stabilným code, správou message, ktorú môžete zobraziť ľuďom, a niekedy aj fields (správy pre jednotlivé polia) a hint.

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

Webhooky

V nastaveniach v časti API a webhooky pridajte koncový bod, vyberte požadované udalosti a skopírujte jeho podpisové tajomstvo. Amaposta pre každú udalosť odošle JSON na vašu URL metódou POST. Pri odpovedi inej než 2xx alebo bez odpovede do 15 sekúnd pokus zopakuje s rastúcim odstupom. Koncové body, ktoré opakovane zlyhávajú, sa vypnú a správcom príde oznámenie.

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

Overiť podpis

X-Amaposta-Signature má tvar t=<unix seconds>,v1=<hex>, kde v1 je HMAC_SHA256(secret, t + "." + body) vypočítaný z nespracovaného tela požiadavky. Vypočítajte ho na svojej strane, porovnajte v konštantnom čase a odmietajte staré časové pečiatky, aby ste zabránili opakovanému prehratiu požiadaviek.

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 Custom API publikuje na koncový bod HTTPS, ktorý prevádzkujete vy: váš CMS, nástroj na newslettery alebo platformu, ktorú Amaposta ešte nepodporuje. Zobrazuje sa v kalendári a rovnako ako ostatné kanály má kontroly, schvaľovanie a opakované pokusy. Pri publikovaní príspevku Amaposta odošle jednu požiadavku POST na každé doručenie:

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áš kľúč API. Názov hlavičky a predpona (predvolene Bearer) sú nastavené na kanáli.

Idempotency-Key

ID doručenia. Opakovaný pokus rovnakého doručenia posiela rovnaký kľúč, takže už vykonanú prácu môžete preskočiť.

X-Amaposta-Delivery

Opäť ID doručenia pre vaše denníky.

X-Amaposta-Signature

Podpísané ako webhooky, s vlastným podpisovým tajomstvom kanála.

Ako odpovedať

• 2xxPublikované. Voliteľne vráťte {"id": "…", "url": "…"} a odkaz sa zobrazí pri príspevku.
• 401, 403Kľúč bol odmietnutý. Kanál sa označí na opätovné pripojenie a správcovia dostanú oznámenie. Nepoužívajte tieto kódy pri nesprávnom podpise.
• 5xx, 408, 429Dočasné. Amaposta opakuje pokusy s rastúcim odstupom.
• Ostatné 4xxPríspevok sa označí ako neúspešný s vašou správou a niekto ho môže opraviť a stlačiť Zopakovať.

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áš koncový bod musí byť dostupný z internetu; presmerovania sa nesledujú. Pri pripojení kanála ho Amaposta overí požiadavkou GET na URL kontroly dostupnosti, ak ste ju nastavili, alebo požiadavkou OPTIONS na koncový bod.

Kanál sandbox sa správa ako skutočný, ale nič neopustí Amaposta. Použite ho na vytvorenie a úplné otestovanie integrácie: príspevky sa plánujú, spúšťajú, publikujú alebo zlyhajú a vyvolávajú rovnaké webhooky. Kanály sandbox sú bezplatné pri každom pláne a nezapočítavajú sa do limitu kanálov.

Vyberte, ako sa má po pridaní správať:

• Vždy uspieťKaždý príspevok sa publikuje.
• Občas zlyhaťPozrite si zlyhania a opakované pokusy bez čakania na skutočný výpadok.
• Vždy zlyhaťOtestujte spracovanie post.failed.
• Pripojenie s vypršanou platnosťouPozrite si upozornenia a odkazy na opätovné pripojenie pri skončení platnosti prístupu.

X účtuje každé volanie API vrátane každého príspevku vývojárskej aplikácii, ktorá ho vykonáva, a platbu odpočíta z jej predplatených kreditov. Preto X pripájate cez vlastnú vývojársku aplikáciu X: nastavte ju raz pre každý pracovný priestor a potom pripojte ľubovoľný počet účtov X. Každý účet sa prihlási na X a jeho príspevky sa platia z kreditov vašej aplikácie.

1. Prihláste sa na console.x.com pomocou účtu X, ktorému má aplikácia patriť, napríklad účtu vašej agentúry, a vytvorte aplikáciu.
2. Otvorte User authentication settings aplikácie a zadajte:
   • App permissionsRead and write
   • Type of AppWeb App, Automated App or Bot
   • Callback URI / Redirect URLhttps://www.amaposta.com/oauth/x/callback
   • Website URLVaša webová stránka

   Potom nastavenia uložte. Tajný kľúč klienta, pomocou ktorého sa Amaposta prihlasuje, dostane iba tento typ aplikácie.

3. Skopírujte OAuth 2.0 Client ID a Client Secret, ktoré X zobrazí po uložení. Nepoužívajte API Key, API Key Secret ani Bearer Token: tie sú určené na iné druhy prístupu. X zobrazí tajný kľúč iba raz.
4. V konzole X si kúpte kredity API. Automatické dobíjanie umožní pokračovať v publikovaní, keď sa kredity míňajú; limit výdavkov obmedzí náklady. Keď kredity dôjdu, X odmieta príspevky, kým nedokúpite ďalšie.
5. V Amaposta otvorte Kanály projektu, vyberte Pripojiť kanál a potom X. Vložte ID klienta a tajný kľúč klienta, pokračujte na X, prihláste sa účtom, ktorý chcete pripojiť, a povoľte prístup.

Dobré vedieť

• Aplikácia sa uloží pre celý pracovný priestor a jej tajný kľúč sa zašifruje. Každý ďalší účet X pripojíte jedným kliknutím z ľubovoľného projektu.
• Kanály si ponechávajú aplikáciu, cez ktorú boli pripojené. Opätovné pripojenie kanála, aj cez odkaz na opätovné pripojenie pre klienta, znova použije túto aplikáciu; váš klient ju nikdy neuvidí.
• Ak chcete zmeniť aplikáciu, pri pripájaní X vyberte „Použiť inú aplikáciu“. Ak znova vygenerujete Client Secret, zadajte tam nový a opätovne pripojte svoje kanály X.
• Konzola X vydáva tokeny iba pre účet, ktorý aplikáciu vlastní. Účty svojich klientov pripojíte prihlásením cez svoju aplikáciu; ručné zadanie tokenov naďalej funguje pre váš vlastný účet.