Инструменты страницы

Запрос сведений о кассовом чеке (getReceiptStatus.do)

Для получения сведений о чеках по заказу используется запрос getReceiptStatus.do. В запросе могут передаваться следующие данные:

  • идентификатор заказа - orderId или orderNumber;
  • идентификатор чека - uuid.

Если передан идентификатор заказа (orderId или orderNumber), ответ возвращает все чеки данного заказа. При передаче только идентификатора чека ответ возвращает сведения только о данном чеке. Если указаны и идентификатор заказа, и чека, ответ возвращает все чеки заказа.

В настоящем документе при описании параметров запросов и ответов используются следующие обозначения типов данных:

  • A<n> – последовательность латинских букв длины <n>;
  • A..<n> – последовательность латинских букв длиной, не превышающей <n>;
  • N<n> – последовательность цифр длины <n>;
  • N..<n> – последовательность цифр длиной, не превышающей <n>;
  • AN<n> – последовательность латинских букв и цифр фиксированной длины <n>;
  • AN..<n> – последовательность латинских букв и цифр длиной, не превышающей <n>;
  • ANS<n> – последовательность латинских букв, цифр и символов фиксированной длины <n>
  • ANS..<n> – последовательность латинских букв, цифр и символов длиной, не превышающей <n>;
  • UTC – дата и время, при этом: дата должна быть передана без указания часового пояса, время московское, для протокола SOAP используется стандартная кодировка xs:dateTime.

Пользуясь протоколом REST, тело сообщения запроса следует отправлять с типом: 'Content-Type: application/x-www-form-urlencoded'.

Параметры запроса

Название Тип Обязательно Описание Версия ФФД

userName

AN..30

Да

Логин служебной учётной записи продавца.

Все версии.

password

AN..200

Да

Пароль служебной учётной записи продавца.

Все версии.

orderId

ANS36

Нет

Номер заказа в платёжной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа не удалась по причине ошибки.

Для выполнения запроса должен быть указан либо номер заказа, либо идентификатор в фискализаторе.

Все версии.

orderNumber

ANS..32

Нет

Номер (идентификатор) заказа в системе магазина.

Для выполнения запроса должен быть указан либо номер заказа, либо идентификатор в фискализаторе.

Все версии.

uuid

AN..32

Нет

Идентификатор чека в фискализаторе.

Для выполнения запроса должен быть указан либо номер заказа, либо идентификатор в фискализаторе.

Все версии.

language

A2

Нет

Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию.

Все версии.

Параметры ответа

Некоторые возвращаемые параметры могут зависеть от используемого оператора фискальных данных.



Название Тип Обязательно Описание Версия ФФД

errorCode

N..2

Нет

Код ошибки. Может отсутствовать, если результат не привёл к ошибке.

Все версии.

errorMessage

AN..512

Нет

Описание ошибки на языке, переданном в параметре language в запросе.

Все версии.

orderNumber

ANS..32

Нет

Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр передавать необязательно

Все версии.

orderId

ANS36

Нет

Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует если регистрация заказа не удалась по причине ошибки, детализированной в ErrorCode.

Все версии.

receipt

Не актуально

Нет

Блок с параметрами чека.

Все версии.

Содержимое блока receipt

Содержимое блока receipt представлено в таблице ниже.

Название Тип Обязательно Описание Версия ФФД

receiptStatus

N2

Да

По значению этого параметра определяется состояние чека. Поле может принимать следующие значения:

  • 0 - отправлен платёж;
  • 1 - доставлен платёж;
  • 2 - ошибка платежа;
  • 3 - отправлен возврат;
  • 4 - доставлен возврат;
  • 5 - ошибка возврата;
  • 6 - чек коррекции отправлен;
  • 7 - чек коррекции доставлен;
  • 8 - ошибка отправки чека коррекции.

Все версии.

uuid

AN..32

Нет

Идентификатор чека в фискализаторе.

Все версии.

original_ofd_uuid

ANS..255

Нет

Идентификатор чека в ОФД системе.

1.05 и более поздние версии.

shift_number

N

Нет

Номер смены.

Все версии.

fiscal_receipt_number

N

Нет

Номер чека в смене.

Все версии.

receipt_date_time

NS

Нет

Дата и время чека в фискальном накопителе.

Все версии.

fn_number

S..16

Нет

Номер фискального накопителя.

Все версии.

fiscal_document_number

N

Нет

Фискальный номер документа.

