Treoir d'fhorbróirí

Fíordheimhniú

Cruthaigh eochair API sa deais faoi Socruithe, API agus crúcaí gréasáin. Tosaíonn eochracha le ss_live_, baineann siad le spás oibre amháin agus is féidir iad a theorannú do thionscadail ar leith. Seol an eochair mar chomhartha iompróra ar gach iarratas:

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

Ainmníonn an freagra an eochair, a raonta agus an spás oibre. Tá raon amháin nó níos mó ag gach eochair:

Is féidir le gach eochair 120 iarratas sa nóiméad a dhéanamh. Ina dhiaidh sin faigheann tú 429 leis an gcód rate_limited; fan seal beag agus bain triail eile as.

Tionscadail agus cainéil

Tá postálacha i dtionscadal. Liostaigh na tionscadail a fheiceann d'eochair, ansin na cainéil i gceann acu. Beidh aitheantas cainéil de dhíth ort chun díriú air nó chun leagan ar leith dá théacs a shocrú.

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"

Tá provider (youtube, instagram, tiktok, x, facebook, custom nó sandbox), status (active, expiring, needs_reconnect, error nó disabled) agus na cineálacha postála a supports aige ag cainéal.

Uaslódáil meáin

Uaslódáiltear íomhánna agus físeáin uair amháin in aghaidh an tionscadail agus is féidir iad a úsáid i líon ar bith postálacha. Tá trí bhealach isteach ann.

Uaslódáil dhíreach

Seol an comhad mar shonraí foirme ilpháirteacha i réimse darb ainm file. Is fearr do chomhaid suas le cúpla céad MB.

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

Uaslódáil réamhshínithe do chomhaid mhóra

Iarr URL uaslódála, déan PUT de na bearta díreach chuig an stóras, ansin inis do Amaposta go bhfuil tú críochnaithe.

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

Iompórtáil ó URL

Tabhair URL poiblí do Amaposta agus íoslódálann sé an comhad sa chúlra. Is féidir leat an chéim seo a scipeáil freisin agus media_url a chur ar fáil nuair a chruthaíonn tú an phostáil.

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

Tugann gach uaslódáil oibiacht meáin ar ais. Bogann a status ó pending go processing go ready (nó failed, le error). Nuair atá sí próiseáilte, tá width, height, duration_ms agus mionsamhail aici. Pollaigh GET /api/v1/media/{id} nó éist leis an gcrúca gréasáin media.ready. Tá an url a thugann sé ar ais sínithe agus bailí ar feadh 12 uair an chloig.

Cruthaigh postáil

Cruthaíonn POST /api/v1/projects/{project_id}/posts postáil amháin le seachadadh do gach cainéal. Cuireann Amaposta in oiriúint do gach ardán í: ní théann teidil ach áit a bhfuil réimse teidil, déantar clibeanna de haischlibeanna ar YouTube agus téacs inlíne in áiteanna eile.

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

Réimsí

Is í an phostáil an freagra, iontráil amháin in deliveries do gach cainéal san áireamh.

Atrialacha slána

Cailleann líonraí iarratais. Seol ceanntásc Idempotency-Key nuair a chruthaíonn tú postáil, agus tugann atriail leis an eochair chéanna an phostáil ón gcéad iarracht ar ais in ionad ceann eile a chruthú. Úsáid rud seasmhach ó do thaobh féin, amhail aitheantas taisc nó eipeasóide. Gearrtar eochracha go 200 carachtar.

Sceidealaigh agus foilsigh

Sceidealaigh dréacht, foilsigh anois í, cuir sa scuaine í nó bain den fhéilire í le 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"}'

• atFoilsíonn ag an am sonraithe, suas le dhá bhliain roimh ré.
• nowFoilsíonn láithreach.
• queueTógann an chéad sliotán postála saor eile do chainéil na postála sna 12 sheachtain atá romhainn.
• unscheduleBogann an phostáil ar ais chuig dréachtaí.

Sula sceidealaítear aon rud, ritear na seiceálacha céanna agus atá san eagarthóir. Má theipeann ar cheann, tugann an t-iarratas 400 ar ais le teachtaireacht amhail Réitigh é seo roimh sceidealú: Tá teideal de dhíth ar YouTube. Éilíonn sceidealú an raon posts:publish, nó tionscadal le ceaduithe ar siúl, agus sa chás sin fanann an phostáil sa bhosca athbhreithnithe.

Léigh postálacha agus seachadtaí

