Запрос передачи данных чека (externalReceipt.do)

Для передачи данных чека используется запрос externalReceipt.do (cм. координаты подключения). Этот запрос необходимо запускать после оплаты с помощью электронного сертификата или возврата средств электронного сертификата, если используется фискализация на стороне мерчанта. В дальнейшем данные чека передаются в НСПК для подтверждения оплаты или возврата.

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

  • 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/json'.

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

Параметры запроса представлены в таблице ниже.

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

language

A2

Нет

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

userName

AN..30

Да

Логин служебной учётной записи продавца. При передаче логина и пароля для аутентификации в платёжном шлюзе параметр token передавать не нужно.

password

AN..30

Да

Пароль служебной учётной записи продавца. При передаче логина и пароля для аутентификации в платёжном шлюзе параметр token передавать не нужно.

mdOrder

ANS..36

Да

Номер заказа в платёжном шлюзе. Уникален в пределах платёжного шлюза.

receipt

Не актуально

Да

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

(Перейти к описанию.)

jsonParams

Строка

Нет

Дополнительные параметры запроса. Формат вида: {«Имя1»: «Значение1», «Имя2»: «Значение2»}. При указании «showLoyalty»:«false» взаимодействие с сервисом лояльности осуществляться не будет.

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

Название Тип Описание
cashboxId N18 Идентификатор кассы
basketId N24 Идентификатор корзины покупки или возврата.

receipt

Блок receipt состоит из следующих элементов.

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

type

N1

Нет

Признак способа оплаты. Возможные значения:

  • 0 - чек прихода/коррекции прихода;
  • 1 - чек возврата/коррекции возврата.

Значение по умолчанию - 0.

paymentType

N1

Да

Признак способа оплаты. Возможные значения:

  • 1 - оплата;
  • 3 - возврат.

fn_number

S..16

Нет

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

fiscal_document_number

N

Нет

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

fiscal_document_attribute

S..10

Нет

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

amount_total

NS..18

Нет

Итоговая сумма чека в формате числа с разделителем. Целая часть не больше 15 символов, дробная часть не больше 2 символов.

receipt_date_time

yyyy:MM:dd HH:mm:ss

Нет

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

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

Параметры ответа представлены в таблице ниже.

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

errorCode

N..2

Нет

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

errorMessage

AN..512

Нет

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

Коды ошибок

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

Обработка запроса прошла без системных ошибок.

1

Заказ с таким номером не зарегистрирован в системе

4

Отсутствует обязательный параметр запроса

5

Неверно указано значение одного из параметров.

7

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

Примеры

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

{
  "language" : "RU",
  "mdOrder" : "fdbd09f9-11c7-4167-8eff-ab9bd8e3d619",
  "userName" : "username",
  "password" : "password",
  "receipt" : {
    "type" : 1,
    "fn_number" : "fn",
    "fiscal_document_number" : "fdn",
    "fiscal_document_attribute" : "fda",
    "amount_total" : "1",
    "receipt_date_time" : "2022:09:16 17:40:46"
  },
  "jsonParams" : {
    "cashboxId" : "900000000000000004",
    "basketId" : "4446763"
  }
}

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

{
  "errorCode" : 0,
  "errorMessage" : "OK"
}