Все версии.

fiscal_document_attribute

S..10

Нет

Фискальный признак документа.

Все версии.

amount_total

NS..11

Нет

Итоговая сумма чека в копейках.

Все версии.

serial_number

S..20

Нет

Заводской номер контрольно-кассовой техники.

Все версии.

fnsSite

ANS

Нет

Адрес сайта ФНС.

1.05 и более поздние версии.

ofd_receipt_url

ANS..1024

Нет

Ссылка на чек.

Не все ОФД системы возвращают ссылку на чек, поэтому поле может быть пустым.

1.05 и более поздние версии.

OFD

Не актуально

Нет

Блок с параметрами оператора фискальных данных.

Все версии.

ofd_order_bundle См. описание Нет

Корзина, переданная в ОФД. Описание атрибутов представлено ниже.

В настоящее время реализовано исключительно для АТОЛ систем версии v5 (1.2).

Настоящая корзина отображается только при передаче бонусных баллов «Спасибо» при регистрации заказа.

Содержимое блока ofd_order_bundle

Содержимое блока ofd_order_bundle представлено в таблице ниже.

Название Тип Обязательно Описание Версия ФФД

name

ANS..100

Да

Наименование или описание товарной позиции в свободной форме.

1.2 и более поздние версии.

amount

N..18

Да

Сумма стоимости всех товарных позиций одного positionId в деньгах в минимальных единицах валюты.

1.2 и более поздние версии.

price

N..18

Да

Стоимость одной товарной позиции в минимальных единицах валюты.

1.2 и более поздние версии.

quantity

N..18

Да

Количество товарных позиций данного positionId. Для указания дробных чисел используйте десятичную точку.

1.2 и более поздние версии.

itemAttributes

Тэг, предназначенный для передачи набора атрибутов товарной позиции. Атрибуты следует указывать следующим образом.

"itemAttributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]

1.2 и более поздние версии.

itemAttributes[paymentMethod]

N..2

Да

Тип оплаты возможны следующие значения:

  • 1 - полная предварительная оплата до момента передачи предмета расчёта;
  • 2 - частичная предварительная оплата до момента передачи предмета расчёта;
  • 3 - аванс;
  • 4 - полная оплата в момент передачи предмета расчёта;
  • 5 - частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит;
  • 6 - передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит;
  • 7 - оплата предмета расчёта после его передачи с оплатой в кредит.

Приоритизация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета):

  1. Корзина заказа из API-запроса.
  2. Настройки фискализации в личном кабинете.
  3. Значения по умолчанию.

Для paymentMethod значением по умолчанию является 1 (полная предварительная оплата до момента передачи предмета расчета).

1.2 и более поздние версии.

itemAttributes[paymentObject]

N..2

Да

Тип оплачиваемой позиции, возможны следующие значения:

  • 1 - товар;
  • 2 - подакцизный товар;
  • 3 - работа;
  • 4 - услуга;
  • 5 - ставка азартной игры;
  • 6 - выигрыш азартной игры;
  • 7 - лотерейный билет;
  • 8 - выигрыш лотереи;
  • 9 - предоставление РИД;
  • 10 - платёж;
  • 11 - агентское вознаграждение;
  • 12 - составной предмет расчёта;
  • 13 - иной предмет расчёта;
  • 14 - имущественное право;
  • 15 - внереализационный доход;
  • 16 - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации;
  • 17 - торговый сбор: о суммах уплаченного торгового сбора;
  • 18 - курортный сбор;

Указанные выше значения доступны для ФФД 1.05.

Для ФФД 1.2 список доступных значений пополняется также следующими значениями:

  • 30 - реализуемый подакцизный товар, подлежащий маркировке средством идентификации, не имеющем кода маркировки;
  • 31 - реализуемый подакцизный товар, подлежащий маркировке средством идентификации, имеющем кода маркировки;
  • 32 - реализуемый товар, подлежащий маркировке средством идентификации, не имеющим код маркировки, за исключением подакцизного товара;
  • 33 - реализуемый товар, подлежащий маркировке средством идентификации, имеющим код маркировки, за исключением подакцизного товара.

Приоритизация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета):

  1. Корзина заказа из API-запроса.
  2. Настройки фискализации в личном кабинете.
  3. Значения по умолчанию.

Для paymentObject значением по умолчанию является 1 (товар).

1.2 и более поздние версии.

taxType

N..2

