В документе приводятся технические сведения о программном интерфейсе приложений (API) предоставляющем возможность регистрировать онлайн-кассы и инициировать генерацию кассовых документов посредством информационной системы (ИС) “Venda”.
Обмен данными с онлайн-кассами происходит по протоколу HTTP с использованием зашифрованного канала (HTTPS). Данные запросов и ответов передаются в виде структуры JSON. Вне зависимости от наличия ошибок в данных, обязательным условием успешного выполнения запроса является ответ с кодом 200 согласно протоколу HTTP.
Ниже описаны запросы HTTP, которыми реализуются функции API по работе с онлайн-кассами.
Кодировка, используемая в запросах и ответах – UTF-8. Запросы выполняются методом POST, параметры запроса передаются в JSON структуре, передаваемой в блоке данных запроса.
Ответы выдаются сервером в формате JSON и, в случае успешности ответа согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:
{
"Status":
"Success",
"Data": {}
}
Здесь ключу "Data" соответствует пустое поле; ключ введен в структуру для обеспечения единообразия запросов в ИС “Venda”; параметр "Status" – состояние обработки запроса – в данном случае имеет значение "Success" (запрос обработан успешно).
В случае неуспешности ответа (код ответа по протоколу HTTP не равен 200) данные имеют следующий обобщенный вид:
{
"Status": "Failed",
"Error": {
Code:
0,
Message: "string"
}
}
Здесь ключу "Error" соответствует объект, в котором присутствуют код и сообщение об ошибке; код ошибки всегда отличен от 0; на месте строки"string" будет сообщение об ошибке, возникшей при обработке переданных данных. параметр "Status" в данном случае имеет значение "Failed" (обработка запроса не удалась).
Возможность множественных обращений к ИС “Venda” после одной авторизации без использования механизма Cookies реализуется с помощью механизма AuthToken: после авторизации с передачей имени и пароля система возвращает код авторизации – строку символов, которая используется, как параметр авторизации при обращении к соответствующему личному кабинету (ЛК). HTTP-запрос авторизации, передающий имя пользователя и пароль в формате JSON выглядит следующим образом:
--- BEGIN ---
POST https://venda.ofd.ru/api/Authorization/CreateAuthToken HTTP/1.1
Content-Length: 38
Content-Type: application/json; charset=utf-8
{"Login": "12345","Password": "56789"}
--- END ---
В данном запросе присутствуют примеры значений: передаваемое имя пользователя – "12345" и пароль – "56789"; они задаются как значения в JSON-структуре внутри запроса с ключами "Login" и "Password" соответственно. В ответ на данный запрос будет получен ответ по протоколу HTTP, который в случае успешной авторизации будет иметь код равный 200 и содержать структуру, подобную следующей (приведены примеры значений):
{
"AuthToken": "f3accdfda7574736ba94a78d00e974f4",
"ExpirationDateUtc": "2017-01-24T14:13:24"
}
Здесь с ключом "AuthToken" – код авторизации: строка символов AuthToken, представляет собой 32-значную последовательность шестнадцатеричных цифр, используемую для повторной аутентификации, а ключ "ExpirationDateUtc" – строка, описывающая момент времени (дату и время в формате UTC), до которого будет действовать данный код авторизации.
Момент времени задается в формате "ГГГГ-ММ-ДДTчч:мм:сс"; здесь
ГГГГ | – | год даты, 4 цифры, |
ММ | – | месяц даты, 2 цифры, |
ДД | – | день даты 2 цифры, |
T | – | заглавная латинская буква “T”, используется как разделитель даты и времени, |
чч | – | часы, 2 цифры, |
мм | – | минуты, 2 цифры, |
сс | – | секунды, 2 цифры. |
В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 403) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «{}»). Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация. Пример запроса с использованием кода авторизации:
POST /api/kkt/cloud/receipt?AuthToken=Code1
здесь Code1 – действующий код авторизации, полученный в результате запроса авторизации.
Вид запроса: POST /api/kkt/cloud/receipt. Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:
{
"Request": {
"Inn":
"string",
"Type": "string",
"InvoiceId": "string",
"LocalDate": "2017-01-24T14:13:24",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "string",
"Phone": "string",
"Items": [
{
"Label": "string",
"Price": 0,
"Quantity": 0,
"Amount": 0,
"Vat": "string"
}, ...
]
}
}
}
Параметры структуры приведены в таблице 2.
Таблица 2. Параметры структуры данных запроса на формирование кассового чека
Ключ | Формат значения | Описание |
---|---|---|
Request | структура | Параметры запросы на формирование кассового документа |
Inn | строка | ИНН лица, от имени которого генерируется кассовый документ (чек) |
Type | строка | Тип формируемого документа (чек), см. п. 3.1.2 |
InvoiceId | строка | Идентификатор счета, на основании которого генерируется чек |
LocalDate | строка, описывающая момент времени (дату и время) | Локальная дата и время чека |
CustomerReceipt | структура | Содержимое клиентского чека |
TaxationSystem | строка | Система налогообложения |
строка | Адрес электронной почты клиента | |
Phone | строка | Контактный телефон клиента |
Items | массив структур | Товарные позиции, приобретаемые клиентом |
Label | строка | Название товарной позиции |
Price | число с точкой | Цена товарной позиции, в рублях |
Quantity | число с точкой | Количество товара в товарной позиции |
Amount | число с точкой | Общая стоимость товара в товарной позиции в рублях |
Vat | строка | Вид вычисляемого подоходного налога см. п. 3.1.1 |
Все вышеуказанные поля являются необходимыми, за исключением полей Email и Phone, здесь необходимым является наличие хотя бы одного из них.
В случае успеха ответ имеет следующий вид:
{
"Status": "Success",
"Data": {
"ReceiptId": "string"
}
}
Параметры структуры «Data» приведены в таблице 3.
Таблица 3. Параметры структуры данных запроса на формирование кассового чека
Ключ | Формат значения | Описание |
---|---|---|
ReceiptId | строка, содержащая UUID | Идентификатор чека для дальнейшего запроса состояния |
Сформированный чек будет считаться корректным, если он соответствует следующим условиям:
Важно! Информация о статусе имеет срок годности (сутки), после которого перестает быть доступна. После истечения этого срока, при попытке запроса статуса вернется ошибка «Чек не найден». Это означает, что информация по данному чеку удалена из оперативной памяти для освобождения ресурсов, но она остается доступна при помощи запроса реестра кассовых чеков (3.3).
Вид запроса:.
POST /api/kkt/cloud/status
Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:
{
"Request": {
"RecieptId": "string"
}
}
Параметры структуры приведены в таблице 3.
Таблица 3. Параметры структуры данных запроса статуса кассового чека
Ключ | Формат значения | Описание |
---|---|---|
Request | структура | Параметры запроса статуса кассового документа |
RecieptId | строка | Идентификатор чека, полученный из запроса на формирование кассового документа |
В случае успеха ответ имеет следующий вид:
{
"Status": "Success",
"Data": {
"StatusCode": 1,
"StatusName": "PROCESSED",
"StatusMessage": "Чек сформирован на кассе",
"ModifiedDateUtc": "2017-01-24T14:13:24",
"ReceiptDateUtc": "2017-01-24T14:13:24",
"Device": {
"DeviceId": "string",
"RNM": "string",
"ZN": "string",
"FN": "string",
"FDN": "string",
"FPD": "string",
}
}
}
Параметры структур Data и Device приведены соответственно в таблицах 3.1 и 3.2.
Таблица 3.1 Параметры структуры данных информации о кассовом чеке
Ключ | Формат значения | Описание |
---|---|---|
StatusCode | Число | Код статуса |
StatusName | строка | Название статуса |
StatusMessage | строка | Необязательный параметр, содержащий дополнительную информацию о текущем состоянии, может отсутствовать |
ModifiedDateUtc | строка, описывающая момент времени (дату и время в формате UTC) | Дата и время последнего обновления информации о чеке |
ReceiptDateUtc | строка, описывающая момент времени (дату и время в формате UTC) | Дата и время, указанные в чеке |
Device | структура | Информация об устройстве (ККТ), на котором была произведена операция |
Возможные значения:
запрос на чек принят Фермой
"StatusCode": 0,
"StatusName": "NEW",
"StatusMessage": "запрос на чек принят Фермой",
чек сформирован на кассе
"StatusCode": 1,
"StatusName": "PROCESSED",
"StatusMessage": "чек сформирован на кассе",
чек передан в ОФД
"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "чек передан в ОФД"
Таблица 3.2 Параметры структуры данных информации о ККТ
Ключ | Формат значения | Описание |
---|---|---|
DeviceId | строка | Сервисный идентификатор устройства, на котором генерируется кассовый документ (чек) |
RNM | строка | Регистрационный номер кассы |
ZN | строка | Заводской номер кассы |
FN | строка | Номер фискального накопителя, установленного в кассу |
FDN | строка | Номер фискального документа |
FPN | строка | Фискальный признак документа |
Вид запроса:
POST /api/kkt/cloud/list
Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:
{
"Request": {
"ReceiptId": "e0d2212f-4e85-475a-8e6e-c533f233e1d9",
"StartDateUtc": "2017-01-24T14:13:24",
"EndDateUtc": "2017-01-24T14:13:24",
"StartDateLocal":
"2017-01-24T14:13:24",
"EndDateLocal": "2017-01-24T14:13:24"
}
}
В случае наличия не пустого параметра "ReceiptId" остальные могут отсутствовать; в случае наличия не пустых параметров "StartDateUtc" и "EndDateUtc" остальные могут отсутствовать; в случае наличия не пустых параметров "StartDateLocal" и "EndDateLocal" остальные могут отсутствовать. Параметры структуры приведены в таблице 4.
Таблица 4. Параметры структуры данных запроса статуса кассового чека
Ключ | Формат значения | Описание |
---|---|---|
Request | структура | Параметры запроса статуса кассового документа |
RecieptId | строка в формате UUID | Идентификатор чека, полученный из запроса на формирование кассового документа |
StartDateUtc | строка, описывающая момент времени (дату и время в формате UTC) | Дата и время начала интервала |
EndDateUtc | строка, описывающая момент времени (дату и время в формате UTC) | Дата и время окончания интервала |
StartDateLocal | строка, описывающая момент времени (дату и время) | Локальная дата и время начала интервала |
EndDateLocal | строка, описывающая момент времени (дату и время) | Локальная дата и время окончания интервала |
В случае успеха ответ имеет следующий вид:
{
"Status": "Success",
"Data": [
{
"ReceiptId": "e0d2212f-4e85-475a-8e6e-c533f233e1d9",
"StatusCode": 1,
"StatusName": "Чек сформирован на кассе",
"StatusMessage": "PROCESSED",
"ModifiedDateUtc": "2017-01-24T14:13:24",
"InvoiceID": "50000249010"
}, ...
]
}
Параметры структуры элементов массива «Data» приведены в таблице 4.1.
Таблица 4.1 Параметры структуры данных запроса на формирование кассового чека
Ключ | Формат значения | Описание |
---|---|---|
RecieptId | строка | Идентификатор чека, полученный из запроса на формирование кассового документа |
StatusCode | Число | Код статуса |
SatusName | строка | Название статуса |
SatusMessage | строка | Необязательный параметр, содержащий дополнительную информацию о текущем состоянии, может отсутсвовать |
ModifiedDateUtc | строка, описывающая момент времени (дату и время в формате UTC) | Дата и время последнего обновления информации о чеке |
InvoiceID | строка | Идентификатор (номер) счета, связанного с кассовым документом (Идентификатор чека со стороны клиента) |
HTTP Код | Код ошибки | Описание ошибки |
401 | 1001 | Клиент не авторизован |
500 | 1002 | Непредвиденная ошибка |
400 | 1003 | Некорректный формат запроса |
404 | 1004 | Объект не найден |
500 | 1 | Неизвестная ошибка |
500 | 2 | Неверный логин, пароль |
500 | 3 | Нет свободных касс |
500 | 4 | Нет авторизации |
400 | 1005 | Объект Request пустой |
400 | 1006 | Объект CustomerReceipt пустой |
400 | 1007 | Некорректный ИНН |
400 | 1008 | Некорректный тип формируемого чека (Type) |
400 | 1009 | Некорректный идентификатор счета (InvoiceId) |
400 | 1010 | Некорректный тип налогооблажения (TaxationSystem) |
400 | 1011 | Некорректно заполнены контакты (Email, Phone) |
400 | 1012 | Некорректный адрес электронной почты |
400 | 1013 | Некорректный номер телефона |
400 | 1014 | Некорректно заполнены позиции (Items) |
400 | 1015 | Цена и общая стоимость не должны быть отрицательными |
400 | 1016 | Количество товаров в позиции не должно быть отрицательным |
400 | 1017 | Некорректно заполнен подоходный налог позиции (Vat) |
400 | 1018 | Общая сумма позиций должна быть неотрицательной |
400 | 1019 | Идентификатор счета уже существует (InvoiceId), (--ReciptID--) |
400 | 1020 | Превышено максимальное количество обращений |
Версия 1.0
Выпущена 24 августа 2018 г.
Первая версия документа.