Помогаем продавать
Войти в ЛК

Программный интерфейс приложений (API) проверки чека услуги «QR Cash» (по БД ФНС)

Версия 1.6 от 11.01.2021 Открыть pdf-файл

Введение

В документе приводятся технические сведения о программном интерфейсе приложений (API) услуги «QR Cash» предоставляющем возможность проверки чеков в рамках данной услуги.
Обмен данными с онлайн-кассами происходит по протоколу HTTP с использованием зашифрованного канала (HTTPS). Данные запросов и ответов передаются в виде структуры JSON.
Ниже описаны запросы HTTP, которыми реализуются функции API «QR Cash».

1. Запросы «QR Cash»

1.1. Запрос фискального документа ФНС

Запрос на выгрузку фискального документа из базы данных ФНС имеет вид:

POST https://ofd.ru/api/partner/v3/receipts/GetReceipt

Входные параметры данного запроса передаются в его теле в виде структуры данных в формате JSON. Все параметры для выполнения успешного запроса являются обязательными. Пример запроса приведен ниже:

{
    "TotalSum": 74204,
    "DocDateTime": "2019-04-08T10:46:00.000",
    "FnNumber": "9286000100012345",
    "ReceiptOperationType": "1",
    "DocNumber": "356",
    "DocFiscalSign": "987654321",
    "tokenSecret": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

Список полей этой структуры c их описаниями представлен в таблице 1.

Таблица 1. Поля данных запроса фискального документа ФНС

Идентификатор Формат поля Назначение
TotalSum Целое число Сумма всего по фискальному документу (в копейках)
DocDateTime Дата и время в формате ISO YYYY-MM-DDThh:mm:ss[.SSS] 1) Дата формирования фискального документа
FnNumber Строка Номер фискального накопителя, установленного в кассу (заводской, серийный)
ReceiptOperationType Строка Тип операции, соответствующей фискальному документу:
“1” — приход средств (кассовый чек (БСО), кассовый чек коррекции (БСО коррекции);
“2” — возврат прихода (кассовый чек (БСО));
“3” — расход средств (кассовый чек (БСО), кассовый чек коррекции (БСО коррекции);
“4” — возврат расхода (кассовый чек (БСО)).
DocNumber Строка Номер документа на фискальном накопителе
DocFiscalSign Строка Фискальный признак документа
tokenSecret Строка, содержащая uuid Уникальный ключ, который позволяет получить информацию по фискальному документу ФНС. Напишите нам, чтобы получить ключ.

Ответ на данный запрос также содержит структуру данных в формате JSON, пример ответа в общем виде приведен ниже, поля описаны в таблице 2.
В зависимости от особенностей чека, наличие описанных ниже полей опционально.

{
"Success": true,
    "Data": {
        "Version": 3,
        "DocumentFormat": "1.05",
        "Document": {
            "DocumentName": "string",
            "Tag": 3,
            "User": "string",
            "UserInn": "string",
            "Number": 11,
            "DateTime": "2019-04-08T10:46:00",
            "ShiftNumber": 27,
            "OperationType": 1,
            "TaxationType": 1,
            "Operator": "string",
            "KKT_RegNumber": "0003016009004321",
            "FN_FactoryNumber": "9286000100012345",
            "Items": [
                {
                    "Name": "string",
                    "Price": 74204,
                    "Quantity":1.0,
                    "Nds18_TotalSumm": null,
                    "Nds10_TotalSumm": null,
                    "Nds00_TotalSumm": null,
                    "NdsNA_TotalSumm": null,
                    "Nds18_CalculatedTotalSumm": null,
                    "Nds10_CalculatedTotalSumm": null,
                    "Total": 74204,
                    "DiscountMarkup": null,
                    "Extra": null,
                    "CalculationMethod": 4,
                    "SubjectType": 1,
                    "UnitOfMeasure": null,
                    "ProductNomenclature": null,
                    "NDS_PieceSumm": null,
                    "NDS_Rate": 1,
                    "NDS_Summ": 12367,
                    "AdditionalRequisite": null
                }
            ],
            "StornoItems": null,
            "RetailPlaceAddress": "string",
            "Buyer_Address": "string",
            "Sender_Address": "string",
            "PaymentAgent_Phone": "string",
            "MoneyOperator_Phone": "string",
            "BankAgent_Phone": "string",
            "BankAgent_Operation": "string",
            "BankAgent_Comission": null,
            "MoneyOperator_Name": "string",
            "MoneyOperator_Address": "string",
            "MoneyOperator_INN": "string",
            "Nds18_TotalSumm": 12367,
            "Nds10_TotalSumm": null,
            "Nds00_TotalSumm": null,
            "NdsNA_TotalSumm": null,
            "Nds18_CalculatedTotalSumm": null,
            "Nds10_CalculatedTotalSumm": null,
            "Amount_Total": 74204,
            "Amount_Cash": 0,
            "Amount_ECash": 74204,
            "Document_Number": 356,
            "FiscalSign": "string",
            "DecimalFiscalSign": "987654321",
            "ReceiptsCount": null,
            "DocumentsCount": null,
            "BadStateCount": null,
            "BadStateDateTime": null,
            "OFD_ResponseTimeout": null,
            "FiscalDrive_Exhaustion": null,
            "OfflineMode": null,
            "BadStateNumber": null,
            "StrictFormSign": null,
            "ServiceSectorSign": null,
            "EncryptionSign": null,
            "AutoMode": null,
            "KKT_MachineNumber": "1",
            "InternetSign": 1,
            "OfdInn": null,
            "KKT_FactoryNumber": null,
            "FiscalDrive_ReplaceRequired": null,
            "FiscalDrive_MemoryExceeded": null,
            "ReRegReasons": null,
            "CheckFP_Site": null,
            "PaymentSubAgent_Phone": "string",
            "PaymentOperator_Phone": "string",
            "PaymentAgent_Comission": null,
            "BankSubAgent_Phone": "string",
            "BankSubAgent_Operation": "string",
            "Messages": "string",
            "DiscountMarkup": null,
            "Extra": null,
            "Format_Version": 2,
            "Format_VersionKKT": null,
            "Format_VersionFN": null,
            "Correction_Type": null,
            "Correction": null,
            "Amount_Advance": 0,
            "Amount_Loan": 0,
            "Amount_Granting": 0,
            "Supplier_Phone": "string",
            "TaxAuthority_Site": "string",
            "AdditionalRequisite": "string",
            "ShiftTotals": null,
            "DeliveredTotals": null,
            "UndeliveredTotals": null,
            "Calculation_Place": null,
            "GamblingMode": null,
            "PaymentAgentMode": null,
            "LotteryMode": null,
            "Sign_KKT_Machine": null,
            "Sign_Excise": null,
            "Operator_INN": null,
            "RecipeSite": null,
            "ValidityPeriod": null
        },
        "Tag": 3,
        "UserInn": "string",
        "KktRegNumber": "0003016009004321",
        "FnNumber": "9286000100012345",
        "DocNumber": 356,
        "DocDateTime": "2019-04-08T10:46:00",
        "DocFiscalSign": "string",
        "DecimalFiscalSign": "987654321",
        "CDateUtc": "2019-04-08T07:46:26",
        "SchemeWarnings": null,
        "ValidationErrors": null
    },
    "AvailableRequests": 9978
}

Здесь:

  • Data - поя структуры приведены в таблице 2;
  • Success - успешность выполнения запроса, принимает значения:
    True – успешно выполнен запрос;
    False – не успешно выполнен запрос;
  • AvailableRequests - доступное количество запросов по токену до конца текущего месяца.

Таблица 2. Поля структуры Data ответа на запрос фискального документа ФНС

Идентификатор Вложенные поля Формат поля Назначение Тег
Version Целое число Версия сериализации документа
DocumentFormat Строка Версия формата фискальных данных
Document Структура Данные фискального документа
DocumentName Строка Название документа
Tag Целое число Численный признак вида документа:
3 – чек;
31 – чек коррекции;
4 – бланк строгой отчетности;
41 – бланк строгой отчетности коррекции.
User Строка Наименование пользователя
UserInn Строка ИНН пользователя (владельца, ответственного лица) 1018
Number Целое число Номер документа в смене
DateTime Дата и время в формате ISO 2) Дата и время последнего обновления информации о чеке 1012
ShiftNumber Целое число Номер смены (по данным кассы), в которую был сформирован документ 1038
OperationType Целое число Численный признак типа операции:
1 – Приход;
2 – Возврат прихода;
3 – Расход;
4 – Возврат расхода.
1054
TaxationType Целое число Тип налогообложения, принимает значения:
0 – общая система налогообложения;
1 – упрощенная система налогообложения (доход);
2 – упрощенная система налогообложения (доход минус расход);
3 – единый налог на вмененный доход;
4 – единый сельскохозяйственный налог;
5 – патентная система налогообложения.
1055
Operator Строка Фамилия, имя, отчество оператора 1021
KKT_RegNumber Строка Регистрационный номер кассы 1037
FN_FactoryNumber Строка Номер фискального накопителя, установленного в кассу (серийный, заводской) 1041
Items Структура Товарные позиции, перечисленные списком. Подробнее в таблице 2.1
StornoItems Строка Сторно товара
RetailPlaceAddress Строка Адрес расположения кассового аппарата
Buyer_Address Строка Абонентский номер и (или) адрес электронной почты покупателя (клиента) в случае передачи ему кассового чека (БСО) в электронной форме
Sender_Address Строка Адрес электронной почты отправителя чека 1117
PaymentAgent_Phone Строка Номер телефона платежного агента 1073
MoneyOperator_Phone Строка Номер телефона оператора по переводу денежных средств 1075
BankAgent_Phone Строка Номер телефона банковского платежного агента
BankAgent_Operation Целое число Операция банковского агента
BankAgent_Comission Целое число Размер комиссии банковского платежного агента
MoneyOperator_Name Строка Название оператора по переводу денежных средств
MoneyOperator_Address Строка Адрес оператора по переводу денежных средств
MoneyOperator_INN Строка ИНН оператора по переводу денежных средств
Nds18_TotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставку 18%, начисленная за смену (в копейках) 1102
Nds10_TotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставку 10%, начисленная за смену (в копейках) 1103
Nds00_TotalSumm Целое число Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену (в копейках) 1104
NdsNA_TotalSumm Целое число Сумма по операциям, не облагаемая НДС, накопленная за смену (в копейках) 1105
Nds18_CalculatedTotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 18/118, начисленная за смену, в копейках 1106
Nds10_CalculatedTotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110, начисленная за смену, в копейках 1107
Amount_Total Целое число Общая сумма по чеку (в копейках) 1020
Amount_Cash Целое число Сумма наличными по чеку (в копейках) 1031
Amount_ECash Целое число Сумма электронного платежа по чеку (в копейках) 1081
Document_Number Целое число Фискальный номер документа 1040
FiscalSign Строка Фискальный признак документа 1077
DecimalFiscalSign Строка Фискальный признак документа
ReceiptsCount Целое число Количество кассовых чеков за смену 1118
DocumentsCount Целое число Количество фискальных документов за смену 1111
BadStateCount Целое число Количество ФД, не переданных ОФД (по которым не было получено подтверждения оператора) 1097
BadStateDateTime Дата и время в формате ISO 3) Дата первого ФД из числа не переданных ОФД 1098
OFD_ResponseTimeout Строка Подтверждение оператора для переданного фискального документа отсутствует более двух дней 1053
FiscalDrive_Exhaustion Строка До истечения срока действия ключей фискального признака в фискальном накопителе осталось менее 30 дней 1050
OfflineMode Строка Применения ККТ в режиме, не предусматривающем обязательной передачи ФД в налоговые органы в электронной форме через ОФД
BadStateNumber Целое число Номер первого ФД из числа не переданных ОФД 1116
StrictFormSign Строка Признак ККТ, являющейся автоматизированной системой для БСО (может формировать только БСО и применяться для осуществления расчетов только при оказании услуг) 1110
ServiceSectorSign Строка Признак работы в сфере услуг 1109
EncryptionSign Строка Признак передачи фискальных документов в зашифрованном виде оператору фискальных данных 1056
AutoMode Строка Признак применения ККТ в составе автоматического устройства для расчетов
KKT_MachineNumber Строка Заводской номер автоматического устройства для расчетов 1036
InternetSign Целое число Осуществления расчетов только в сети «Интернет», в которой отсутствует устройство для печати фискальных документов в составе ККТ 1108
OfdInn Строка ИНН оператора фискальных данных
KKT_FactoryNumber Строка Заводской номер KKT 1013
FiscalDrive_ReplaceRequired Строка Признак того, что до истечения срока действия ключей фискального признака в фискальном накопителе осталось менее 3 дней 1051
FiscalDrive_MemoryExceeded Строка Признак того, что память фискального накопителя заполнена более чем на 99% 1052
ReRegReasons Целое число Причина изменения сведений о ККТ 1101
CheckFP_Site Строка Адрес сайта для проверки ФП
PaymentSubAgent_Phone Строка Номер телефона платежного субагента 1083
PaymentOperator_Phone Строка Номер телефона оператора по приему платежей
PaymentAgent_Comission Целое число Размер комиссии платежного агента
BankSubAgent_Phone Строка Номер телефона банковского платежного субагента 1082
BankSubAgent_Operation Строка Операция банковского платежного субагента 1045
Messages Строка Текст сообщения
DiscountMarkup Целое число Скидка/наценка
Extra Строка Дополнительные реквизиты пользователя
Format_Version Целое число Номер версии формата фискальных документов 1209
Format_VersionKKT Целое число Версия форматов фискальных документов, реализованная в ККТ 1189
Format_VersionFN Целое число Версия форматов фискальных документов, реализованная в ФН 1190
Correction_Type Целое число Тип коррекции:
Самостоятельно – 0;
По предписанию – 1.
1173
Correction Строка Основание для коррекции 1174
Amount_Advance Целое число Сумма предоплаты 1215
Amount_Loan Целое число Сумма постоплаты 1216
Amount_Granting Целое число Сумма встречным предоставлением 1217
Supplier_Phone Строка Номер телефон поставщика 1171
TaxAuthority_Site Строка Сайт налогового органа 1060
AdditionalRequisite Строка Дополнительные реквизиты
ShiftTotals Целое число Итоговая суммы расчетов, указанная в чеке 1194
DeliveredTotals Строка Итоговые количества и итоговые суммы расчетов фискальных данных 1157
UndeliveredTotals Строка Итоговые количества и итоговые суммы расчетов непереданных фискальных данных 1158
Calculation_Place Строка Место осуществления расчетов между пользователем и покупателем (клиентом) 1187
GamblingMode Целое число Признак проведения азартных игр 1193
PaymentAgentMode Целое число Проведение расчётов платежным агентом 1057
LotteryMode Целое число Признак проведения лотереи 1126
Sign_KKT_Machine Целое число Признак ККТ, предназначенной для применения только в составе автоматического устройства для расчетов 1221
Sign_Excise Целое число Продажа подакцизного товара 1207
Operator_INN Строка ИНН кассира 1203
RecipeSite Строка Адрес сайта, на котором покупатель может бесплатно получить чек 1208
ValidityPeriod Дата и время в формате ISO 4) Срок действия ключей фискального признака (величина учитывается в днях до момента истечения срока действия ключей) 1213
Tag Целое число Численный признак вида документа:
3 – чек;
31 – чек коррекции;
4 – бланк строгой отчетности;
41 – бланк строгой отчетности коррекции.
UserInn Строка ИНН пользователя (владельца, ответственного лица) 1018
KktRegNumber Строка Регистрационный номер кассы 1037
FnNumber Строка Номер фискального накопителя, установленного в кассу (серийный, заводской) 1041
DocNumber Целое число Фискальный номер документа 1040
DocDateTime Дата и время в формате ISO 5) Дата и время формирования документа по данным кассы
DocFiscalSign Строка Фискальный признак документа 1077
CDateUtc Дата и время в формате ISO 6) Дата и время приема документа в информационную систему
SchemeWarnings Целое число Схема предупреждения документа принимает значения:
0 – нет нарушения;
1 – предупреждение о максимальной длине документа;
2 – предупреждение о минимальной длине документа;
3 – предупреждение о фиксированной длине документа.
ValidationErrors Строка Ошибки валидации документа

