API-интеграция

Введение

Для повышения удобства технического взаимодействия клиентов и партнёров транспортной компании КИТ был реализован простой и доступный программный интерфейс — КИТ.API, работающий поверх протокола HTTP.

Данное руководство описывает интерфейс доступа к КИТ API, и предназначено для программистов, автоматизирующих взаимодействие с нашей транспортной компанией КИТ.

Предполагается, что читатель знаком с основами HTTP и имеет навыки программирования. Технические вопросы не отражённые в данном документе можно задать на странице по этой ссылке.

  • 1. В КИТ.API пользователь генерирует параметр token в личном кабинете самостоятельно. Для этого в разделе "Разработчикам" появился пункт "Получение ключа API". Запрашивать его отдельно и ожидать модерации больше не требуется.
  • 2. Присутствует возможность удалять существующий token.
    Внимание: Ни одна функция с удаленным токеном работать не будет.
  • 3. Лимитирование количества запросов происходит на каждый отдельный token, а не на аккаунт token`a.
  • 4. Лимитирование разделяется по методам КИТ.API . Например: если Ваше приложение истратило лимит используя метод /1.0/order/create то блокировка метода /1.0/geography/email/get-list по лимиту не происходит. У каждого метода свой лимит для token.
  • 5. В случае превышения лимита будет возвращен статус страницы 429, а так же ответ формата {"name":"Too Many Requests","message":"Rate limit exceeded.","code":0,"status":429}.
  • 6. КИТ.API выведено на отдельный поддомен https://capi.tk-kit.com
  • 7. Каждый метод имеет вид /1.0/geography/email/get-list
    Таким образом URL для данного метода будет выглядеть следующим образом:
    https://capi.tk-kit.com/1.0/geography/email/get-list
Авторизация

В данном КИТ.API доступно 2 метода авторизации:

  • httpBearerAuth - реализация аутентификации по токену (HTTP Bearer token). Для авторизации с помощью токена нужно передать его в http заголовке Authorization: Bearer FFFF70it7tzNsHddEiq0BZ0i-OU8S3xV
  • queryParamAuth - Работает по тому-же принципу, что и HttpBearerAuth, т.е. идентифицирует пользователя по токену, только в данном случае токен передается в строке запроса, как GET параметр token.
Общий принцип взаимодействия

Параметр token является обязательным для всех методов КИТ.API . При отсутствии параметра token или в случае если он содержит невалидный token доступа будет возращен статус страницы 401, а так же ответ формата {"name":"Unauthorized", "message":"Your request was made with invalid credentials.", "code":0, "status":401}.

Транспортным протоколом для вызова функций КИТ.API является HTTPS. В КИТ.API поддерживаются как JSON, так и POST запросы. Внимание: В данной версии API не поддерживаются GET параметры (кроме параметра token).