Автоматизація та інтеграції

API-ключі, batch uploads і callbacks без здогадок про правила runtime.

Ця сторінка описує живу інтеграційну поверхню: як автентифікуватися, підготувати завантаження, перевіряти одиночні jobs або batch та підключати terminal callbacks на поточному Pro API path.

Останнє оновлення: 6 квітня 2026

Швидкий старт

Робочий шлях навмисно вузький: спочатку підготуйте job, потім завантажте файл у видану ціль і далі або poll, або callback.

1Створіть API-ключ в акаунті під Pro планом.
2Надішліть POST /uploads/prepare або POST /uploads/batch/prepare лише з метаданими файла.
3Завантажте бінарний файл саме в той upload target, який повернула відповідь.
4Опитуйте GET /jobs/:jobId або GET /job-batches/:batchId, поки результат не стане ready.
5За потреби додайте callbackUrl і callbackSecret, якщо хочете terminal push-подію.

Автентифікація і модель доступу

Server-to-server запити можуть автентифікуватися через X-API-Key. Браузерні сценарії використовують session token акаунта, але інтеграційна модель побудована навколо API-ключів.

- API-ключі створюються в акаунті і повністю показуються лише один раз.
- Batch prepare і webhook callbacks обмежені Pro API path.
- Важкі audio та video jobs усе ще витрачають media credits акаунта-власника.
- Статус одиночного job можна перевіряти або авторизацією акаунта-власника, або signed status token з prepare response.
- Статус batch вимагає auth акаунта-власника і не має public token path.

Заголовки для auth polling

bash

curl https://your-swapmyfile-host.example/jobs/job_123 \
  -H "X-API-Key: smf_live_your_key"

curl https://your-swapmyfile-host.example/jobs/job_123?token=job_status_token

Одиночний prepare-upload-poll flow

Одиночний job починається лише з метаданих. API повертає job record, upload target, signed status token і список наступних перевірок після прийняття upload.

- POST /uploads/prepare валідовує запит ще до передачі тіла файла.
- У відповіді може бути або API multipart upload target, або direct PUT target плюс completeUrl.
- Після завершення upload опитуйте GET /jobs/:jobId, поки статус не стане ready або failed.
- Коли статус ready, використовуйте job.downloadUrl як signed result link.
- callbackUrl і callbackSecret є опціональними для кожного job і додаються на етапі prepare.

Підготовка одиночного job

bash

curl -X POST https://your-swapmyfile-host.example/uploads/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "converterSlug": "jpg-to-png",
    "inputFilename": "hero.jpg",
    "inputMime": "image/jpeg",
    "inputSize": 245001
  }'

Batch preparation і batch status

Batch prepare дозволяє одним API-запитом відкрити кілька upload targets одразу. Поточний backend приймає до 25 елементів у batch request і повертає як batch record, так і per-job upload entries.

- POST /uploads/batch/prepare приймає optional label і масив jobs.
- Кожен job окремо передає converterSlug, filename, mime type, size і optional callback settings.
- Довжина batch label обмежена 80 символами.
- Публічний web batch UI тримає один converter на сторінку, але API payload лишається job-by-job.
- Опитуйте GET /job-batches/:batchId тим самим auth акаунта-власника для aggregate status.

Підготовка batch request

bash

curl -X POST https://your-swapmyfile-host.example/uploads/batch/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "label": "April content refresh",
    "jobs": [
      {
        "converterSlug": "jpg-to-png",
        "inputFilename": "hero-01.jpg",
        "inputMime": "image/jpeg",
        "inputSize": 245001
      },
      {
        "converterSlug": "webp-to-png",
        "inputFilename": "hero-02.webp",
        "inputMime": "image/webp",
        "inputSize": 198221
      }
    ]
  }'

Terminal callbacks

Callbacks призначені для terminal edge pipeline, а не для кожного проміжного стану. Зараз SwapMyFile відправляє callbacks лише коли job стає ready або failed.

- Підтримувані callback events: job.ready і job.failed.
- callbackUrl має бути абсолютним http або https URL, callbackSecret є optional.
- Якщо callbackSecret заданий, запит містить x-swapmyfile-signature з sha256=<hmac> від сирого JSON body.
- Запит також містить заголовки x-swapmyfile-event і x-swapmyfile-job-id.
- Відповідь 2xx означає успішну доставку. Невдалі доставки повторюються до 3 разів у короткому retry-вікні.

Приклад callback payload

json

{
  "event": "job.ready",
  "deliveredAt": "2026-04-06T12:00:00.000Z",
  "job": {
    "jobId": "job_123",
    "converterSlug": "jpg-to-png",
    "status": "ready",
    "inputFilename": "hero.jpg",
    "outputFilename": "hero.png",
    "downloadUrl": "/downloads/signed/example",
    "callback": {
      "url": "https://client.example/hooks/swapmyfile",
      "status": "pending",
      "attempts": 0
    }
  }
}

FAQ для інтеграції

Чи може guest-сесія використовувати API path?

Ні. Guest-користувачі можуть користуватися браузерним продуктом, але API keys, callbacks і batch prepare прив'язані до авторизованого Pro акаунта.

Callbacks повністю замінюють polling?

Не завжди. Callbacks зручні для terminal state delivery, але polling лишається простішим способом дивитися на in-progress jobs, batch progress і готовність download.

Чи можна poll одиночний job без збереження account credentials?

Так. Відповідь на single-job prepare містить signed status token, який можна використовувати на GET /jobs/:jobId?token=... для status-only доступу.

Відкрийте акаунт перед тим, як скриптувати production flow.

Спочатку створіть API-ключ, перевірте ліміти плану на акаунті-власнику і поповніть media credits, якщо сценарій включає важкі audio або video jobs.

Відкрити акаунт Переглянути ціни