Спецификация API по услуге Перехват груза

Схема работы

Предполагается, что общение между системами АТИ и ТК будет инициироваться только со стороны АТИ путем отправления HTTP запросов на заданный URL в системе ТК. Обмен данными происходит в формате JSON, кодировка: UTF-8.

Для интеграции с системой АТИ ТК должна реализовать следующий метод авторизации:

  1. Из системы АТИ отправляется POST запрос на получение авторизационного токена на адрес <partner_url>/auth/app, предоставленный ТК. В запросе имеется заголовок Authorization: KEY, где KEY - некоторый ключ, которая ТК предоставила системе АТИ. Ожидается ответ в виде JSON объекта:  

    {
        "token_type": TOKEN_TYPE,
        "access_token": ACCESS_TOKEN
    }

    При этом ACCESS_TOKEN имеет тип string, с максимальной длинной 1024 символа. TOKEN_TYPE так же имеет тип string, с максимальной длинной 64 символа.
    Система АТИ имеет право запрашивать авторизационный токен на каждый запрос.

  2. Все последующие запросы из системы АТИ в систему ТК будут содержать заголовок Authorization: TOKEN_TYPE ACCESS_TOKEN
    При этом система АТИ ожидает следующие HTTP коды ответа:
    200 - успешный ответ;
    400, 401 - некорректный авторизационный токен либо некорректный ключ для получения авторизационного токена;
    403 - приложение недоступно.

Степени интеграции

Минимальная

От ТК требуется реализация:

  • метода расчета тарифа на перевозку

В данной интеграции, если клиент выбирает предложение ТК, то сайт АТИ переадресовывает клиента на указанный этой ТК URL. Оформление заявки и все последующая работа производится клиентом на сайте ТК.

Средняя

От ТК требуется реализация:

  • метода расчета тарифа на перевозку
  • метода приема заявки на перевозку

В данной интеграции, клиент оформляет заявку на сайте АТИ полностью. Заполненную заявку сайт отправляет в ТК. Дальнейшее взаимодействие клиента и ТК происходит вне сайта АТИ. На сайте АТИ у клиента будет возможность просмотреть заявки, отправленные в ТК.

Полная

От ТК требуется реализация:

  • метода расчета тарифа на перевозку
  • метода приема заявки на перевозку
  • метода передачи статусов выполнения заявки на перевозку

В данной интеграции, оформляет полностью заявку на сайте АТИ полностью. При этом каждой заявке назначается уникальный id, по которому в дальнейшем система АТИ будет узнавать актуальный статус исполнения заявки. При изменениях статуса заявки система АТИ уведомляет клиента об изменениях. На сайте АТИ у клиента будет возможность просмотреть заявки, отправленные в ТК и их текущие статусы.

Рекомендации по интеграции

1. Заполняйте форму заказа перевозки автоматически

В запросе цен на перевозку груза (метод get_offers) вместе с данными о грузе на сторону ТК передается уникальный идентификатор груза - поле load_id. В случае, когда ТК готово выполнить перевозку и передает клиенту цену, можно сохранить в своей БД весь набор информации: load_id, "груз" и цену. Когда клиент переходит на сайт ТК (по нажатию кнопки "Подробнее") выполняется HTTP запрос методом POST, в параметрах которого также имеется load_id. По нему система ТК может найти в своей БД данные о грузе/цене и предзаполнить форму заявки. В том же запросе передаются данные об участнике АТИ и контактные данные, указанные в информации о грузе, размещаемом на сайте АТИ. Эту информацию также можно использовать, например для автоматического создания кабинета заказчика в системе ТК.

2. Производительность метода расчета тарифов

При реализации метода расчета тарифов (метод get_offers) нужно обращать внимание как на скорость его выполнения, так и на возможность параллельного выполнения нескольких запросов. В часы "пик" в системе АТИ может появляться 10-20 новых "грузов" в секунду от разных пользователей. При этом, от момента сохранения "груза" в системе АТИ до показа предложения ТК пользователю должно пройти не более 10 секунд.