Izstrādātāju ceļvedis

Autentifikācija

Izveido API atslēgu vadības paneļa iestatījumu sadaļā “API un tīmekļa aizķeres”. Atslēgas sākas ar ss_live_, pieder vienai darbvietai, un to piekļuvi var ierobežot līdz noteiktiem projektiem. Nosūti atslēgu kā nesēja tokenu katrā pieprasījumā:

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

Atbilde norāda atslēgas nosaukumu, tās tvērumus un darbvietu. Katrai atslēgai ir viens vai vairāki tvērumi:

Katra atslēga var veikt 120 pieprasījumus minūtē. Pārsniedzot šo limitu, saņemsi 429 ar kodu rate_limited; nedaudz uzgaidi un mēģini vēlreiz.

Projekti un kanāli

Ieraksti atrodas projektā. Uzskaiti projektus, ko tava atslēga redz, un pēc tam kāda projekta kanālus. Kanāla ID būs nepieciešams, lai to izvēlētos vai pārrakstītu tā tekstu.

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ālam ir provider (youtube, instagram, tiktok, x, facebook, custom vai sandbox), status (active, expiring, needs_reconnect, error vai disabled) un ierakstu veidi, kurus tas supports.

Augšupielādēt multividi

Attēlus un videoklipus augšupielādē vienreiz katram projektam, un tos var izmantot neierobežotā skaitā ierakstu. Ir trīs veidi, kā tos pievienot.

Tieša augšupielāde

Nosūti failu kā multipart formas datus laukā ar nosaukumu file. Vispiemērotāk failiem līdz dažiem simtiem MB.

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

Iepriekš parakstīta augšupielāde lieliem failiem

Pieprasi augšupielādes URL, nosūti baitus tieši uz krātuvi ar PUT un pēc tam paziņo Amaposta, ka esi pabeidzis.

# 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ēt no URL

Norādi Amaposta publisku URL, un tā lejupielādēs failu fonā. Vari arī izlaist šo soli un norādīt media_url, veidojot ierakstu.

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

Katra augšupielāde atgriež multivides objektu. Tā status mainās no pending uz processing un pēc tam uz ready (vai failed ar error). Pēc apstrādes tam ir width, height, duration_ms un sīktēls. Periodiski pieprasi GET /api/v1/media/{id} vai klausies media.ready tīmekļa aizķeres notikumu. Atgrieztais url ir parakstīts un derīgs 12 stundas.

Izveidot ierakstu

POST /api/v1/projects/{project_id}/posts izveido vienu ierakstu ar piegādi katram kanālam. Amaposta pielāgo to katrai platformai: virsraksti tiek izmantoti tikai tur, kur ir virsraksta lauks, tēmturi kļūst par atzīmēm YouTube un par daļu no teksta citur.

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

Lauki

Atbilde ir ieraksts, ieskaitot vienu vienumu laukā deliveries katram kanālam.

Droši atkārtoti mēģinājumi

Tīklos pieprasījumi mēdz pazust. Veidojot ierakstu, nosūti Idempotency-Key galveni; atkārtots pieprasījums ar to pašu atslēgu atgriezīs pirmajā mēģinājumā izveidoto ierakstu, nevis izveidos otru. Izmanto savā pusē nemainīgu vērtību, piemēram, uzdevuma vai epizodes ID. Atslēgas tiek saīsinātas līdz 200 rakstzīmēm.

Ieplānot un publicēt

Ieplāno melnrakstu, publicē to tagad, pievieno rindai vai noņem no kalendāra ar 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"}'

• atPublicē norādītajā laikā līdz diviem gadiem uz priekšu.
• nowPublicē uzreiz.
• queueIzmanto ieraksta kanālu nākamo brīvo publicēšanas laiku nākamajās 12 nedēļās.
• unschedulePārvieto ierakstu atpakaļ uz melnrakstiem.

