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». Ключи отображаются только один раз при создании и хранятся в хешированном виде — если вы потеряли ключ, обновите его. Каждый ключ относится к одному режиму («Производственная среда» или «Тестовая среда») и имеет фиксированный набор областей доступа.

Области применения

Каждому конечному пункту требуется определённая способность ключа. Если у ключа отсутствует требуемый диапазон, возвращается 403 запрещённый_область_применения.

Пробная версия и тестовый режим

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

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

Каждый ответ и веб-хук содержит режим реального времени Укажите этот флаг, чтобы ваша интеграция могла создавать ветки без проверки ключа:

• livemode: true — реальный заказ, подлежащий выставлению счета
• livemode: false — тестовая среда / тестовый заказ

Ограничения по скорости

На количество запросов на одну организацию установлено ограничение. По умолчанию разрешено 120 запросов в минуту. При превышении этого значения возвращается 429 rate_limited; попробуйте ещё раз через некоторое время. Если для вашей интеграции требуется более высокий лимит, обратитесь к 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-адрес и просмотрите секретный ключ подписи в разделе «Настройки бизнеса» → «Веб-хуки». Веб-хуки — это удобный инструмент: запрос «Получить заказ» всегда является достоверным источником информации.

События

Конверт

Каждая посылка упакована в одинаковый конверт: мероприятие блок (включая режим реального времени) и специфичный для данного события данные блок.

{
  "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, версия, статус) и портал ссылка. The отзыв клиента событие добавляет подробный список ценообразование блок и 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-Signature заголовок содержит sha256= префикс. Либо сравнить с 'sha256=' + yourHmac (как указано выше) либо удалите префикс перед сравнением — не сравнивайте сам шестнадцатеричный код со всем заголовком целиком.
• Выполните хеширование исходного тела запроса в том виде, в каком оно было получено. При повторной сериализации проанализированного JSON изменяются пробелы и порядок ключей, в результате чего подпись не будет совпадать — считывайте тело запроса до того, как его проанализирует какое-либо промежуточное ПО для работы с JSON.
• Сравнить за постоянное время (hash_equals / crypto.timingSafeEqual), но никогда с == или ===.

The {timestamp} является частью подписанной строки, поэтому его следует прочитать из заголовка и добавить в начало перед хешированием. Это также позволяет отклонять устаревшие или повторно отправленные сообщения — например, те, у которых метка времени старше пяти минут.

В случае сбоя доставки повторяется с использованием экспоненциальной задержки (до 5 попыток). Ответьте с помощью 2xx статус для подтверждения получения.