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).