Посібник розробника

Автентифікація

Створіть ключ API в панелі керування в розділі «Налаштування → API та вебхуки». Ключі починаються з 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 form data в полі з назвою file. Найкраще для файлів до кількох сотень МБ.

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

Завантаження великих файлів за попередньо підписаною URL-адресою

Запросіть URL-адресу для завантаження, надішліть байти безпосередньо у сховище методом 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} або слухайте вебхук media.ready. Повернена url підписана й дійсна 12 годин.

Створити допис

POST /api/v1/projects/{project_id}/posts створює один допис з окремим надсиланням для кожного каналу. Amaposta адаптує його до платформи: заголовки додаються лише там, де є відповідне поле, хештеги стають тегами на 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."
    }
  }
}

Вебхуки

Додайте кінцеву точку в розділі «Налаштування → API та вебхуки», виберіть потрібні події та скопіюйте секрет підпису. Amaposta надсилає POST із JSON на вашу 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", ""))

Канал із власним 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

Підписується як вебхуки, з власним секретом підпису каналу.

Як відповідати

• 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 до кінцевої точки.

Канал-пісочниця працює як справжній, але нічого не виходить за межі Amaposta. Використовуйте його, щоб створити й перевірити інтеграцію від початку до кінця: дописи плануються, виходять в ефір, публікуються або зазнають збою та викликають ті самі вебхуки. Канали-пісочниці безкоштовні в усіх тарифах і не враховуються в лімітах каналів.

Виберіть, як канал поводитиметься після додавання:

• Завжди успіхКожен допис публікується.
• Іноді збійПерегляньте збої та повторні спроби, не чекаючи справжньої аварії.
• Завжди збійПеревірте обробку post.failed.
• Строк з’єднання закінчивсяПодивіться, як виглядають сповіщення й посилання для повторного під’єднання після закінчення доступу.