API - общие положения

Общие положения

API предназначен для интеграции торговых систем клиента с сервисом HEADO и поддерживает JRPC 2.0-протокол вызова методов.

Методы API делятся на два раздела:

• Device API - для взаимодействия с устройством;
• Management API - для взаимодействия в рамках торговой сети.

Протокол обмена данными

Запрос представляет собой JSON-сериализованный объект отправляемый с помощью POST-метода в виде RAW_POST_DATA

1
2
3
4
5
6
7

{
                        "jsonrpc":"2.0",
                        "id": "[Свободно-генерируемый идентификатор запроса]"
                        "method": "[Название вызываемого метода]",
                        "params":  [объект или массив аргументов вызываемого метода]
                       }
                    }

Ответ так же является JSON-сериализованным объектом

1
2
3
4
5

{
                        "jsonrpc":"2.0",
                        "id":"[Идентификатор запроса на который дан ответ]"
                        "result":[Любой тип данных - объект, массив, значение]
                      }

или отрицательный

1
2
3
4
5
6
7
8

{
                        "jsonrpc":"2.0",
                        "id":"[Идентификатор запроса на который дан ответ]"
                        "error": {
                        "code":"[Код ошибки]",
                        "message":"[Человекочитаемое пояснение ошибки]"
                        }
                      }

Список ошибок

Требования к надежности потоков данных

Надежность потоков данных должна обеспечиваться комплексом организационно-технических мероприятий отладки, поиска и исключения ошибок, а также технологическими процедурами резервирования.

При реализации потоков данных должны обеспечиваться:

• защита от потери данных в условиях возможных сбоев и отказов канала передачи данных, доступности API HEADO;
• диагностика сбоев и отказа канала передачи данных и доступности API HEADO;
• протоколирование событий при передаче данных с возможностью последующего анализа причин возникновения критических ситуаций.

В качестве мер по повышению надежности потоков данных должны быть предусмотрены:

• мониторинг доступности API HEADO;
• отложенная передача данных в случае недоступности API HEADO (прогрессивная задержка повторной передачи, например: 0, 3, 30, 60 сек, и.т.д.);
• обработка ошибок, возвращаемых API HEADO;
• повторная отправка данных в случае наличия ошибок API HEADO;
• диагностика ошибок с помощью программных средств контроля.

Общие интеграционные практики

1. При передаче значений в API стоит учитывать, что с данными работают люди через интерфейсы. Далеко не во всех интерфейсах отображаются non-printable characters и ведущие/хвостовые пробелы, по умолчанию данные от них нужно предварительно очищать
2. В некоторых случаях интеграций важно сквозное сопоставление данных, например при headless-интеграции с ОФД, в которой Пользователь несёт ответственность за качество и представимость данных

Внешние идентификаторы

• Внешние идентификаторы (store_ext_id, kpi_ext_id, ext_id сотрудника и др.) сравниваются точно, с учётом регистра: tt1 и TT1 — разные идентификаторы.
• Рекомендуемый набор символов — латинские буквы, цифры, -, _.
• Кириллица в kpi_ext_id не поддерживается.
• Пробел и / сервис принимает, но использовать их не рекомендуется: / — разделитель в пути @store_ext_id/pos_ext_id, а пробелы легко потерять при очистке данных (п.1).