Таблица 2.1 Поля структуры Items ответа на запрос фискального документа ФНС

Идентификатор Формат поля Назначение Тег
Name Строка Название позиции
Price Целое число Цена позиции (в копейках)
Quantity Целое число Количество единиц товарной позиции
Nds18_TotalSumm Целое число Сумма НДС по предмету расчета со ставкой 20% в копейках 7) 1102
Nds10_TotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставку 10%, начисленная за смену (в копейках) 1103
Nds00_TotalSumm Целое число Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену (в копейках) 1104
NdsNA_TotalSumm Целое число Сумма по операциям, не облагаемая НДС, накопленная за смену (в копейках) 1105
Nds18_CalculatedTotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 20/120 8), начисленная за смену, в копейках 1106
Nds10_CalculatedTotalSumm Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110, начисленная за смену, в копейках 1107
Total Целое число Стоимость по позиции (в копейках)
DiscountMarkup Целое число Cкидка/наценка 1112
Extra Строка Дополнительные реквизиты пользователя
CalculationMethod Целое число Признак способа расчета 1214
SubjectType Целое число Признак предмета расчета 1212
UnitOfMeasure Строка Единица измерения предмета расчета 1197
ProductNomenclature Строка Код товарной номенклатуры 1162
NDS_PieceSumm Целое число Размер НДС за единицу предмета расчета 1198
NDS_Rate Целое число Ставка НДС принимает значения:
1 - НДС 20% 9);
2 - НДС 10%;
3 - 20/120 10);
4 - НДС 10/110;
5 - НДС 0%;
6 - НДС не облагается.
1199
NDS_Summ Целое число Сумма НДС за предмет расчета 1200
AdditionalRequisite Строка Дополнительные реквизиты