Да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 6 – НДС чека по ставке 20%;
  • 7 – НДС чека по расчётной ставке 20/120;
  • 10 – НДС чека по ставке 5%;
  • 11 – НДС чека по расчетной ставке 5/105;
  • 12 – НДС чека по ставке 7%;
  • 13 – НДС чека по расчетной ставке 7/107.

Если в запросе не передаётся корзина с данными фискализации, оператору фискальных данных передаются значения по умолчанию, указанные в настройках личного кабинета (подробнее см. инструкцию по работе с личным кабинетом).

1.2 и более поздние версии.

Содержимое блока OFD

Содержимое блока OFD представлено в таблице ниже.

Название Тип Обязательно Описание Версия ФФД

name

S..256

Нет

Наименование оператора фискальных данных.

Все версии.

website

S..58

Нет

Сайт оператора фискальных данных.

Все версии.

INN

S12

Нет

Идентификационный номер налогоплательщика оператора фискальных данных.

Все версии.

Коды ошибок

В таблице ниже представлены коды ошибок с сообщениями.

Код ошибки Текст ошибки
1

Необходим хотя бы один из параметров: orderId, orderNumber, uuid.

5

Доступ запрещён.

6

Чек не найден.

7

Системная ошибка.

Примеры

Пример запроса

language=ru&userName=login-api&password=123&uuid=574590d8-f004-41a6-9be6-45678b1626ff

Пример ответа


{
    "errorCode": "0",
    "orderNumber":"232002",
    "orderId":"5b6ddd02-0974-77f3-bfbd-33be011b4f5b",
   "receipt": [
        {
            "receiptStatus": 4,
            "uuid": "574590d8-f004-41a6-9be6-45678b1626ff",
             "original_ofd_uuid":"27c5a617-62a4-4f77-943e53512c38f3e2",
            "shift_number": "22",
            "fiscal_receipt_number": "6543",
            "receipt_date_time": 1608215760000,
            "fn_number": "9999078900001823",
            "ecr_registration_number": "0000000005039739",
            "fiscal_document_number": "36178",
            "fiscal_document_attribute": "4068500213",
            "amount_total": "141",
            "fnsSite":"www.nalog.ru",
            "ofd_receipt_url":"https://lk.platformaofd.ru/web/noauth/cheque?fn=9999078900001823&fp=4068500213&i=36178"
          }
      ]
}

Пример ответа с блоком ofd_order_bundle

{
    "errorCode": "0",
    "orderNumber": "220170606034051002_177",
    "orderId": "abd60d0c-e096-42c3-8b17-6081c67db214",
    "receipt": [
        {
            "receiptStatus": 1,
            "uuid": "790925e5-739c-430c-9e92-79d9f14481a4",
            "shift_number": "27",
            "fiscal_receipt_number": "21",
            "receipt_date_time": 1499256900000,
            "fn_number": "9999078900006364",
            "ecr_registration_number": "1234567890023481",
            "fiscal_document_number": "21",
            "fiscal_document_attribute": "3713381819",
            "amount_total": 10000
            "ofdOrderBundle": [
                {
                    "taxType": "VAT_0",
                    "name": "water",
                    "itemAmount": 111165,
                    "itemPrice": 7411,
                    "quantity": {
                        "value" : "15",
                        "measure": "0"
                    },
                    "itemAttributes": [
                        {
                           "name": "paymentMethod",
                           "value": "1"
                        },
                        {
                            "name": "paymentObject",
                            "value": "1"
                        }
                    ]
                },
                {
                    "taxType": "VAT_0",
                    "name": "chocolate",
                    "itemAmount": 22191,
                    "itemPrice": 7397,            
                    "quantity": {
                        "value" : "15",
                        "measure": "0"
                    }        
                },
                {
                    "taxType": "VAT_0",
                    "name": "potato",
                    "itemAmount": 18005,
                    "itemPrice": 8259,            
                    "quantity": {
                        "value" : "15",
                        "measure": "0"
                    }        
                },
                {
                    "taxType": "VAT_0",
                    "name": "water",
                    "itemAmount": 333540,
                    "itemPrice": 7412,            
                    "quantity": {
                        "value" : "15",
                        "measure": "0"
                    },            
                    "itemAttributes": [
                        {
                            "name": "paymentMethod",
                            "value": "1"
                        },
                        {
                            "name": "paymentObject",
                            "value": "1"
                        }
                    ]
                }
            ]
        } 
    ]
}