Arendaja juhend

Autentimine

Loo API-võti töölaual seadete jaotises „API ja veebihaagid”. Võtmed algavad märgiga ss_live_, kuuluvad ühte tööruumi ja neid saab piirata kindlate projektidega. Saada võti iga päringuga bearer-pääsutõendina:

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

Vastus sisaldab võtme nime, selle õigusulatusi ja tööruumi. Igal võtmel on üks või mitu õigusulatust:

Iga võti saab teha 120 päringut minutis. Selle ületamisel saad vastuse 429 koodiga rate_limited; oota hetk ja proovi uuesti.

Projektid ja kanalid

Postitused asuvad projektis. Kuva projektid, mida sinu võti näeb, ja seejärel ühe projekti kanalid. Kanali sihtimiseks või selle teksti kohandamiseks vajad kanali ID-d.

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"

Kanalil on provider (youtube, instagram, tiktok, x, facebook, custom või sandbox), status (active, expiring, needs_reconnect, error või disabled) ja toetatud postituseliigid väljal supports.

Laadi meedia üles

Pildid ja videod laaditakse üles üks kord projekti kohta ning neid saab kasutada piiramatul arvul postitustes. Lisamiseks on kolm viisi.

Otseüleslaadimine

Saada fail multipart-vormiandmetena väljal nimega file. Sobib kõige paremini kuni mõnesaja MB suurustele failidele.

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

Eelallkirjastatud üleslaadimine suurtele failidele

Küsi üleslaadimis-URL, saada baidid PUT-päringuga otse salvestusruumi ja anna seejärel Amapostale teada, et oled lõpetanud.

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

Impordi URL-ilt

Anna Amapostale avalik URL ja see laadib faili taustal alla. Võid selle sammu ka vahele jätta ja postituse loomisel edastada välja 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"}'

Iga üleslaadimine tagastab meediaobjekti. Selle status liigub olekust pending olekusse processing ja sealt ready (või failed, koos väljaga error). Pärast töötlemist sisaldab see välju width, height, duration_ms ja pisipilti. Päri regulaarselt GET /api/v1/media/{id} või kuula veebihaaki media.ready. Tagastatav url on allkirjastatud ja kehtib 12 tundi.

Loo postitus

POST /api/v1/projects/{project_id}/posts loob ühe postituse koos iga kanali edastusega. Amaposta kohandab seda platvormi järgi: pealkirjad saadetakse ainult sinna, kus on pealkirjaväli, teemaviited muutuvad YouTube'is siltideks ja mujal tekstisiseseks tekstiks.

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

Väljad

Vastus on postitus, sealhulgas üks kirje väljal deliveries iga kanali kohta.

Turvalised korduskatsed

Võrgus lähevad päringud vahel kaotsi. Saada postituse loomisel päis Idempotency-Key ning sama võtmega korduskatse tagastab uue postituse loomise asemel esimesel katsel loodud postituse. Kasuta oma poolelt midagi püsivat, näiteks töö või episoodi ID-d. Võtmed kärbitakse 200 tähemärgini.

Ajasta ja avalda

Ajasta mustand, avalda see kohe, lisa järjekorda või eemalda kalendrist päringuga 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"}'

• atAvaldab määratud ajal, kuni kaks aastat ette.
• nowAvaldab kohe.
• queueValib postituse kanalite järgmise vaba avaldamisaja järgneva 12 nädala jooksul.
• unscheduleViib postituse tagasi mustanditesse.

Enne ajastamist tehakse samad kontrollid nagu koostajas. Kui mõni neist nurjub, tagastab päring 400 koos sõnumiga nagu Paranda enne ajastamist: YouTube vajab pealkirja. Ajastamiseks on vaja õigust posts:publish või projekti, kus kinnitamine on sisse lülitatud; viimasel juhul ootab postitus ülevaatuste postkastis.

Loe postitusi ja edastusi

Kuva projekti postitused, filtreerides välja status järgi (komadega eraldatud olekud või inbox, queue või history), ajavahemiku from/to ning väljade limit ja offset järgi. Vastus on {"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"

Postitusel on üldine status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial või failed) ning iga kanali kohta üks edastus:

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

Edastuse olekud on pending, scheduled, publishing, processing, published, failed ja cancelled. DELETE /api/v1/posts/{post_id} eemaldab postituse.

Vead

Kõigil vigadel on sama kuju: objekt error püsiva väljaga code, inimestele näidatava väljaga message ja vahel ka väljadega fields (väljade kaupa sõnumid) ning hint.

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

Veebihaagid

Lisa seadete jaotises „API ja veebihaagid” lõpp-punkt, vali soovitud sündmused ja kopeeri selle allkirjastamissaladus. Amaposta saadab iga sündmuse kohta sinu URL-ile JSON-i POST-päringuga. Kui vastus pole 2xx või vastust ei tule 15 sekundi jooksul, proovitakse kasvavate vahedega uuesti. Pidevalt nurjuvad lõpp-punktid lülitatakse välja ja administraatoreid teavitatakse.

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

Kontrolli allkirja

X-Amaposta-Signature on t=<unix seconds>,v1=<hex>, kus v1 on päringu töötlemata sisu põhjal arvutatud HMAC_SHA256(secret, t + "." + body). Arvuta see ise, võrdle konstantse ajakuluga ja lükka vanad ajatemplid tagasi, et vältida taasesitusründeid.

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

