Использование callback-уведомлений

Руководство по настройке callback-уведомлений для получения информации об изменении статуса документа или проекта в Smartcat

С помощью callback-уведомлений вы можете узнать об изменении статуса документа или проекта в Smartcat, а также узнать о статусе импорта двуязычных XLIFF-представлений документов.

Настройки для приема callback

Для того чтобы получить callback-уведомления необходимо выполнить следующие действия:

1. Настроить веб-сервер
2. Настроить callback URL по WebAPI 
3. Выполнить настройку уведомлений с помощью методов API, описанных ниже.
4. Выполнить обработку callback-запроса при изменении статуса проекта URL: <callbackURL>/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"]

5. Выполнить обработку callback-запроса при изменении статуса документа URL: <callbackURL>/document/status

   Структура запроса:

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

6. Выполнить обработку callback-запроса для окончания импорта перевода из XLIFF URL: <callbackURL>/document/translationImportCompleted

   Структура запроса:

   POST /api/callbackUrl/document/translationImportCompleted HTTP/1.1
   Host: example.local 
   Content-Type: application/json 
   ["60606_25", "61234_25"]

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

Периодичность, с которой Smartcat пытается отправить уведомления повторно, если не может достучаться до callback URL:
задержка 30 секунд, 8 попыток, перед каждой следующей задержка увеличивается в 2 раза.

Методы Callback API

Создание или обновление настроек приема уведомлений

В первую очередь необходимо указать адрес вашего сервера, на который будут приходить callback-запросы.

Это можно сделать с помощью метода POST: /api/integration/v1/callback

Тело запроса:

{
  "url": "smartcat.stage-next.sc.local:8012/api/receiver/myTest",
  "additionalHeaders": [
    {
    name: "Authorization",
    value: "Basic ZG0eMTpRd3VydHkdMjM="
    }
  ]
}

В этом примере указан callback URL, на который будут отправляться уведомления, а также параметр additionalHeaders, который добавляет HTTP-заголовок к callback-уведомлению. Этот HTTP-заголовок может быть полезен, если веб-сервер защищен фаерволом и нужно выполнить аутентификацию. Если этого не требуется, то параметр additionalHeaders можно проигнорировать.

Этот метод позволяет как задать новый callback, так и изменить существующий.

Структура запроса:

POST /api/integration/v1/callback HTTP/1.1
Host: smartcat.stage-next.sc.local
Authorization: Basic ZG0eMTpRd3VydHkdMjM=
Content-Type: application/json
Cache-Control: no-cache
{
"url": "http://myurl.net:8012/api/receiver/myTest",
"additionalHeaders": [
    {
    name: "Authorization",
    value: "Basic ZG0eMTpRd3VydHkdMjM="
    }
  ]
}

HTTP код 200 возвращается в случае, успешного обновления настроек

HTTP код 400 возвращается в случаях:

• недействительный URI один из заголовков имеет пустое, нулевое или состоящее из пробельных символов значение.
• один из заголовков имеет null в качестве значения.

Удаление настроек приема уведомлений

Для того чтобы удалить настройки приема уведомлений, воспользуйтесь методом DELETE: /api/integration/v1/callback

Структура запроса:

DELETE /api/integration/v1/callback HTTP/1.1
Host: smartcat.stage-next.sc.local
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Cache-Control: no-cache 

После выполнения запроса возвращается код HTTP 204, если удаление настроек уведомлений было выполнено.

Чтение настроек приема уведомлений аккаунта

Прочитать текущие настройки уведомлений позволяет метод

GET: /api/integration/v1/callback

Структура запроса:

GET /api/integration/v1/callback HTTP/1.1
Host: smartcat.stage-next.sc.local
Authorization: Basic ZG0eMTpRd3VydHkdMjM=
Cache-Control: no-cache

Структура ответа:

{
"url": "string",
"additionalHeaders": [
    {
    "name": "string",
    "value": "string"
    }
  ]
 }

HTTP код 200 возвращается в случае успешного выполнения запроса

HTTP код 404 возвращается в случае, если настройки уведомлений не заданы

Чтение последних ошибок отправки

Если в случае выполнения callback-запроса возникли ошибки, то вы можете просмотреть их с помощью метода GET: /api/integration/v1/callback/lastErrors

Метод также позволяет указать параметр limit, ограничивающий количество показываемых ошибок, например: https://smartcat.stage-next.sc.local/api/integration/v1/callback/lastErrors?limit=100

Структура запроса:

GET /api/integration/v1/callback/lastErrors HTTP/1.1
Host: smartcat.stage-next.als.local
Authorization: Basic ZG0eMTpRd3VydHkdMjM=
Cache-Control: no-cache

Структура ответа:

[
 {
  "Id": "string",
  "Created": "2017-02-01T00:38:39.062Z",
  "Expired": "2017-02-01T00:38:39.062Z",
  "ApplicationId": "string",
  "Url": "string",
 "FailResponse": {
   "Reason": "string",
    "Code": 0,
     "Content": "string"
  }
 }
]

Параметр Id содержит идентификатор описания.

Параметр Reason содержит описание причины (например, timeout, unknown host или информацию о недействительном сертификате).

Параметр Code содержит код ответа, который вернул веб-сервер.

Параметр Content содержит текст ошибки, которую вернул веб-сервер. 

HTTP код 200 возвращается в случае успешного выполнения запроса.

HTTP код 400 возвращается в случае, если указан лимит, больше допустимого.

Если ошибок выполнения callback-запросов нет, то будет возвращен пустой массив.