Kūrėjų vadovas

Autentifikavimas

Sukurkite API raktą valdymo skydelio nustatymų skiltyje „API ir webhook“. Raktai prasideda ss_live_, priklauso vienai darbo erdvei ir gali būti apriboti tam tikrais projektais. Kiekvienoje užklausoje siųskite raktą kaip bearer prieigos raktą:

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

Atsakyme nurodomas raktas, jo teisės ir darbo erdvė. Kiekvienas raktas turi vieną ar daugiau teisių:

Kiekvienas raktas gali pateikti 120 užklausų per minutę. Viršijus limitą grąžinamas 429 su kodu rate_limited; šiek tiek palaukite ir bandykite dar kartą.

Projektai ir kanalai

Įrašai priklauso projektui. Gaukite raktui matomų projektų sąrašą, tada vieno iš jų kanalus. Norėdami pasirinkti kanalą ar pakeisti jo tekstą, turėsite nurodyti jo 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"

Kanalas turi provider (youtube, instagram, tiktok, x, facebook, custom arba sandbox), status (active, expiring, needs_reconnect, error arba disabled) ir palaikomus įrašų tipus supports.

Įkelti mediją

Paveikslėliai ir vaizdo įrašai įkeliami vieną kartą kiekvienam projektui ir gali būti naudojami bet kokiame skaičiuje įrašų. Yra trys įkėlimo būdai.

Tiesioginis įkėlimas

Siųskite failą kaip multipart formos duomenis lauke file. Geriausiai tinka failams iki kelių šimtų MB.

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

Iš anksto pasirašytas didelių failų įkėlimas

Paprašykite įkėlimo URL, siųskite baitus tiesiai į saugyklą PUT užklausa, tada praneškite Amaposta, kad baigėte.

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

Importuoti iš URL

Pateikite Amaposta viešą URL ir ji atsisiųs failą fone. Taip pat galite praleisti šį veiksmą ir kurdami įrašą pateikti 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"}'

Kiekvienas įkėlimas grąžina medijos objektą. Jo status keičiasi iš pending į processing, tada į ready (arba failed su error). Apdorojus pateikiami width, height, duration_ms ir miniatiūra. Periodiškai kvieskite GET /api/v1/media/{id} arba laukite media.ready webhook pranešimo. Grąžinamas url yra pasirašytas ir galioja 12 valandų.

Sukurti įrašą

POST /api/v1/projects/{project_id}/posts sukuria vieną įrašą su pristatymu kiekvienam kanalui. Amaposta jį pritaiko kiekvienai platformai: pavadinimai siunčiami tik ten, kur yra pavadinimo laukas, grotažymės YouTube tampa žymomis, o kitur – teksto dalimi.

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

Laukai

Atsakymas yra įrašas su po vieną deliveries elementą kiekvienam kanalui.

Saugūs pakartotiniai bandymai

Tinkle užklausos gali pasimesti. Kurdami įrašą siųskite Idempotency-Key antraštę; pakartojus užklausą su tuo pačiu raktu grąžinamas pirmojo bandymo įrašas, užuot sukūrus antrą. Naudokite pastovią savo sistemos reikšmę, pvz., užduoties ar epizodo ID. Raktai trumpinami iki 200 ženklų.

Planuoti ir publikuoti

Suplanuokite juodraštį, publikuokite dabar, pridėkite į eilę arba pašalinkite iš kalendoriaus naudodami 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"}'

• atPublikuoja nurodytu laiku, iki dvejų metų į priekį.
• nowPublikuoja iš karto.
• queueParenka kitą laisvą įrašo kanalų publikavimo laiką per artimiausias 12 savaičių.
• unscheduleGrąžina įrašą į juodraščius.

Prieš planuojant atliekamos tos pačios patikros kaip rengyklėje. Jei kuri nors nepavyksta, užklausa grąžina 400 su pranešimu, pvz., Prieš planuodami ištaisykite: YouTube reikia pavadinimo. Planavimui reikia posts:publish teisės arba projekto su įjungtu tvirtinimu; tokiu atveju įrašas laukia peržiūros dėžutėje.

Skaityti įrašus ir pristatymus

Pateikite projekto įrašų sąrašą, filtruojamą pagal status (kableliais atskirtas būsenas arba inbox, queue ar history), from/to intervalą, limit ir offset. Atsakymas: {"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"

Įrašas turi bendrą status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial arba failed) ir po vieną pristatymą kiekvienam kanalui:

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

Pristatymo būsenos: pending, scheduled, publishing, processing, published, failed ir cancelled. DELETE /api/v1/posts/{post_id} pašalina įrašą.

Klaidos

Visos klaidos turi tą pačią struktūrą: error objektą su pastoviu code, žmonėms rodomu message, kartais fields (atskirų laukų pranešimais) ir hint.

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

Webhook pranešimai

Nustatymų skiltyje „API ir webhook“ pridėkite galinį tašką, pasirinkite norimus įvykius ir nukopijuokite jo pasirašymo paslaptį. Kiekvienam įvykiui Amaposta siunčia JSON POST užklausą į jūsų URL. Jei atsakymas nėra 2xx arba negaunamas per 15 sekundžių, bandoma dar kartą didinant intervalus, o nuolat neveikiantys galiniai taškai išjungiami ir apie tai pranešama administratoriams.

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

Patikrinti parašą

X-Amaposta-Signature yra t=<unix seconds>,v1=<hex>, kur v1 yra HMAC_SHA256(secret, t + "." + body), apskaičiuotas iš neapdoroto užklausos turinio. Apskaičiuokite jį patys, palyginkite pastoviu laiku ir atmeskite senas laiko žymas, kad užklausų nebūtų galima pakartoti.

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

