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

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

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

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. Поля данных запроса фискального документа ФНС

Ответ на данный запрос также содержит структуру данных в формате 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": "string",
            "FN_FactoryNumber": "string",
            "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,
        "RegAddresss": "string",
        "FiasId": "string",
        "GeoPoint": {
            "Latitude": Integer,
            "Longitude": Integer
        }
    },
    "AvailableRequests": 9978
}

Здесь:

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

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

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

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

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

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

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

Версия 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.7
Выпущена 4 октября 2022 г.

• Добавлены новые параметры в ответе метода api/partner/v3/receipts/GetReceipt:
  • RegAddresss
  • FiasId
  • GeoPoint:
    • Latitude
    • Longitude

Версия 1.8
Выпущена 15 февраля 2024 г.

• Добавлено подробное описание возможных значений параметра CalculationMethod в ответе метода api/partner/v3/receipts/GetReceipt: