Οδηγός προγραμματιστών

Έλεγχος ταυτότητας

Δημιούργησε ένα κλειδί API στον πίνακα ελέγχου, στις Ρυθμίσεις, στην ενότητα API και webhook. Τα κλειδιά αρχίζουν με ss_live_, ανήκουν σε έναν χώρο εργασίας και μπορούν να περιορίζονται σε συγκεκριμένα έργα. Στείλε το κλειδί ως διακριτικό bearer σε κάθε αίτημα:

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

Η απάντηση αναφέρει το κλειδί, τα δικαιώματά του και τον χώρο εργασίας. Κάθε κλειδί έχει ένα ή περισσότερα δικαιώματα:

Κάθε κλειδί μπορεί να στέλνει 120 αιτήματα το λεπτό. Πέρα από αυτό το όριο λαμβάνεις 429 με κωδικό rate_limited· περίμενε λίγο και δοκίμασε ξανά.

Έργα και κανάλια

Οι αναρτήσεις ανήκουν σε ένα έργο. Δες τη λίστα έργων στα οποία έχει πρόσβαση το κλειδί σου και μετά τα κανάλια ενός από αυτά. Θα χρειαστείς το αναγνωριστικό ενός καναλιού για να το επιλέξεις ως προορισμό ή να προσαρμόσεις το κείμενό του.

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"

Ένα κανάλι έχει provider (youtube, instagram, tiktok, x, facebook, custom ή sandbox), status (active, expiring, needs_reconnect, error ή disabled) και τα είδη αναρτήσεων που supports.

Μεταφόρτωση πολυμέσων

Οι εικόνες και τα βίντεο μεταφορτώνονται μία φορά ανά έργο και μπορούν να χρησιμοποιηθούν σε απεριόριστες αναρτήσεις. Υπάρχουν τρεις τρόποι εισαγωγής.

Απευθείας μεταφόρτωση

Στείλε το αρχείο ως δεδομένα φόρμας multipart σε πεδίο με όνομα file. Ιδανικό για αρχεία έως μερικές εκατοντάδες MB.

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

Προϋπογεγραμμένη μεταφόρτωση για μεγάλα αρχεία

Ζήτησε ένα URL μεταφόρτωσης, στείλε τα byte απευθείας στον αποθηκευτικό χώρο με PUT και μετά ενημέρωσε το Amaposta ότι ολοκλήρωσες.

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

Εισαγωγή από URL

Δώσε στο Amaposta ένα δημόσιο URL και θα κατεβάσει το αρχείο στο παρασκήνιο. Μπορείς επίσης να παραλείψεις αυτό το βήμα και να δώσεις 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"}'

Κάθε μεταφόρτωση επιστρέφει ένα αντικείμενο πολυμέσου. Το status περνά από pending σε processing και ready (ή failed, με error). Μετά την επεξεργασία περιέχει width, height, duration_ms και μια μικρογραφία. Έλεγχε περιοδικά το GET /api/v1/media/{id} ή περίμενε το webhook media.ready. Το url που επιστρέφεται είναι υπογεγραμμένο και ισχύει για 12 ώρες.

Δημιουργία ανάρτησης

Το POST /api/v1/projects/{project_id}/posts δημιουργεί μία ανάρτηση με μία παράδοση για κάθε κανάλι. Το Amaposta την προσαρμόζει ανά πλατφόρμα: οι τίτλοι προστίθενται μόνο όπου υπάρχει πεδίο τίτλου, ενώ τα hashtag γίνονται ετικέτες στο YouTube και ενσωματώνονται στο κείμενο αλλού.

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

Πεδία

Η απάντηση είναι η ανάρτηση, με μία εγγραφή στο deliveries ανά κανάλι.

Ασφαλείς επαναλήψεις

Τα δίκτυα χάνουν αιτήματα. Στείλε μια κεφαλίδα Idempotency-Key όταν δημιουργείς ανάρτηση και μια επανάληψη με το ίδιο κλειδί επιστρέφει την ανάρτηση της πρώτης προσπάθειας αντί να δημιουργεί δεύτερη. Χρησιμοποίησε κάτι σταθερό από την πλευρά σου, όπως το αναγνωριστικό μιας εργασίας ή ενός επεισοδίου. Τα κλειδιά περικόπτονται στους 200 χαρακτήρες.

Προγραμματισμός και δημοσίευση

Προγραμμάτισε ένα πρόχειρο, δημοσίευσέ το τώρα, πρόσθεσέ το στην ουρά ή αφαίρεσέ το από το ημερολόγιο με 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"}'

• atΔημοσιεύεται στην καθορισμένη ώρα, έως δύο χρόνια αργότερα.
• nowΔημοσιεύεται αμέσως.
• queueΕπιλέγει την επόμενη ελεύθερη θέση δημοσίευσης για τα κανάλια της ανάρτησης μέσα στις επόμενες 12 εβδομάδες.
• unscheduleΜεταφέρει την ανάρτηση πίσω στα πρόχειρα.

Πριν προγραμματιστεί οτιδήποτε, εκτελούνται οι ίδιοι έλεγχοι με τον επεξεργαστή. Αν κάποιος αποτύχει, το αίτημα επιστρέφει 400 με μήνυμα όπως Διόρθωσέ το πριν τον προγραμματισμό: Το YouTube χρειάζεται τίτλο. Ο προγραμματισμός απαιτεί το δικαίωμα posts:publish ή ένα έργο με ενεργοποιημένες εγκρίσεις, οπότε η ανάρτηση περιμένει στα εισερχόμενα ελέγχου.

Ανάγνωση αναρτήσεων και παραδόσεων

Λίστα αναρτήσεων ενός έργου, με φίλτρα status (καταστάσεις χωρισμένες με κόμμα ή inbox, queue ή history), χρονικό διάστημα from/to, limit και offset. Η απάντηση είναι {"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"

Μια ανάρτηση έχει συνολικό status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial ή failed) και μία παράδοση ανά κανάλι:

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

Οι καταστάσεις παράδοσης είναι pending, scheduled, publishing, processing, published, failed και cancelled. Το DELETE /api/v1/posts/{post_id} αφαιρεί μια ανάρτηση.

Σφάλματα

Κάθε σφάλμα έχει την ίδια δομή: ένα αντικείμενο error με σταθερό code, ένα message που μπορείς να εμφανίσεις στους χρήστες και, μερικές φορές, fields (μηνύματα ανά πεδίο) και hint.

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

Webhook

Πρόσθεσε ένα τελικό σημείο στις Ρυθμίσεις, στην ενότητα API και webhook, επίλεξε τα συμβάντα που θέλεις και αντέγραψε το μυστικό υπογραφής του. Το Amaposta στέλνει JSON με POST στο URL σου για κάθε συμβάν. Κάθε απάντηση εκτός 2xx, ή η απουσία απάντησης εντός 15 δευτερολέπτων, οδηγεί σε επανάληψη με αυξανόμενη καθυστέρηση. Τα τελικά σημεία που συνεχίζουν να αποτυγχάνουν απενεργοποιούνται και οι διαχειριστές ειδοποιούνται.

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

Επαλήθευση υπογραφής

Το X-Amaposta-Signature είναι t=<unix seconds>,v1=<hex>, όπου το v1 είναι το HMAC_SHA256(secret, t + "." + body) για το ακατέργαστο σώμα του αιτήματος. Υπολόγισέ το, σύγκρινέ το σε σταθερό χρόνο και απόρριψε παλιές χρονικές σημάνσεις για να αποτρέψεις την επανάληψη αιτημάτων.

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

Ένα κανάλι Custom API δημοσιεύει σε ένα τελικό σημείο HTTPS που διαχειρίζεσαι: το CMS σου, ένα εργαλείο ενημερωτικών δελτίων ή μια πλατφόρμα που δεν υποστηρίζει ακόμη το Amaposta. Εμφανίζεται στο ημερολόγιο και έχει ελέγχους, εγκρίσεις και επαναλήψεις όπως κάθε άλλο κανάλι. Όταν δημοσιεύεται μια ανάρτηση, το Amaposta στέλνει ένα POST ανά παράδοση:

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

Το κλειδί API σου. Το όνομα κεφαλίδας και το πρόθεμα (Bearer από προεπιλογή) ορίζονται στο κανάλι.

Idempotency-Key

Το αναγνωριστικό παράδοσης. Η επανάληψη της ίδιας παράδοσης στέλνει το ίδιο κλειδί, ώστε να παραλείπεις εργασίες που έχεις ήδη εκτελέσει.

X-Amaposta-Delivery

Το αναγνωριστικό παράδοσης ξανά, για τα αρχεία καταγραφής σου.

X-Amaposta-Signature

Υπογράφεται όπως τα webhook, με το δικό του μυστικό υπογραφής του καναλιού.

Πώς να απαντάς

• 2xxΔημοσιεύτηκε. Προαιρετικά επέστρεψε {"id": "…", "url": "…"} και ο σύνδεσμος εμφανίζεται στην ανάρτηση.
• 401, 403Το κλειδί απορρίφθηκε. Το κανάλι επισημαίνεται για επανασύνδεση και οι διαχειριστές ενημερώνονται. Μην χρησιμοποιείς αυτούς τους κωδικούς για μη έγκυρη υπογραφή.
• 5xx, 408, 429Προσωρινό. Το Amaposta επαναλαμβάνει με αυξανόμενη καθυστέρηση.
• Άλλο 4xxΗ ανάρτηση επισημαίνεται ως αποτυχημένη με το μήνυμά σου και κάποιος μπορεί να τη διορθώσει και να πατήσει Επανάληψη.

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

Το τελικό σημείο σου πρέπει να είναι προσβάσιμο από το διαδίκτυο· οι ανακατευθύνσεις δεν ακολουθούνται. Όταν συνδέεις το κανάλι, το Amaposta το ελέγχει με GET στο URL ελέγχου λειτουργίας, αν έχεις ορίσει ένα, ή με αίτημα OPTIONS στο τελικό σημείο.

Ένα κανάλι Sandbox συμπεριφέρεται σαν πραγματικό, αλλά τίποτα δεν φεύγει από το Amaposta. Χρησιμοποίησέ το για να αναπτύξεις και να δοκιμάσεις τη διασύνδεσή σου από άκρη σε άκρη: οι αναρτήσεις προγραμματίζονται, βγαίνουν στον αέρα, δημοσιεύονται ή αποτυγχάνουν και ενεργοποιούν τα ίδια webhook. Τα κανάλια Sandbox είναι δωρεάν σε κάθε πρόγραμμα και δεν υπολογίζονται στα όρια καναλιών.

Επίλεξε τη συμπεριφορά του κατά την προσθήκη:

• Πάντα επιτυχίαΚάθε ανάρτηση δημοσιεύεται.
• Περιστασιακή αποτυχίαΔες αποτυχίες και επαναλήψεις χωρίς να περιμένεις πραγματική διακοπή λειτουργίας.
• Πάντα αποτυχίαΔοκίμασε τον χειρισμό του post.failed.
• Ληγμένη σύνδεσηΔες πώς εμφανίζονται οι ειδοποιήσεις και οι σύνδεσμοι επανασύνδεσης όταν λήγει η πρόσβαση.