Pasirinktinės API kanalas publikuoja į jūsų valdomą HTTPS galinį tašką: jūsų TVS, naujienlaiškių įrankį ar platformą, kurios Amaposta dar nepalaiko. Jis rodomas kalendoriuje, tikrinamas, tvirtinamas ir pakartotinai bandomas kaip bet kuris kitas kanalas. Publikuojant įrašą, Amaposta siunčia vieną POST užklausą kiekvienam pristatymui:

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

Jūsų API raktas. Antraštės pavadinimas ir priešdėlis (pagal numatytuosius nustatymus Bearer) nustatomi kanale.

Idempotency-Key

Pristatymo ID. Kartojant tą patį pristatymą siunčiamas tas pats raktas, todėl galite praleisti jau atliktą darbą.

X-Amaposta-Delivery

Pristatymo ID dar kartą, jūsų žurnalams.

X-Amaposta-Signature

Pasirašoma kaip webhook pranešimai, naudojant atskirą kanalo pasirašymo paslaptį.

Kaip atsakyti

• 2xxPublikuota. Pasirinktinai grąžinkite {"id": "…", "url": "…"} ir nuoroda bus rodoma įraše.
• 401, 403Raktas atmestas. Kanalas pažymimas pakartotiniam prijungimui ir apie tai pranešama administratoriams. Nenaudokite šių kodų neteisingam parašui.
• 5xx, 408, 429Laikina. Amaposta bando dar kartą didindama intervalus.
• Kiti 4xxĮrašas pažymimas kaip nepavykęs su jūsų pranešimu, o kas nors gali jį pataisyti ir paspausti „Bandyti dar kartą“.

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

Jūsų galinis taškas turi būti pasiekiamas internetu; peradresavimų nesekama. Prijungiant kanalą Amaposta jį patikrina GET užklausa į veikimo patikros URL, jei jis nustatytas, arba OPTIONS užklausa į galinį tašką.

Bandomasis kanalas veikia kaip tikras, bet niekas neišsiunčiama iš Amaposta. Naudokite jį integracijai kurti ir visapusiškai išbandyti: įrašai planuojami, pradedami publikuoti, publikuojami arba nepavyksta, ir siunčiami tie patys webhook pranešimai. Bandomieji kanalai nemokami visuose planuose ir neįskaičiuojami į kanalų limitus.

Pasirinkite, kaip jis veiks jį pridėjus:

• Visada pavykstaKiekvienas įrašas publikuojamas.
• Kartais nepavykstaPamatykite klaidas ir pakartotinius bandymus nelaukdami tikro sutrikimo.
• Visada nepavykstaIšbandykite savo post.failed apdorojimą.
• Nebegaliojantis ryšysPamatykite, kaip atrodo pakartotinio prijungimo įspėjimai ir nuorodos pasibaigus prieigai.

X kiekvieno API iškvietimo, įskaitant kiekvieną įrašo publikavimą, mokestį priskiria jį atlikusiai kūrėjo programėlei ir nuskaičiuoja iš jos iš anksto apmokėtų kreditų. Todėl X prijungiate per savo X kūrėjo programėlę: nustatykite ją vieną kartą kiekvienai darbo erdvei, tada prijunkite tiek X paskyrų, kiek norite. Prie kiekvienos paskyros prisijungiama X platformoje, o už jos įrašus mokama iš jūsų programėlės kreditų.

1. Prisijunkite adresu console.x.com su X paskyra, kuriai turėtų priklausyti programėlė, pavyzdžiui, jūsų agentūros paskyra, ir sukurkite programėlę.
2. Atverkite programėlės User authentication settings ir įveskite:
   • App permissionsRead and write
   • Type of AppWeb App, Automated App or Bot
   • Callback URI / Redirect URLhttps://www.amaposta.com/oauth/x/callback
   • Website URLJūsų svetainė

   Tada išsaugokite. Tik šio tipo programėlė gauna kliento slaptąjį raktą, kurį Amaposta naudoja prisijungimui.

3. Nukopijuokite OAuth 2.0 Client ID ir Client Secret, kuriuos X parodo išsaugojus. Nenaudokite API Key, API Key Secret ar Bearer Token: jie skirti kitų rūšių prieigai. X slaptąjį raktą parodo tik vieną kartą.
4. X konsolėje įsigykite API kreditų. Automatinis papildymas leidžia toliau publikuoti įrašus, kai kreditų lieka mažai; išlaidų limitas apriboja sąnaudas. Kai kreditai baigiasi, X neleidžia publikuoti, kol jų nepapildote.
5. Amaposta atidarykite projekto skiltį Kanalai, pasirinkite Prijungti kanalą, tada X. Įklijuokite kliento ID ir kliento slaptąjį raktą, pereikite į X, prisijunkite prie paskyros, kurią norite prijungti, ir suteikite prieigą.

Verta žinoti

• Programėlė išsaugoma visai darbo erdvei, o jos slaptasis raktas užšifruojamas. Kiekvieną kitą X paskyrą galima prijungti vienu spustelėjimu iš bet kurio projekto.
• Kanalai išlaiko programėlę, per kurią buvo prijungti. Iš naujo prijungiant kanalą, taip pat ir per klientui skirtą pakartotinio prijungimo nuorodą, vėl naudojama ta pati programėlė; jūsų klientas jos niekada nemato.
• Norėdami pakeisti programėlę, prijungdami X pasirinkite „Naudoti kitą programėlę“. Jei iš naujo sugeneruosite Client Secret, ten įveskite naują reikšmę ir iš naujo prijunkite savo X kanalus.
• X konsolė išduoda prieigos raktus tik paskyrai, kuriai priklauso programėlė. Savo klientų paskyras prijungiate prisijungdami per savo programėlę; savo paskyrai ir toliau galite įvesti prieigos raktus rankiniu būdu.