Подключение к API

Требования к организации подключения

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

Модель взаимодействия

API использует модель RESTful (данные передаются в виде объектов JSON). Особенностью является использование партнером и Cardsmobile двух интерфейсов:

• Push API — используется партнером для отправки пуш-сообщений;

• Callback API — используется Cardsmobile для передачи информации о доставке и прочтении сообщений.

Взаимодействие партнера и Cardsmobile

Параметры подключения

Push API

Провайдером Push API выступает узел Cardsmobile.

Партнеру передаются следующие параметры для подключения к API:

Параметры	Описание
host:port	Адрес узла Cardsmobile, предоставляющего API.
login:password	Имя пользователя и пароль для авторизации API-запросов.

Количество учетных записей не ограничено, при этом каждая учетная запись определяет:

• партнера, клиентам которого отправляются сообщения;

• адрес Callback API для информировании о доставке и прочтении сообщений.

Callback API

Провайдером Callback API выступает узел партнера.

Партнеру необходимо предоставить «обратный» URL-адрес, который будет использоваться хостом Cardsmobile для информирования о доставке и прочтении отправляемых сообщений.

Авторизация запросов

Взаимодействие осуществляется по протоколу HTTPS. Для авторизации запросов к Push API необходимо использовать HTTP Basic Authentication (RFC 7617). Данные для авторизации запросов передаются в HTTP-заголовке Authorization.

Требования к кодировкам

Как в запросах, так и в ответах используется кодировка UTF-8.

Коды HTTP

В случае успешного выполнения запроса со стороны узла Cardsmobile будет возвращен тип данных, описанный в документации запроса, и HTTP-код 200.

Код	Назначение
200	Возвращается в случае успешного выполнения запроса API.

В случае ошибки обработки запроса будет возвращен один из HTTP-кодов с описанием ошибки в теле ответа в формате JSON:

Код	Назначение
304	Новый запрос поступил ранее ожидаемого времени.
400	Неверный формат запроса.
401	Ошибка авторизации.
404	Не найден запрашиваемый тип данных.

Примеры тела ошибки:

HTTP: 400

{
    "status": "BAD_REQUEST",        // статус HTTP ошибки
    "errors": [                     // массив ошибок
        "msisdn: size must be between 0 and 10000", // описание ошибки
        "subId: may not be null"
    ]
}

HTTP: 401

{
    "status": "UNAUTHORIZED",
    "errors": [
        "Auth token is invalid"
    ]
}