1.2. Возможные ошибки

В ответ об ошибке имеет общий вид и формат JSON. В случае, если ответ содержит несколько ошибок, они будут перечислены в массиве друг за другом через запятую. Общий вид ошибки приведен ниже, поля описаны в таблице 3:

{
    "Success": false,
    "Errors": [
        {
            "Code": "",
            "Field": "",
            "Message": ""
        }
    ],
    "AvailableRequests": 9978
}

Таблица 3. Поля данных неуспешно выполненного запроса фискального документа ФНС

Идентификатор Вложенные поля Формат поля Назначение
Success Логическое значение Успешность выполнения запроса, принимает значения:
True – успешно выполнен запрос;
False – не успешно выполнен запрос.
Errors Структура Информация об ошибке или ошибках
Code Строка Внутренний код ошибки. Перечень возможных ошибок приведен в таблице 4
Field Строка Параметр, в котором допущена ошибка
Message Строка Информация об ошибке.
AvailableRequests Целое число Доступное количество запросов по токену до конца текущего месяца

Таблица 4. Список возможных ошибок в ответах.

Код ошибки Значение
Unable to find token не указан, указан неверно или истек срок у параметра tokenSecret
Invalid token превышено количество раз, которое может быть использован токен в параметре tokenSecret
InclusiveBetweenValidator не указан обязательный параметр DocNumber или DocFiscalSign либо значение параметров DocNumber, DocFiscalSign, ReceiptOperationType превышает допустимое
NotEqualValidator не указан обязательный параметр ReceiptOperationType
InternalError информация о типе ошибке содержится в поле Message. Возможные варианты:
- ошибка со стороны ФНС;
- ФНС недоступна;
- не указан или указан неверно обязательный параметр DocDateTime или TotalSum
NotNullValidator не указан обязательный параметр FnNumber
RegularExpressionValidator указано недопустимое значение параметра FnNumber
DataNotFound чек отсутствует в базе ФНС
InvalidDataInput неверные данные на вход
Invalid attempts count exceed. Next attempt at 2020-09-15T17:12:21.4810000 превышен лимит неудачных попыток получения чека в течение 24 часов (максимальное число неудачных запросов по одному чеку - 4). Указывается время, когда можно будет повторно запросить чек
452 Запрос не соответствует формату hsm
454 Обращение к hsm было выполнено и получен отрицательный результат проверки
455 Не найдены данные в сервисе поиска чека
456 Ошибка hsm. Чек не валиден или любая внутренняя ошибка hsm
503 Service unavailable (сервис недоступен)
528 Фискальный признак не может быть проверен, поскольку в hsm отсутствует необходимый ключ
532 Внутренняя ошибка сервиса получения чеков
544 Не прошла проверка пара ККТ+ФН
545 ККТ в автономном режиме
546 Ошибка ФЛК
546 Ошибка ФЛК

