Fejlesztői útmutató

Hitelesítés

Hozz létre API-kulcsot a kezelőfelületen, a Beállítások, API és webhookok alatt. A kulcsok ss_live_ előtaggal kezdődnek, egy munkaterülethez tartoznak, és meghatározott projektekre korlátozhatók. A kulcsot minden kérésnél bearer tokenként küldd:

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

A válasz megadja a kulcs nevét, jogosultsági köreit és a munkaterületet. Minden kulcsnak egy vagy több jogosultsági köre van:

Minden kulcs percenként 120 kérést küldhet. E fölött 429 választ kapsz rate_limited kóddal; várj egy kicsit, és próbáld újra.

Projektek és csatornák

A bejegyzések egy projektben találhatók. Listázd a kulcsoddal elérhető projekteket, majd az egyik projekt csatornáit. A célzáshoz vagy a szöveg felülírásához szükséged lesz a csatorna azonosítójára.

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"

A csatornának van provider mezője (youtube, instagram, tiktok, x, facebook, custom vagy sandbox), status mezője (active, expiring, needs_reconnect, error vagy disabled), valamint az általa támogatott bejegyzéstípusokat tartalmazó supports mezője.

Média feltöltése

A képeket és videókat projektenként egyszer kell feltölteni, és tetszőleges számú bejegyzésben használhatók. Három módon tölthetsz fel.

Közvetlen feltöltés

Küldd a fájlt multipart űrlapadatként egy file nevű mezőben. Leginkább néhány száz MB-ig ajánlott.

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

Előre aláírt feltöltés nagy fájlokhoz

Kérj feltöltési URL-t, küldd a bájtokat PUT-kéréssel közvetlenül a tárhelyre, majd jelezd az Amapostának, hogy elkészültél.

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

Importálás URL-ről

Adj meg az Amapostának egy nyilvános URL-t, és a háttérben letölti a fájlt. Ezt a lépést ki is hagyhatod, és a bejegyzés létrehozásakor megadhatod a media_url mezőt.

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

Minden feltöltés egy médiaobjektumot ad vissza. A status értéke pending állapotból processing, majd ready állapotba lép (vagy failed lesz, egy error mezővel). Feldolgozás után tartalmazza a width, height, duration_ms mezőt és egy bélyegképet. Kérdezd le rendszeresen a GET /api/v1/media/{id} végpontot, vagy figyeld a media.ready webhookot. A visszaadott url aláírt, és 12 óráig érvényes.

Bejegyzés létrehozása

A POST /api/v1/projects/{project_id}/posts egy bejegyzést hoz létre, csatornánként egy kézbesítéssel. Az Amaposta platformonként alakítja a tartalmat: a címek csak oda kerülnek, ahol van címmező, a hashtagek a YouTube-on címkékké, máshol szövegközi tartalommá válnak.

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

Mezők

A válasz maga a bejegyzés, a deliveries mezőben csatornánként egy bejegyzéssel.

Biztonságos újrapróbálás

A hálózatok elveszíthetnek kéréseket. A bejegyzés létrehozásakor küldj Idempotency-Key fejlécet: ugyanazzal a kulccsal az újrapróbálás az első próbálkozás bejegyzését adja vissza ahelyett, hogy újat hozna létre. Használj a saját oldaladon állandó értéket, például feladat- vagy epizódazonosítót. A kulcsokat 200 karakterre vágjuk.

Időzítés és közzététel

Időzíts piszkozatot, tedd közzé azonnal, add a várólistához, vagy vedd le a naptárról a POST /api/v1/posts/{post_id}/schedule végponttal.

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

• atA megadott időpontban teszi közzé, legfeljebb két évre előre.
• nowAzonnal közzéteszi.
• queueA bejegyzés csatornáinak következő szabad közzétételi idősávját foglalja le a következő 12 hétben.
• unscheduleVisszahelyezi a bejegyzést a piszkozatok közé.

Az időzítés előtt ugyanazok az ellenőrzések futnak le, mint a szerkesztőben. Ha valamelyik sikertelen, a kérés 400 választ ad, például ezzel az üzenettel: Időzítés előtt javítsd: a YouTube-hoz cím szükséges. Az időzítéshez posts:publish jogosultsági kör vagy bekapcsolt jóváhagyású projekt szükséges; az utóbbi esetben a bejegyzés az ellenőrzési beérkezők között várakozik.

Bejegyzések és kézbesítések olvasása

