Общие требования и соглашения
Формат запросов
Запросы в систему API отправляются через протокол HTTP. Все запросы и ответы — в формате JSON. Поэтому в заголовке каждого запроса должен отправляться параметр:
1 2
Content-Type: application/json Authorization: Bearer 123TOKEN123
Токен нужно получить авторизовавшись (см. Получить токен) 123TOKEN123
Параметры в теле запроса должны начинаться с заглавной буквы в формате CamelCase.
Форм ат данных
Общий формат ответа от API:
1 2 3 4 5
{ "Status": 200, "Message": "ОK", "Data": { object } }
Описание переменных
Название переменной | Тип переменной | Описание переменной |
---|---|---|
Status | int | HTTP-код статуса обработки |
Message | string | Сообщение об обработке запроса |
Data | object | Данные ответа на запрос |
Параметр Data
— всегда объект. Если в ответе от эндпоинта ожидается хеш с массивом, то он будет в параметре с названием запрашиваемого ресурса:
1 2 3 4 5 6 7 8
{ "Status": 200, "Message": "ОK", "Data": { "Kkms": [ array ] } } }
Описание переменных
Название переменной | Тип переменной | Описание переменной |
---|---|---|
Kkms | array | Пример ответа с массивом |
Идентификатор корневого ресурса в теле ответа всегда Id
:
1 2 3 4 5 6 7 8 9 10
{ "Status": 200, "Message": "ОK", "Data": { "Kkm": { "Id": 1, ... } } }
Описание переменных
Название переменной | Тип переменной | Описание переменной |
---|---|---|
Kkm | object | Получить данные о кассе (см. GET /kkms/:IdKkm) |
Id | int | Идентификатор ККМ |
Идентификаторы связанных ресурсов начинаются с префикса Id
:
1 2 3 4 5
IdKkm IdShift IdBalance IdTypeBalance ...
Значения справочников не удаляются. У каждого элемента справочника есть параметр:
1
active: true
Неиспользуемые элементы отключаются переключением пар аметра active
в false
. При прямом запросе справочника на чтение отключенные элементы возвращаться не будут. Но неактивные значения справочника разрешено считывать через вложенный документ для ссылочной целостности.
Формат ошибок
Все эндпоинты возвращают одинаковый ответ с ошибкой, если не удалось распарсить тело запроса как валидный JSON, либо неправильный формат запроса:
1 2 3 4
{ "Status": 400, "Message": "Bad request" }
Описание ошибки:
Параметр | Описание параметра |
---|---|
Status | Дублирует HTTP-статус результата обработки запроса. Если в процессе обработки запроса произошла ошибка, то понять это можно по стандартному коду HTTP-статуса либо по значению параметра Status |
Message | Если произойдет ошибка, то ее описание будет в параметре Message |
1 2 3 4
{ "Status": 401, "Message": "Unauthorized: token is expired by 2h36m46s" }
Идемпотентность и последовательность запросов на создание чековых операций
Чековые операции поддерживают механизм идемпотентности и защиту от одновременных запросов.
Идемпотентная операция — это операция, которая при многократном вызове возвращает один и тот же результат. Для обеспечения идемпотентности необходимо передавать параметр Uid
в заголовке запроса. В нем следует указать Uid
-строку (ключ идемпотентности).
Когда сервис получит запрос с параметром Uid
в заголовке, он проверит, была ли ранее создана операция с таким ключом. Если операция была создана, сервер вернет данные на ранее созданную операцию, указав в статусе и сообщении, что она была сохранена ранее:
1 2 3 4 5
{ "Status": 208, "Message": "Уже сообщалось", "Data": { object } }
Если ключ корректный и сервис не найдет операции с таким Uid
, то сохранит ее как новую операцию.
Если не считать Uid из заголовка ответа и отправить устаревший Uid
или eсли Uid
не был отправлен в заголовке запроса, то операция вернет ошибку:
Описание ошибки
Status | Message | Способ устранения | Примечание |
---|---|---|---|
452 | Некорректный Uid | Получить новый Uid |
Получить Uid
Если смена уже открыта, но по каким-то причинам актуальный Uid
не был сохранен, его можно получить, сделав запрос в эндпоинт.
1
GET /uid/:IdKkm
В ответ придет новый актуальный Uid:
Возвращает данные:
1 2 3 4 5 6 7
{ "Status": 200, "Message": "OK", "Data": { "Uid": "df225748-4ga4-4573-9fe8-6e45851d2874" } }
Описание переменных
Название переменной | Тип переменной | Описание переменной |
---|---|---|
Uid | string | Актуальный Uid |
Ошибки
Status | Message | Способ устранения | Примечание |
---|---|---|---|
429 | Использовать эту операцию разрешается не чаще чем раз в 5 минут | Подождать 5 минут | Запрашивать Uid таким способом можно раз в 5 минут. Если запрашивать чаще, то в ответ эндпоинт вернет ошибку |