Общие требования и соглашения

Формат запросов

Запросы в систему API отправляются через протокол HTTP. Все запросы и ответы — в формате JSON. Поэтому в заголовке каждого запроса должен отправляться параметр:

Content-Type: application/json
Authorization: Bearer 123TOKEN123

Токен нужно получить авторизовавшись (см. Получить токен) 123TOKEN123

Параметры в теле запроса должны начинаться с заглавной буквы в формате CamelCase.

Формат данных

Общий формат ответа от API:

{ 
  "Status": 200,
  "Message": "ОK",
  "Data": { object }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Status	int	HTTP-код статуса обработки запроса
Message	string	Сообщение с описанием результата обработки запроса
Data	object	Объект, содержащий данные ответа на запрос

Параметр Data — всегда объект. Если в ответе от эндпоинта ожидается хеш с массивом, то он будет в параметре с названием запрашиваемого ресурса:

{ 
  "Status": 200,        
  "Message": "ОK",      
  "Data": {              
     "Kkms": [ array ]
    }            
  } 
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Kkms	array	Пример ответа с массивом

Идентификатор корневого ресурса в теле ответа всегда Id :

{ 
  "Status": 200,        
  "Message": "ОK",      
  "Data": {              
    "Kkm": {
      "Id": 1,
      ...
    }            
  } 
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Kkm	object	Получить данные о кассе (см. GET /kkms/:IdKkm)
Id	int	Идентификатор ККМ

Идентификаторы связанных ресурсов начинаются с префикса Id :

IdKkm
IdShift
IdBalance
IdTypeBalance
...

Значения справочников не удаляются. У каждого элемента справочника есть параметр:

active: true

Неиспользуемые элементы отключаются переключением параметра active в false . При прямом запросе справочника на чтение отключенные элементы возвращаться не будут. Но неактивные значения справочника разрешено считывать через вложенный документ для ссылочной целостности.

Формат ошибок

Все эндпоинты возвращают одинаковый ответ с ошибкой, если не удалось распарсить тело запроса как валидный JSON, либо неправильный формат запроса:

{
  "Status": 400,
  "Message": "Bad request"
}

Описание ошибки:

Параметр	Описание параметра
Status	Дублирует HTTP-статус результата обработки запроса. Если в процессе обработки запроса произошла ошибка, то понять это можно по стандартному коду HTTP-статуса либо по значению параметра Status
Message	Если произойдет ошибка, то ее описание будет в параметре Message

{
  "Status": 401,
  "Message": "Unauthorized: token is expired by 2h36m46s"
}

Идемпотентность и последовательность запросов на создание чековых операций

Чековые операции поддерживают механизм идемпотентности и защиту от одновременных запросов.

Идемпотентная операция — это операция, которая при многократном вызове возвращает один и тот же результат. Для обеспечения идемпотентности необходимо передавать параметр Uid в заголовке запроса. В нем следует указать Uid -строку (ключ идемпотентности).

Когда сервис получит запрос с параметром Uid в заголовке, он проверит, была ли ранее создана операция с таким ключом. Если операция была создана, сервер вернет данные на ранее созданную операцию, указав в статусе и сообщении, что она была сохранена ранее:

{
  "Status": 208,
  "Message": "Уже сообщалось",
  "Data": { object }
}

Если ключ корректный и сервис не найдет операции с таким Uid , то сохранит ее как новую операцию.

Если не считать Uid из заголовка ответа и отправить устаревший Uid или eсли Uid не был отправлен в заголовке запроса, то операция вернет ошибку:

Описание ошибки

Status	Message	Способ устранения	Примечание
452	Некорректный Uid	Получить новый Uid

Получить Uid

Если смена уже открыта, но по каким-то причинам актуальный Uid не был сохранен, его можно получить, сделав запрос в эндпоинт.

GET /uid/:IdKkm 

В ответ придет новый актуальный Uid:

Возвращает данные:

{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Uid": "df225748-4ga4-4573-9fe8-6e45851d2874"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Uid	string	Актуальный Uid

Ошибки

Status	Message	Способ устранения	Примечание
429	Использовать эту операцию разрешается не чаще чем раз в 5 минут	Подождать 5 минут	Запрашивать Uid таким способом можно раз в 5 минут. Если запрашивать чаще, то в ответ эндпоинт вернет ошибку

Блок-схема