Listázd egy projekt bejegyzéseit status alapján szűrve (vesszővel elválasztott állapotok, vagy inbox, queue, illetve history), from/to időablakkal, limit és offset értékkel. A válasz: {"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"

A bejegyzésnek van összesített status értéke (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial vagy failed) és csatornánként egy kézbesítése:

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

A kézbesítési állapotok: pending, scheduled, publishing, processing, published, failed és cancelled. A DELETE /api/v1/posts/{post_id} eltávolít egy bejegyzést.

Hibák

Minden hiba szerkezete azonos: egy error objektum állandó code értékkel, felhasználóknak megjeleníthető message üzenettel, és esetenként fields (mezőnkénti üzenetek) és hint mezővel.

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

Webhookok

Adj hozzá végpontot a Beállítások, API és webhookok alatt, válaszd ki a kívánt eseményeket, és másold ki az aláírási titkát. Az Amaposta minden eseménynél JSON-t küld POST-kéréssel az URL-edre. A 2xx-től eltérő választ vagy a 15 másodpercen belüli válasz hiányát növekvő várakozással újrapróbáljuk; a tartósan hibás végpontokat kikapcsoljuk, és értesítjük az adminisztrátorokat.

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

Az aláírás ellenőrzése

Az X-Amaposta-Signature értéke t=<unix seconds>,v1=<hex>, ahol a v1 a nyers kéréstörzsön számított HMAC_SHA256(secret, t + "." + body). Számítsd ki magad, állandó időben hasonlítsd össze, és utasítsd el a régi időbélyegeket az ismételt lejátszások megakadályozására.

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

Egy egyéni API-csatorna egy általad üzemeltetett HTTPS-végpontra tesz közzé: a CMS-edbe, egy hírlevélküldőbe vagy egy, az Amaposta által még nem támogatott platformra. A többi csatornához hasonlóan megjelenik a naptárban, ellenőrzéseket, jóváhagyásokat és újrapróbálást kap. A közzétételkor az Amaposta kézbesítésenként egy POST-kérést küld:

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

Az API-kulcsod. A fejléc nevét és az előtagot (alapértelmezetten Bearer) a csatornán állítod be.

Idempotency-Key

A kézbesítés azonosítója. Ugyanazon kézbesítés újrapróbálása ugyanazt a kulcsot küldi, így kihagyhatod a már elvégzett munkát.

X-Amaposta-Delivery

Újra a kézbesítés azonosítója, a naplóidhoz.

X-Amaposta-Signature

A webhookokhoz hasonlóan aláírva, a csatorna saját aláírási titkával.

Hogyan válaszolj

• 2xxKözzétéve. Opcionálisan adj vissza {"id": "…", "url": "…"} választ, és a hivatkozás megjelenik a bejegyzésen.
• 401, 403A kulcsot elutasították. A csatornát újracsatlakoztatandónak jelöljük, és értesítjük az adminisztrátorokat. Hibás aláíráshoz ne használd ezeket.
• 5xx, 408, 429Átmeneti hiba. Az Amaposta növekvő várakozással újrapróbálja.
• Egyéb 4xxA bejegyzést sikertelennek jelöljük az üzeneteddel, és valaki javíthatja, majd az Újrapróbálás gombra kattinthat.

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

A végpontodnak elérhetőnek kell lennie az internetről; az átirányításokat nem követjük. A csatorna összekapcsolásakor az Amaposta GET-kéréssel ellenőrzi a megadott állapotellenőrzési URL-t, ha van ilyen, egyébként OPTIONS-kérést küld a végpontra.

A sandbox-csatorna valódi csatornaként viselkedik, de semmi sem hagyja el az Amapostát. Építsd meg és teszteld vele az integrációdat elejétől a végéig: a bejegyzések időzíthetők, adásba kerülnek, megjelennek vagy meghiúsulnak, és ugyanazokat a webhookokat váltják ki. A Sandbox-csatornák minden csomagban ingyenesek, és nem számítanak bele a csatornakorlátba.

Hozzáadáskor válaszd ki a viselkedését:

• Mindig sikeresMinden bejegyzés megjelenik.
• Időnként sikertelenFigyeld meg a hibákat és az újrapróbálást valódi kimaradás nélkül.
• Mindig sikertelenTeszteld a post.failed kezelését.
• Lejárt kapcsolatNézd meg az újracsatlakozási értesítéseket és hivatkozásokat a hozzáférés lejártakor.