Pirms ieplānošanas tiek veiktas tās pašas pārbaudes, kas redaktorā. Ja kāda neizdodas, pieprasījums atgriež 400 ar paziņojumu, piemēram, Novērs šo problēmu pirms ieplānošanas: YouTube nepieciešams virsraksts. Ieplānošanai vajadzīgs posts:publish tvērums vai projekts ar ieslēgtu apstiprināšanu; tādā gadījumā ieraksts gaida pārskatīšanas iesūtnē.

Lasīt ierakstus un piegādes

Uzskaiti projekta ierakstus, filtrējot pēc status (ar komatiem atdalīti statusi vai inbox, queue vai history), from/to perioda, limit un offset. Atbilde ir {"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"

Ierakstam ir kopējais status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial vai failed) un viena piegāde katram kanālam:

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

Piegādes statusi ir pending, scheduled, publishing, processing, published, failed un cancelled. DELETE /api/v1/posts/{post_id} dzēš ierakstu.

Kļūdas

Visām kļūdām ir vienāda struktūra: error objekts ar nemainīgu code, cilvēkiem parādāmu message un dažreiz arī fields (paziņojumi par atsevišķiem laukiem) un hint.

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

Tīmekļa aizķeres

Iestatījumu sadaļā “API un tīmekļa aizķeres” pievieno galapunktu, izvēlies vajadzīgos notikumus un nokopē tā parakstīšanas noslēpumu. Katram notikumam Amaposta nosūta JSON uz tavu URL ar POST. Ja atbilde nav 2xx vai tā netiek saņemta 15 sekunžu laikā, pieprasījums tiek atkārtots ar pieaugošu intervālu. Galapunkti, kuros kļūmes turpinās, tiek izslēgti, paziņojot administratoriem.

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

Pārbaudīt parakstu

X-Amaposta-Signature ir t=<unix seconds>,v1=<hex>, kur v1 ir HMAC_SHA256(secret, t + "." + body), ko aprēķina no neapstrādātā pieprasījuma satura. Aprēķini to pats, salīdzini konstantā laikā un noraidi vecus laika zīmogus, lai novērstu atkārtotu pieprasījumu uzbrukumus.

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

Pielāgotās API kanāls publicē tavā HTTPS galapunktā: tavā CMS, jaunumu vēstuļu rīkā vai platformā, kuru Amaposta vēl neatbalsta. Tas ir redzams kalendārā, saņem pārbaudes, apstiprinājumus un atkārtotus mēģinājumus tāpat kā jebkurš cits kanāls. Publicējot ierakstu, Amaposta nosūta vienu POST katrai piegādei:

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

Tava API atslēga. Galvenes nosaukums un prefikss (Bearer pēc noklusējuma) tiek iestatīti kanālā.

Idempotency-Key

Piegādes ID. Atkārtojot to pašu piegādi, tiek sūtīta tā pati atslēga, lai varētu izlaist jau paveikto darbu.

X-Amaposta-Delivery

Piegādes ID vēlreiz tavai uzskaitei.

X-Amaposta-Signature

Parakstīts tāpat kā tīmekļa aizķeres, izmantojot kanāla parakstīšanas noslēpumu.

Kā atbildēt

• 2xxPublicēts. Pēc izvēles atgriez {"id": "…", "url": "…"}, un saite parādīsies ierakstā.
• 401, 403Atslēga tika noraidīta. Kanāls tiek atzīmēts atkārtotai pievienošanai, un administratori saņem paziņojumu. Neizmanto šos statusus nederīga paraksta gadījumā.
• 5xx, 408, 429Pārejoša kļūme. Amaposta atkārto mēģinājumus ar pieaugošu intervālu.
• Citi 4xxIeraksts tiek atzīmēts kā neizdevies ar tavu paziņojumu, un kāds var to izlabot un nospiest “Mēģināt vēlreiz”.

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

Tavam galapunktam jābūt sasniedzamam no interneta; pāradresācijas netiek ievērotas. Pievienojot kanālu, Amaposta to pārbauda ar GET uz darbspējas URL, ja tāds norādīts, vai ar OPTIONS pieprasījumu uz galapunktu.

