Начало работы с API Smartcat

Как получить доступ к API?

Для авторизации в API Smartcat используется пара ID аккаунта и ключ авторизации. Узнать идентификатор аккаунта и создать свой ключ вы можете в разделе настроек API в Smartcat.

Как делать запросы к API

Какие есть методы?

С полным списком методов API вы можете ознакомиться здесь.

Куда отправлять запросы?

Например, полный URL запроса на получение списка проектов будет выглядеть так:

https://smartcat.ai/api/integration/v1/project/list

Авторизация и аутентификация

Для всех методов необходима аутентификация. 

В качестве основной системы аутентификации используется механизм BASIC Authentication.
Для аутентификации необходимо в каждый запрос добавлять заголовок вида: Authorization: Basic Key, где Key это Base64 представление строки типа «accountID»:«authKey».

Описание объектов

Аккаунт/Account - корпоративный аккаунт вашей компании. Все ваши документы, ресурсы и пользователи находятся внутри вашего аккаунта.

Проект/Project - набор документов, которые нужно перевести с исходного языка на один или несколько целевых языков. Помимо документов к проекту подключаются ресурсы – Память Переводов и Глоссарии. 

Документ/Document - файл внутри проекта, который нужно перевести на один из целевых языков. Если один файл нужно перевести на несколько языков, в проекте будет несколько документов.

Память переводов/Translation memory - хранилище ваших сохраненных переводов, которые вы можете переиспользовать в текущих проектах.

Примеры использования

Как отправить файлы на перевод

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

Проект создается с помощью метода

POST: /api/integration/v1/project/create

Файлы можно загружать в том же вызове одновременно с созданием проекта, либо отдельно с помощью метода

POST: /api/integration/v1/project/document

Как узнать статус работы по переводу

Статус работы по проекту можно узнать с помощью метода

GET: /api/integration/v1/project/{projectId} 

Метод возвращает полную модель проекта, включая список всех документов с информацией об их статусах и прогрессах перевода по каждой стадии

Статус работы по конкретному документу можно узнать с помощью метода

GET: /api/integration/v1/document 

Метод возвращает информацию о конкретном документе, включая информацию о статусе и прогрессе перевода 

Также вы можете настроить callback-уведомления об изменении статусов проектов и документов. Для этого воспользуйтесь методом 

POST: /api/integration/v1/callback 

Метод задает URL, на который Smartcat будет отправлять уведомления об изменениях статусов ваших проектов и документов. 

На адрес <your_URL>/project/status будут приходить уведомления об изменениях статусов проектов. Запрос будет содержать список идентификаторов проектов, по которым изменились статусы. Пример запроса:

POST /api/callback/project/status HTTP/1.1
Host: example.local
Content-Type: application/json
["1e2d703f-9def-4d27-ab4d-350cbbe8c44b", "b5bf9123-31b3-4e45-9ee9-8c14d15a4145"]

С помощью этих идентификаторов вы сможете получить полную информацию о проектах.

На адрес <your_URL>/document/status будут аналогичным образом приходить уведомления об изменениях статусов документов, например:

POST /api/callback/document/status HTTP/1.1
Host: example.local
Content-Type: application/json
["189_25", "310_25"]


Как скачать готовый перевод

Чтобы получить готовый перевод, воспользуйтесь методом

POST: /api/integration/v1/document/export

передав список идентификаторов нужных документов.

Этот метод запрашивает сборку перевода выбранных документов и возвращает идентификатор задачи на сборку.

Затем с помощью метода

GET: /api/integration/v1/document/export/{taskId}

вы можете проверить статус задачи и получить итоговый файл.

Как обновить существующий файл

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

POST: /api/integration/v1/document/update

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

Как назначить исполнителя

Для назначения исполнителя или исполнителей на документ воспользуйтесь методом
POST: /api/integration/v1/document/assign

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