Liostaigh postálacha tionscadail, scagtha de réir status (stádais scartha le camóga, nó inbox, queue nó history), tréimhse from/to, limit agus offset. Is é an freagra {"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"

Tá status foriomlán ag postáil (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial nó failed) agus seachadadh amháin do gach cainéal:

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

Is iad na stádais seachadta pending, scheduled, publishing, processing, published, failed agus cancelled. Baineann DELETE /api/v1/posts/{post_id} postáil.

Earráidí

Tá an struchtúr céanna ag gach earráid: oibiacht error le code seasmhach, message ar féidir leat a thaispeáint do dhaoine, agus uaireanta fields (teachtaireachtaí do gach réimse) agus hint.

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

Crúcaí gréasáin

Cuir críochphointe leis i Socruithe, API agus crúcaí gréasáin, roghnaigh na himeachtaí atá uait agus cóipeáil a rún sínithe. Seolann Amaposta JSON le POST chuig do URL do gach imeacht. Triailtear aon rud seachas freagra 2xx, nó easpa freagra laistigh de 15 shoicind, arís le tréimhsí feithimh níos faide, agus múchtar críochphointí a leanann orthu ag teip le fógra do riarthóirí.

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

Fíoraigh an síniú

Is é X-Amaposta-Signature ná t=<unix seconds>,v1=<hex>, áit arb é v1 ná HMAC_SHA256(secret, t + "." + body) thar chorp amh an iarratais. Ríomh tú féin é, déan comparáid in am tairiseach, agus diúltaigh do sheanstampaí ama chun athsheinm a stopadh.

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

Foilsíonn cainéal API saincheaptha chuig críochphointe HTTPS a ritheann tú: do CMS, uirlis nuachtlitreach, ardán nach gclúdaíonn Amaposta fós. Tá sé ar an bhféilire, agus faigheann sé seiceálacha, ceaduithe agus atrialacha mar aon chainéal eile. Nuair a sheoltar postáil, seolann Amaposta POST amháin do gach seachadadh:

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

D'eochair API. Socraítear ainm an cheanntáisc agus an réimír (Bearer de réir réamhshocraithe) ar an gcainéal.

Idempotency-Key

Aitheantas an tseachadta. Seolann atriail den seachadadh céanna an eochair chéanna, ionas gur féidir leat obair atá déanta agat cheana a scipeáil.

X-Amaposta-Delivery

Aitheantas an tseachadta arís, do do logaí.

X-Amaposta-Signature

Sínithe ar nós crúcaí gréasáin, le rún sínithe an chainéil féin.

Conas freagairt

• 2xxFoilsithe. Is féidir {"id": "…", "url": "…"} a thabhairt ar ais go roghnach agus taispeántar an nasc ar an bpostáil.
• 401, 403Diúltaíodh don eochair. Marcáiltear an cainéal lena athcheangal agus cuirtear in iúl do riarthóirí é. Ná húsáid iad seo do dhrochsíniú.
• 5xx, 408, 429Sealadach. Baineann Amaposta triail eile as le tréimhsí feithimh níos faide.
• 4xx eileMarcáiltear an phostáil mar theipthe le do theachtaireacht, agus is féidir le duine í a dheisiú agus Bain triail eile as a bhrú.

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

Caithfidh do chríochphointe a bheith inrochtana ón idirlíon; ní leantar atreoruithe. Nuair a cheanglaíonn tú an cainéal, seiceálann Amaposta é le GET chuig do URL sláinte má shocraíonn tú ceann, nó iarratas OPTIONS chuig an gcríochphointe.

Iompraíonn cainéal sandbox mar fhíorchainéal, ach ní fhágann aon rud Amaposta. Úsáid é chun do chomhtháthú a thógáil agus a thástáil ó cheann ceann: sceidealaítear postálacha, téann siad ar an aer, foilsítear iad nó teipeann orthu, agus gineann siad na crúcaí gréasáin céanna. Tá cainéil Sandbox saor in aisce ar gach plean agus ní áirítear iad sna teorainneacha cainéal.

Roghnaigh conas a iompraíonn sé nuair a chuireann tú leis é:

• Éirigh leis i gcónaíFoilsítear gach postáil.
• Teip anois is arísFéach teipeanna agus atrialacha gan fanacht le fíor-bhriseadh seirbhíse.
• Teip i gcónaíTástáil do láimhseáil ar post.failed.
• Ceangal imithe in éagFéach cuma foláirimh agus naisc athcheangail nuair a théann rochtain in éag.