API RapidTranslate

Вступ

API RapidTranslate дозволяє вашому додатку надсилати документи на завірений переклад, отримувати актуальну інформацію про стан виконання та вартість, а також отримувати готові файли — без необхідності для вашої команди користуватися нашою системою оформлення замовлень. Цей сервіс призначений для компаній, які розміщують замовлення на переклад від імені своїх клієнтів.

Усі запити надсилаються на адресу https://www.rapidtranslate.org/api/v1 через HTTPS. Запити та відповіді надсилаються у форматі JSON, за винятком створення замовлення, під час якого файли завантажуються як multipart/form-data. Усі суми повертаються у вигляді цілі центи у доларах США, а всі часові мітки вказано у форматі UTC ISO‑8601.

Колекція «Поштар»

Хочете спочатку ознайомитися з API, перш ніж писати код? У нашій колекції Postman усі кінцеві точки вже налаштовані — разом з автентифікацією, прикладами тіл запитів та параметрами запитів.

Завантажити колекцію Postman

1. У програмі Postman виберіть «Файл» → «Імпортувати» та вкажіть завантажений файл.
2. Відкрити колекцію Змінні та встановити apiKey до ключа з Налаштування бізнесу → Ключі API.
3. (Необов’язково) Встановити baseUrl для вашого середовища — за замовчуванням встановлено «production».
4. Надішліть будь-який запит. Використовуйте ключ Sandbox для тестування без оформлення замовлень, за які стягується плата.

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

Аутентифікуйте кожен запит за допомогою вашого секретного ключа API як токена «bearer» і запитуйте відповідь у форматі JSON. Обидва заголовки є обов’язковими:

Авторизація: Bearer YOUR_API_KEY
Приймати: application/json

Створюйте та оновлюйте ключі на панелі управління в розділі «Налаштування бізнесу» → «Ключі API». Ключі відображаються лише один раз під час створення та зберігаються у хешованому вигляді — якщо ви втратили ключ, оновлюйте його. Кожен ключ належить до одного режиму («Live» або «Sandbox») і має фіксований набір областей доступу.

Області застосування

Кожна кінцева точка вимагає наявності певної можливості у ключі. Якщо у ключі відсутня необхідна область дії, повертається 403 заборонений_діапазон.

Пісочниця та тестовий режим

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

Замовлення в тестовому середовищі використовують ті самі процедури перевірки, зіставлення полів та реальні ціни, але не передбачають зберігання файлів, OCR та виконання замовлення. Після створення замовлення в тестовому середовищі автоматично проходить весь свій життєвий цикл (обробка → завершено), запускаючи ті самі веб-хуки, що й у разі реального замовлення, і, зрештою, надаючи статичний зразок документа.

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

• livemode: true — справжнє замовлення, що підлягає оплаті
• livemode: false — тестове середовище / тестове замовлення

Обмеження частоти запитів

Кількість запитів обмежена для кожної організації. За замовчуванням дозволено 120 запитів на хвилину. Якщо це значення перевищено, повертається 429 обмеження швидкості; спробуйте ще раз через деякий час. Якщо для вашої інтеграції потрібне більше обмеження, зверніться до support@rapidtranslate.org.

Відповіді

Кожна успішна відповідь упаковує свої дані в дані ключ. У списку кінцевих точок додайте мета блок із нумерацією сторінок.

Один ресурс

{
  "data": {
    "id": "9b1c...-uuid",
    "reference": "APO-10432",
    "status": "processing",
    "total": 11270,
    "currency": "USD"
  }
}

Список із нумерацією сторінок

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

Помилки

Помилки використовують стандартні коди статусу HTTP і повертають стабільні дані, придатні для машинного зчитування код_помилки разом із повідомленням, надісланим людиною. Помилки перевірки додають поле, пов’язане з ключем помилки об'єкт.

{
  "message": "The given data was invalid.",
  "error_code": "validation_failed",
  "errors": {
    "source_language": ["The selected source language is invalid."]
  }
}