История изменений

Версия 1.0
Выпущена 04 декабря 2018 г.
Первая отслеживаемая версия документа.

Версия 1.1
Выпущена 09 апреля 2019 г.

  • Изменен вид POST запроса (с Document/FetchReceiptFromFns на api/partner/v3/receipts/GetReceipt);
  • В запрос и таблицу 1 добавлен параметр tokenSecret;
  • Актуализирован успешный ответ и таблица 2 с полями ответа на получаемый запрос;
  • Добавлены возможные ошибки в случае неуспешного запроса.

Версия 1.2
Выпущена 23 сентября 2020 г.

  • Добавлено поле AvailableRequests;
  • Добавлена информация по ошибке «Invalid attempts count exceed»;
  • В таблицу 2 добавлены теги 1102, 1106.

Версия 1.3
Выпущена 12 октября 2020 г.
Добавлена таблица с кодами ошибок.

Версия 1.4
Выпущена 27 октября 2020 г.
Переработаны таблицы для большей наглядности информации о вложенных полях в структурах.

Версия 1.5
Выпущена 29 октября 2020 г.

  • Добавлены коды ошибок: DataNotFound, InvalidDataInput;
  • Добавлена расшифровка кода ошибки InternalError.

Версия 1.6
Выпущена 11 января 2021 г.

  • Поправлено в ответе местоположение «Success»: true,
1) , 2) , 3) , 4) , 5) , 6)
Данный формат описан в стандарте ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.
7)
до 01.01.2019 сумма НДС предмета расчета рассчитывалась со ставкой 18%
8)
до 01.01.2019 сумма удерживаемого НДС рассчитывалась по ставке 18/118
9)
до 01.01.2019 18%
10)
до 01.01.2019 18/118