Smilškastes kanāls darbojas kā īsts kanāls, taču nekas netiek nosūtīts ārpus Amaposta. Izmanto to, lai izveidotu un pilnībā pārbaudītu integrāciju: ieraksti tiek ieplānoti, sāk publicēties, tiek publicēti vai neizdodas un izraisa tos pašus tīmekļa aizķeres notikumus. Smilškastes kanāli ir bez maksas visos plānos un netiek ieskaitīti kanālu limitā.

Pievienojot izvēlies, kā tas darbosies:

• Vienmēr izdodasVisi ieraksti tiek publicēti.
• Ik pa laikam neizdodasApskati kļūmes un atkārtotus mēģinājumus, negaidot īstu darbības pārtraukumu.
• Vienmēr neizdodasPārbaudi savu post.failed apstrādi.
• Savienojuma derīgums beidziesApskati brīdinājumus un saites atkārtotai pievienošanai, kad piekļuves derīgums beidzas.

X maksu par katru API izsaukumu, tostarp katru publikāciju, piemēro izstrādātāja lietotnei, kas to veic, un ietur no tās priekšapmaksas kredītiem. Tāpēc X pievieno, izmantojot savu X izstrādātāja lietotni: iestati to katrai darbvietai vienu reizi un pēc tam pievieno tik X kontu, cik vēlies. Katrā kontā jāpierakstās X platformā, un maksa par tā publikācijām tiek ieturēta no tavas lietotnes kredītiem.

1. Pieraksties vietnē console.x.com ar X kontu, kuram jāpieder lietotnei, piemēram, savas aģentūras kontu, un izveido lietotni.
2. Atver lietotnes User authentication settings un ievadi:
   • App permissionsRead and write
   • Type of AppWeb App, Automated App or Bot
   • Callback URI / Redirect URLhttps://www.amaposta.com/oauth/x/callback
   • Website URLTava vietne

   Pēc tam saglabā. Tikai šī veida lietotne saņem klienta slepeno atslēgu, ko Amaposta izmanto, lai pierakstītos.

3. Nokopē OAuth 2.0 Client ID un Client Secret, ko X parāda pēc saglabāšanas. Neizmanto API Key, API Key Secret vai Bearer Token: tie paredzēti citiem piekļuves veidiem. X slepeno atslēgu parāda tikai vienreiz.
4. Iegādājies API kredītus X konsolē. Automātiskā papildināšana ļauj turpināt publicēšanu, kad kredīti tuvojas beigām; tēriņu limits ierobežo izmaksas. Kad kredīti beidzas, X noraida publikācijas, līdz papildini atlikumu.
5. Amaposta atver projekta sadaļu Kanāli, izvēlies Pievienot kanālu un pēc tam X. Ielīmē klienta ID un klienta slepeno atslēgu, turpini uz X, pieraksties kontā, kuru vēlies pievienot, un atļauj piekļuvi.

Noderīgi zināt

• Lietotne tiek saglabāta visai darbvietai, un tās slepenā atslēga tiek šifrēta. Katru nākamo X kontu var pievienot ar vienu klikšķi no jebkura projekta.
• Kanāli saglabā lietotni, ar kuru tie tika pievienoti. Atkārtoti pievienojot kanālu, arī ar klientam paredzētu atkārtotas pievienošanas saiti, tiek izmantota tā pati lietotne; tavs klients to nekad neredz.
• Lai mainītu lietotni, pievienojot X, izvēlies “Izmantot citu lietotni”. Ja izveido jaunu Client Secret, ievadi to tur un atkārtoti pievieno savus X kanālus.
• X konsole izsniedz tokenus tikai kontam, kuram pieder lietotne. Klientu kontus pievieno, pierakstoties ar savu lietotni; savam kontam joprojām vari ievadīt tokenus manuāli.