Oma API kanal avaldab sinu hallatavasse HTTPS-lõpp-punkti: sinu sisuhaldussüsteemi, uudiskirjatööriista või platvormile, mida Amaposta veel ei toeta. See kuvatakse kalendris ning läbib samad kontrollid, kinnitamised ja korduskatsed nagu iga teine kanal. Postituse avaldamisel saadab Amaposta iga edastuse kohta ühe POST-päringu:

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

Sinu API-võti. Päise nimi ja eesliide (vaikimisi Bearer) määratakse kanalil.

Idempotency-Key

Edastuse ID. Sama edastuse korduskatse saadab sama võtme, nii et saad juba tehtud töö vahele jätta.

X-Amaposta-Delivery

Edastuse ID uuesti, sinu logide jaoks.

X-Amaposta-Signature

Allkirjastatud nagu veebihaagid, kanali enda allkirjastamissaladusega.

Kuidas vastata

• 2xxAvaldatud. Soovi korral tagasta {"id": "…", "url": "…"} ja link ilmub postitusele.
• 401, 403Võti lükati tagasi. Kanal märgitakse taasühendamist vajavaks ja administraatoreid teavitatakse. Ära kasuta neid vigase allkirja korral.
• 5xx, 408, 429Ajutine. Amaposta proovib kasvavate vahedega uuesti.
• Muud 4xxPostitus märgitakse sinu sõnumiga nurjunuks ning keegi saab selle parandada ja vajutada „Proovi uuesti”.

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

Sinu lõpp-punkt peab olema internetist kättesaadav; ümbersuunamisi ei järgita. Kanali ühendamisel kontrollib Amaposta seda GET-päringuga sinu määratud tervisekontrolli URL-ile või OPTIONS-päringuga lõpp-punkti.

Liivakastikanal toimib nagu päris kanal, kuid miski ei välju Amapostast. Kasuta seda integratsiooni loomiseks ja terviklikuks testimiseks: postitused ajastatakse, jõuavad eetrisse, avaldatakse või nurjuvad ning käivitavad samad veebihaagid. Liivakastikanalid on kõigis pakettides tasuta ega lähe kanalite limiidi arvestusse.

Vali, kuidas see lisamisel käitub:

• Õnnestu alatiIga postitus avaldatakse.
• Nurju aeg-ajaltVaata tõrkeid ja korduskatseid päris katkestust ootamata.
• Nurju alatiTesti sündmuse post.failed käsitlemist.
• Aegunud ühendusVaata, millised on taasühendamise teavitused ja lingid juurdepääsu aegumisel.

X arvestab iga API-päringu, sealhulgas iga postituse tasu selle teinud arendajarakenduse ettemakstud krediidist. Seetõttu ühendad X-i oma X-i arendajarakenduse kaudu: seadista see iga tööruumi jaoks üks kord ja ühenda seejärel nii palju X-i kontosid kui soovid. Iga kontoga logitakse sisse X-is ja selle postituste eest tasutakse sinu rakenduse krediidist.

1. Logi aadressil console.x.com sisse X-i kontoga, millele rakendus peaks kuuluma, näiteks oma agentuuri kontoga, ja loo rakendus.
2. Ava rakenduse User authentication settings ja sisesta:
   • App permissionsRead and write
   • Type of AppWeb App, Automated App or Bot
   • Callback URI / Redirect URLhttps://www.amaposta.com/oauth/x/callback
   • Website URLSinu veebisait

   Seejärel salvesta. Ainult seda tüüpi rakendus saab kliendi saladuse, mida Amaposta kasutab sisselogimiseks.

3. Kopeeri OAuth 2.0 Client ID ja Client Secret, mida X pärast salvestamist näitab. Ära kasuta väljade API Key, API Key Secret ega Bearer Token väärtusi: need on mõeldud teistsuguseks juurdepääsuks. X näitab saladust ainult ühe korra.
4. Osta X-i konsoolis API krediiti. Automaatne laadimine võimaldab postitamist jätkata, kui krediit hakkab otsa saama; kululimiit piirab kulu. Kui krediit on otsas, keeldub X postitusi avaldamast, kuni lisad krediiti juurde.
5. Ava Amapostas projekti Kanalid, vali Ühenda kanal ja seejärel X. Kleebi kliendi ID ja kliendi saladus, jätka X-i, logi sisse kontoga, mille soovid ühendada, ja luba juurdepääs.

Hea teada

• Rakendus salvestatakse kogu tööruumi jaoks ja selle saladus krüpteeritakse. Iga järgmise X-i konto saad ühendada ühe klõpsuga mis tahes projektist.
• Kanalid säilitavad rakenduse, mille kaudu need ühendati. Kanali uuesti ühendamisel, ka kliendile mõeldud taasühendamislingi kaudu, kasutatakse jälle sama rakendust; sinu klient seda kunagi ei näe.
• Rakenduse vahetamiseks vali X-i ühendamisel „Kasuta teist rakendust“. Kui lood uue Client Secreti, sisesta see seal ja ühenda oma X-i kanalid uuesti.
• X-i konsool väljastab pääsutõendeid ainult kontole, millele rakendus kuulub. Oma klientide kontod ühendad oma rakenduse kaudu sisse logides; oma konto puhul saad endiselt sisestada pääsutõendid käsitsi.