Документация API перевода

Авторизация, безопасный первый запрос и жизненный цикл заказа с примерами на чистом PHP. API v1 поддерживает текст, документы и аудио в пределах прав аккаунта.

Базовый URLhttps://api.translate24.pro/v1

Доступ и авторизация

Свяжитесь с нами для согласования аккаунта и прав. Локальные аккаунты используют выданный Bearer-токен. В этой версии нет кабинета самостоятельного выпуска ключей компании. Связаться с нами

Authorization: Bearer YOUR_API_TOKEN

Храните токен в переменной окружения или закрытой конфигурации сервера. Используйте HTTPS. Не передавайте учётные данные в URL, браузерном JavaScript или публичных репозиториях.

Хеш пароля из базы не является паролем API. SSO-вход на сайт и авторизация API — разные механизмы.

Первый запрос

Начните с чтения профиля. Этот запрос не создаёт заказ и не списывает средства.

cURL
curl --request GET \
  'https://api.translate24.pro/v1/user/view' \
  --header "Authorization: Bearer $TRANSLATE24_API_TOKEN" \
  --header 'Accept: application/json'

Задайте TRANSLATE24_API_TOKEN на сервере. Проверьте HTTP-статус и JSON: успешный ответ профиля содержит объект user.

Читайте актуальные справочники и используйте полученные идентификаторы. Идентификаторы из примеров могут быть недоступны вашему аккаунту.

  • GET /languages/get-pairs
  • GET /languages/get-themes
  • GET /languages/get-types
  • GET /order/get-data-for-create-order

Чистый PHP

Пример только читает данные и использует расширение cURL для PHP; фреймворк не требуется.

PHP
<?php
$token = getenv('TRANSLATE24_API_TOKEN');
if (!is_string($token) || $token === '') {
    throw new RuntimeException('API token is not configured.');
}

$ch = curl_init('https://api.translate24.pro/v1/user/view');
if ($ch === false) {
    throw new RuntimeException('Unable to initialize cURL.');
}
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
]);
$body = curl_exec($ch);
$httpStatus = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($body === false) {
    // Keep diagnostic details in a protected server log.
    throw new RuntimeException('API connection failed.');
}
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($httpStatus < 200 || $httpStatus >= 300) {
    throw new RuntimeException('API HTTP error: ' . $httpStatus);
}
if (!is_array($data) || isset($data['errors'])
    || !isset($data['user']) || !is_array($data['user'])) {
    throw new RuntimeException('Unexpected API response.');
}
$user = $data['user'];

Храните профиль на сервере и показывайте только нужные приложению поля. Пример не выводит данные клиента или учётные данные.

Жизненный цикл заказа

  1. Выберите языковую пару, тип и тему из справочников. POST /order/create-as-draft создаёт запись, но автоматически не запускает платную работу.
  2. Проверьте errors, order, price и infoMessage в ответе. Для некоторых документов нужен ручной подсчёт слов.
  3. POST /order/in-work?id=ORDER_ID&pay_by=1 может списать баланс и запустить работу. Перед вызовом получите явное подтверждение.
  4. Для отслеживания используйте GET /order/view?id=ORDER_ID или GET /order/index. Ограничивайте частоту опроса.

Поля запроса черновика

Поля запроса черновикаЗначение
type1: текст · 2: файлы · 3: аудио
source_type1: текстовый результат · 2: аудиорезультат
language_pair_idID из справочника либо from_language_code и to_language_code.
translate_type_idID типа перевода из справочника
translate_theme_idID тематики из справочника
source_textИсходный текст текстового заказа
uploadSourceFiles[]Загрузка файлов или аудио через multipart
user_idНеобязательно: клиент, созданный авторизованным партнёром. Иначе заказ принадлежит авторизованному аккаунту.

Для текста передавайте поля формы, для файлов — multipart/form-data. Границу multipart должен задавать HTTP-клиент.

Для in-work значение pay_by=1 использует баланс авторизованного аккаунта; pay_by=2 — баланс владельца заказа и требует соответствующих прав партнёра и принадлежности клиента.

Файлы и аудио

Документы: txt, odt, pdf, docx; до 5 файлов по 5 МиБ. Аудио: mp3, ogg, webm; до 5 файлов по 15 МиБ.

Проверяйте каждый ответ загрузки. Один лишь ID заказа не означает, что можно запускать платную работу, если не удался разбор файла или подсчёт слов.

Ошибки и повторы

401: проверьте авторизацию. 403: проверьте права. 404: проверьте ID и принадлежность записи. Ответ 2xx с errors означает ошибку приложения; часть ошибок валидации возвращается с HTTP 200.

После тайм-аута или 5xx запись уже могла выполниться. Перед повтором проверьте состояние. Не повторяйте автоматически создание, оплату или удаление: контракт ключей идемпотентности не опубликован. Чтение можно повторять ограниченное число раз с задержкой.

Внешние аккаунты

Внешние аккаунты используют предусмотренную для них Basic-авторизацию и читают только свой профиль, историю переводов и разрешённые справочники. Создание, отправка в работу и удаление заказов им недоступны. Для записи согласуйте локальный интеграционный или партнёрский аккаунт.

Справочник методов

Пути указаны относительно базового URL. Доступ зависит от прав аккаунта. Схемы параметров смотрите в Swagger; для подключения свяжитесь с нами.

МетодПутьНазначение
GET/user/viewВаш профиль
GET/user/listКлиенты партнёра
POST/user/registrationСоздать клиента партнёра
POST/user/deleteУдалить клиента партнёра
GET/order/indexДоступные заказы
GET/order/viewДетали заказа
GET/order/get-data-for-create-orderПараметры заказа
POST/order/create-as-draftСоздать черновик
POST/order/in-workПодтвердить оплату и начать работу
POST/order/deleteУдалить допустимый заказ
GET/languages/get-pairsЯзыковые пары
GET/languages/get-themesТематики
GET/languages/get-typesТипы перевода

Swagger ↗ · Связаться с нами