Cloud API
Сценарий работы с устройством, арендованном в «облачном» сервисе.
Аннотация. Документ описывает сценарий использования протокола при работе с устройствами, арендованными в «облачном» сервисе
1. Сценарий
Для выполнения запросов на устройстве, подключённом к «облачному» сервису, необходимо скопировать из личного кабинета TOKEN предприятия, после чего выполнять запрос, описанный в данном документе.
Запрос необходимо выполнить методом POST по адресу:
https://kkt.interkassa.online/fr/api/v2/Complex
При выполнении запроса необходимо предоставить идентификатор (TOKEN) предприятия.
Управление сменами осуществляется автоматически. Смена автоматически откроется, при поступлении первого документа, и в дальнейшем будет автоматически пере открываться по мере необходимости.
2. Типы значений
В описании запросов используются следующие типы значений:
• uint8 — беззнаковое целое длиной 8 бит;
• uint16 — беззнаковое целое длиной 16 бит;
• uint32 — беззнаковое целое длиной 32 бита;
• uint64 — беззнаковое целое длиной 64 бита;
• string — строка;
• Money — беззнаковое целое длиной 64 бита, значение указывается в копейках;
• Quantity — беззнаковое целое длиной 64 бита, значение указывается в тысячных долях;
• date — дата (см. п. 2.1);
• time — время (см. п. 2.1);
• datetime — дата и время (см. п. 2.1);
• array of uint8 — массив из значений указанного типа, строка в кодировке Base64;
• <N> тип — массив из N значений указанного типа.
2.1. Дата и время
Даты передаются и возвращаются в виде:
{
"Day": 28,
"Month": 2,
"Year": 17
}
Где:
Day (uint8): день,
• Month (uint8): месяц, • Year (uint8): год.
Время передаётся и возвращается в виде:
{
"Hour": 13,
"Minute": 49,
"Second": 32
}
Где:
• Hour (uint8): количество часов
• Minute (uint8): количество минут
• Second (uint8): количество секунду
Значение комбинированного поля дата и время формируется следующим образом:
{
"Date": {
"Day": 28,
"Month": 2,
"Year": 17
},
"Time": {
"Hour": 13,
"Minute": 49,
"Second": 32
}
}
3. Полный список полей команды Complex
Поля запроса:
• Group (string): Идентификатор предприятия. Можно получить в личном кабинете.
• Device (string, обязательное): Должно иметь значение auto.
• RequestId (string, обязательное): Уникальный идентификатор запроса.
• ClientId (string): Идентификатор клиента. Идентификатор клиента удобно использовать, если у вас несколько сайтов и значение поля RequestId может иметь одинаковое значение.
• DocumentType (uint8, обязательное): Тип чека (см. табл. 1).
• Cash (Money): Сумма оплаты наличными. Если сумма равна нулю, то это поле можно опустить.
• NonCash (3 Money, обязательное): Массив из 3-х элементов с суммами оплат 3-х различных типов. Разделение по типам (например: Visa, MasterCard, Мир) используется исключительно для внутреннего учёта пользователя устройства. Если разбиение не требуется, то можно передавать в виде [1000, 0, 0].
• AdvancePayment (Money): Сумма оплаты предоплатой (зачётом аванса). Если сумма равна нулю, то это поле можно опустить.
• Credit (Money): Сумма оплаты постоплатой (в кредит). Если сумма равна нулю, то это поле можно опустить.
• Consideration (Money): Сумма оплаты встречным предоставлением. Если сумма равна нулю, то это поле можно опустить.
• TaxMode (uint8): Применяемая в чеке система налогообложения (см. табл. 3). Если при регистрации устройства в ФНС было выбрано более одного режима налогообложения, то в поле TaxMode необходимо указать, к какой системе относится данный чек (см. табл. 3). Если была выбрана одна система, то это поле можно опустить.
• PhoneOrEmail (string): Телефон или электронный адрес покупателя. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
• Place (string): Место расчётов. Если при регистрации кассы данный параметр не задан, его нужно передавать в каждом чеке.
• MaxDocumentsInTurn (uint16): Максимальное количество документов в одной смене.
• FullResponse (bool): Признак получения полного ответа. (true — получение полного ответа по всем командам, из которого строится запрос, аналогичный ответу команды Batch; false — получение сокращённого ответа)
• PaymentAgentModes (uint8, 1057): Режим агента для документа (см. табл. 5). Обратите внимание, что данное поле является битовой маской. В этом поле можно указать режим агента, который будет распространён на все записи в документе.
• UserRequisite (Структура с дополнительным реквизитом пользователя, тег 1084): Может включаться в состав чека с учётом особенностей сферы деятельности, в которой осуществляются расчёты.
– Title (string, тег 1085): Заголовок дополнительного реквизита пользователя
– Value (string, тег 1086): Значение дополнительного реквизита пользователя
• Person (string, тег 1021): Кассир
• PersonINN (string, тег 1203): ИНН кассира
• TransferOperatorData (Данные оператора перевода):
– Phones (array of string, тег 1075): Телефоны оператора перевода. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX». – Name (string, тег 1026): Наименование оператора перевода.
– Address (string, тег 1005): Адрес оператора перевода. – INN (string, тег 1016): ИНН оператора перевода.
• GetPaymentOperatorData (Данные оператора по приёму платежей):
– Phones (array of string, тег 1074): Телефоны оператора по приёму платежей.
Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
• AgentData (Данные платёжного агент):
– Operation (string, тег 1044): Операция платёжного агента.
– Phones (array of string, тег 1073): Телефоны платёжного агента. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
• ProviderData (Данные поставщика, тег 1224): – Phones (array of string, тег 1171): Телефоны поставщика. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
• CustomerName (string, тег 1227): Покупатель (клиент)
• CustomerINN (string, тег 1228): ИНН покупателя (клиента)
• Lines (Массив товарных позиций, обязательное):
– Qty (Quantity, обязательное): Количество. Количество указывается в тысячных долях, т.о если необходимо передать количество, например, 2,5 килограмма то в параметре следует указать 2500 (2,5 · 1000=2500).
– Price (Money, обязательное): Цена. Цена указывается в копейках. – PayAttribute (uint8): Признак способа расчёта (см. табл. 4).
– TaxId (uint8, обязательное): Код налога (1 – 6) (см. табл. 2). В примере ниже «НДС 20%».
– Description (string, обязательное): Наименование товарной позиции. Не может быть пустым.
– PayAttribute (uint8, тег 1214): Признак способа расчета (см таб. 4)
– LineAttribute (uint8, тег 1212): Признак предмета расчета (см таб. 6)
– AgentModes (uint8, тег 1222 ): Признак агента по предмету расчета (см таб. 5)
– IndustryProps (Отраслевой реквизит предмета расчета, тег 1260):
▪ Id (string, тег 1262 ): Идентификатор ФОИВ
▪ Data (date, тег 1263 ):
▪ Number (string, тег 1264 ):
▪ Value (string, тег 1265 ):
▪ Data (date, тег 1263 ):
▪ Number (string, тег 1264 ):
▪ Value (string, тег 1265 ):
– TransferOperatorData (Данные агента, тег 1223):
▪ Phone (string, тег 1075 ): Телефон оператора перевода.
▪ Name (string, тег 1026 ): Наименование оператора перевода
▪ Address (string, тег 1005 ): Адрес оператора перевода
▪ INN (string, тег 1016 ): ИНН оператора перевода
– GetPaymentOperatorData (Данные агента, раздел «Оператор по приёму платежей», тег 1223):
▪ Phone (string, тег 1074): Телефон оператора по приёму платежей. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
– AgentData (Данные агента, раздел «Платёжный агент», тег 1223):
▪ Operation (string, тег 1044): Операция платёжного агента.
▪ Phone (string, тег 1073): Телефон платёжного агента. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
– ProviderData (Данные поставщика, тег 1224):
▪ Phone (string, тег 1171): Телефон поставщика. Телефон передаётся в формате «7XXXXXXXXXX» или «7-XXX-XXX-XX-XX».
▪ Name (string, тег 1225): Наименование поставщика.
▪ INN (string, тег 1226): ИНН поставщика. ИНН поставщика формируется в значение тега 1226, которых входит в состав тега 1059 напрямую. В команде он указан в составе структуры «Данные поставщика» исключительно для группировки всех данных по поставщику в единой структуре.
– Excise (Money, тег 1229): Акциз
– CountryOfOrigin (string, тег 1230): Код страны происхождения товара
– NumberOfCustomsDeclaration (string, тег 1231): Номер таможенной декларации
– CGNRaw (string, тег 1162): Код товарной номенклатуры. HEX-строка
– AdditionalRequisite (string, тег 1191): Дополнительный реквизит предмета расчёта. Формат данных определяется ФНС России.
Сумма всех безналичных оплат (NonCash+AdvancePayment+Credit+Consideration) должна быть равна итогу чека, в противном случае устройство ответит ошибкой 69 или 77.
Следует обратить внимание на то, что в строках, передаваемых как значения полей Description, PhoneOrEmail и Place не должно быть символов, которые нельзя представить в кодировке CP866, т.к. эти данных сохраняются в памяти фискального накопителя, который работает в кодировке CP866.
Поля ответа:
• Device (Идентификация устройства, обработавшего запрос):
– Name (string): Заводской номер устройства
Response (Результат выполнения команды Complex):
– Error (uint8): Код ошибки (см. п. 8)
– ErrorMessages (array of string): Список сообщений, сформированных устройством при обработке запроса.
• Change (Money): Сдача.
• Date (datetime): Дата и время формирований документа.
• DeviceRegistrationNumber (string): Регистрационный номер устройства.
• DeviceSerialNumber (string): Заводской номер устройства.
• FNSerialNumber (string): Номер фискального накопителя, в котором сформирован документ.
• FiscalDocNumber (uint32): Номер фискального документа.
• FiscalSign (uint32): Фискальный признак документа.
• GrandTotal (Money): Итог чека.
• QR (string): QR-код чека.
Таблица 1. Типы документов
Таблица 2. Налоги
Таблица 3. Режим налогообложения
Таблица 4. Признак способа расчёта
Таблица 5: Признак агента
Таблица 6: Признак предмета расчёта
4. Пример запроса
{
"Device": "auto",
"ClientId": "<идентификатор клиента>",
"Password": 1,
"RequestId": "<уникальный идентификатор запроса>",
"Lines":
[
{
"Qty": 2500,
"Price": 10000,
"PayAttribute": 4,
"TaxId": 1,
"Description": "Булочка с маком"
},
{
"Qty": 500,
"Price": 200000,
"PayAttribute": 4,
"TaxId": 2,
"Description": "Икра чёрная, баклажанная"
}
],
"NonCash": [ 125000, 0, 0 ],
"TaxMode": 1,
"PhoneOrEmail": "user@example.com",
"Place": "www.example.com",
"FullResponse": false
}
5. Пример ответа
Такой ответ будет выдан, если поле FullResponse имеет значение false.
{
"RequestId": "D35",
"ClientId": "",
"Path": "/fr/api/v2/Complex",
"Response":
{
"Error": 0
},
"FiscalDocNumber": 31,
"DocNumber": 5,
"Date":
{
"Date":
{
"Day": 15,
"Month": 7,
"Year": 23
},
"Time":
{
"Hour": 14,
"Minute": 38,
"Second": 27
}
},
"GrandTotal": 125000,
"FiscalSign": 1879546968,
"DocumentType": 0,
"QR": "t=20170715T1438&s=1250.00&fn=9999078900006825&i=31&fp=1879546968&n=1",
"FNSerialNumber": "9999078900006825",
"DeviceSerialNumber": "00000000381001017439",
"DeviceRegistrationNumber": "3949620073015105"
}
Поле Error (см. п. 8) со значением 0, показывает, что команда была успешно выполнена и в фискальном накопителе был сформирован новый документ.
Если необходимо получить информацию об этом документе, то необходимо в поле FullResponse передать значение true: в таком случае будет сформирован ответ, который будет включать полную информацию о сформированном в устройстве фискальном документе, включая его содержимое, хранящееся в фискальном накопителе, а так же текст чека, который бы распечатало устройство, если бы к нему был подключён принтер. Структура ответа показана в описании команды CloseDocument в документе «Протокол взаимодействия...».
6. Пример кода на PHP
<?php
$url = "https://kkt.interkassa.online/fr/api/v2/Complex";
// Базовая структура запроса
$datas = array(
// Всегда должно быть "auto"
"Device" => "auto",
"Group" => "d4b15d86-5feb-11e7-82ef-00155d00c805", // указан тестовый Token
'RequestId' => uniqid(),
"Lines" => array(),
// Всегда должен быть массив из 3-х элементов.
// 1-й содежрит сумму оплаты элетронными (безналичными)
// оставшиеся 2 должны быть заполнены нулями.
// Сумма всех элементов массива должна быть
// в точности равна итогу чека
"NonCash" => array(30000, 0, 0),
// Указываем код СНО,
"TaxMode" => 1,
"PhoneOrEmail" => "info@interkassa.online",
);
// Товар 1: 1 * 100.00 = 100.00
$datas['Lines'][]=array(
// Количество передается в тысячных долях
// например:
// 2.5 кг -> 2.5 * 1000 = 2500
// 42 шт. -> 42 * 1000 = 42000
// 500 табл. -> 500 * 1000 = 500000
// 0.5 упак. -> 0.5 * 1000 = 500 // 1 шт. -> 1 * 1000 = 1000
"Qty" => 1000,
// Цена в копейках
"Price" => 10000,
"PayAttribute" => 4,
"TaxId" => 1,
"Description"=> 'Тестовый товар 1',
);
// Товар 2: 2 * 100.00 = 200.00
$datas['Lines'][]=array(
"Qty" => 2000,
"Price" => 10000,
"PayAttribute" => 4,
"TaxId" => 1,
"Description"=> 'Тестовый товар 2',
);
$mydatas = json_encode($datas);
var_Export($mydatas);
$curl = curl_init();
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-type: application/json"));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $mydatas);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_URL,$url);
$json_response = curl_exec($curl);
print "json_response: $json_response\n";
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE); var_dump($status);
$lastError = curl_error($curl);
print "lastError :$lastError\n";
print "Status :$status\n";
curl_close($curl);
$response = json_decode($json_response);
var_dump($response);
?>
7. Ошибки «облачного» сервиса
При ошибках, возникающих при работе «облачного» сервиса возвращается ошибка HTTP с номеров 500 и структура, содержащая поля: FCEError, ErrorDescription и Device, Fatal.
Поле FCEError содержит код ошибка из таблицы 5.
Поле ErrorDescription содержит описание ошибки или дополнительную информацию.
Поле Device содержит информацию об устройстве с которым связана ошибка.
Поле Fatal со значением true показывает, что повторное выполнение запроса приведёт к ошибке.
Таблица 5: Ошибки «облачного» сервиса
7.1. Ошибка чтения запроса
Сервер не смог прочитать тело запроса, пришедшего от клиента. Необходимо проверить, правильно ли указана длина запроса в заголовке.
7.2. Ошибка распознавания JSON
Сервер не смог правильно преобразовать JSON в свои внутренние структуры данных. Необходимо проверить правильность переданного JSON, а так же соответствие типов полей сервера указанным в документации.
7.3. Нет подходящих устройств (согласной выбранной стратегии)
Сервер попытался найти подходящее устройство за TryCount попыток. Необходимо изменить условия стратегии либо увеличить значение поля TryCount.
7.4. Ошибка распознавания JSON ответа
От устройства был получен ответ, который не содержит корректный JSON. При получении этой ошибки сервер переведёт устройство в неактивное состояние.
7.5. Устройство занято
Было выбрано устройство, которое получило другой запрос раньше, чем данный. После ожидания WaitForFree секунд, сервер вернёт ошибку «Устройство занято».
8. Ошибки устройства
Таблица 6: Коды ошибок устройства
Ниже будут описаны некоторые из ошибок более подробно.
8.1. Параметр команды содержит неверные данные (51)
1. Ошибка при преобразовании строковых данных из кодировки UTF-8 в кодировку Windows-1251.
2. Значение реквизита «признак способа расчёта» отличается от перечисленных в табл. 4 или не соответствует условиям изложенным там же.
3. Код налога выходит за пределы диапазона 1 ... 6.
4. В команде SetTableField тип поля Value не соответствует значения поля ValueType.
5. Параметр «Применяемая в документе (чеке) система налогообложения» имеет более одного установленного бита, причём этот бит должен один из тех, которые были указаны при регистрации.
6. Строка содержит символы, недопустимые в кодировке CP866.
7. Пустое наименование товарной позиции.