Статуси замовлень

Замовлення статус дотримується стабільного життєвого циклу. Ці п’ять цінностей також визнаються статус ввімкнути фільтр Список замовлень:

Поки замовлення знаходиться в процесі виконання, більш детальні позначки (наприклад, Доручено перекладачеві, Переклад, Відправлено) також може з’явитися. Якщо потрібно отримати схвалення, у замовленні може бути коротко зазначено платіж_не_пройшов або credit_hold якщо оплату не вдалося отримати — визначте спосіб оплати та підтвердьте замовлення ще раз.

Значення полів

Фіксовані набори, які приймаються під час створення замовлення.

Види перекладів

Поворот

Способи доставки

Вебхуки

Замість періодичного запиту налаштуйте кінцеву точку вебхука для отримання подій у міру їх виникнення. Вкажіть URL-адресу та перегляньте свій секретний ключ підпису в розділі «Налаштування бізнесу» → «Вебхуки». Вебхуки — це зручний інструмент: отримання інформації про замовлення завжди є достовірним.

Події

Конверт

Кожна доставка має однаковий конверт: подія блок (включно з livemode) та специфічний для події дані блок.

{
  "event": {
    "type": "order_status",
    "id": "evt_9b1c...",
    "livemode": true,
    "sent_at": "2026-08-28T10:20:00+00:00"
  },
  "data": {
    "order": {
      "id": "9b1c2d3e-...-uuid",
      "reference": "APO-10432",
      "status": "completed"
    }
  }
}

У "The доставка_документів подія додає документи масив (кожен із ім'я, download_url, версія, статус) та портал посилання. Це відгук клієнта подія додає детальний перелік ціноутворення блок і actions.approve об’єкт із URL-адресою, яку потрібно викликати.

Перевірка підписів

Кожен запит підписується, щоб ви могли переконатися, що він надійшов від RapidTranslate. Ми надсилаємо три заголовки:

Обчислити очікуваний цифровий підпис у форматі HMAC-SHA256 для цього рядка "{timestamp}.{raw_request_body}" використовуючи секретний ключ для підписання вебхука, а потім порівняйте його зі значенням заголовка:

// PHP
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $webhookSecret
);
$valid = hash_equals($expected, $signatureHeader);

Node.js (Express) — підключити маршрут із використанням парсера необробленого тіла, щоб зберегти точну кількість байтів:

// app.use('/webhooks/rapidtranslate', express.raw({ type: 'application/json' }))
const crypto = require('crypto');

const timestamp = req.get('X-RapidTranslate-Timestamp');
const received  = req.get('X-RapidTranslate-Signature'); // "sha256=..."
const rawBody   = req.body;                               // Buffer, untouched

const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

const valid = received &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Є три речі, які стають для людей перешкодою:

• У "The X-RapidTranslate-Підпис заголовок містить sha256= префікс. Або порівняти з 'sha256=' + yourHmac (як зазначено вище) або видаліть префікс перед порівнянням — не порівнюйте сам шістнадцятковий код із усім заголовком.
• Виконайте хешування необробленого тіла запиту саме в тому вигляді, в якому воно надійшло. Повторна серіалізація розібраного JSON змінює пробіли та порядок ключів, тому підпис не збігатиметься — зчитуйте тіло запиту до того, як його розбере будь-який проміжний модуль обробки JSON.
• Порівнювати за постійний час (hash_equals / crypto.timingSafeEqual), ніколи з == або ===.

У "The {timestamp} є частиною підписаного рядка, тому зчитайте його з заголовка та додайте на початок перед хешуванням. Це також дозволяє відхиляти застарілі або повторно надіслані повідомлення — наприклад, будь-які, мітки часу яких старші за п’ять хвилин.

У разі невдалої доставки здійснюється повторна спроба з експоненційним відстроченням (до 5 спроб). Відповідайте за допомогою 2xx статус для підтвердження отримання.