Интернет-эквайринг с комиссией от 1%

Принимайте платежи на сайте, в онлайн-магазине
или в соцсетях — по картам и через СБП

Главное изображение комиссия 1%

8. Работа с чеками 54-ФЗ

PayKeeper поддерживает автоматическую генерацию чеков согласно 54-ФЗ.

  URI Назначение
8.1 /info/receipts/bydate/ Получение реестра чеков за период, с фильтром по типам.
8.2 /info/receipts/bydatecount/ Получение количеств чеков за период, сгруппированных по типам
8.3 /info/receipts/bypaymentid/ Получение информации о чеках, выданных по указанному платежу
8.4 /info/receipts/byid/ Получение информации о чеке по его внутреннему номеру
8.5 /info/receipts/search/ Поиск чеков по фискальным атрибутам
8.6 ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО
8.7 ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО
8.8 ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО
8.9 ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО
8.10 ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО
8.11 /change/receipt/print/ Сгенерировать чек по платежу или с произвольными атрибутами
8.12 ЗАРЕЗЕРВИРОВАНО Отправить запрос о состоянии чеков кассовому устройству. Если у чека нет фискальных атрибутов, этот запрос может их получить.
8.13 Callback о статусе чека Уведомление системы ТСП о достижении чеком финального статуса 

 

8.1. Получение реестра чеков за период, с фильтром по типам.

Результатом будет список выданных произвольных чеков.

Тип Формат запроса
GET /info/receipts/bydate/?start=2021-01-28&end=2021-02-28&sum_type[0]=sum_cashless&sum_type[1]=sum_cash&status[0]=created&status[1]=success
  Параметр Назначение
1. start Не обязательный. Дата начала периода в формате YYYY-MM-DD.
2. end Не обязательный. Дата конца периода в формате YYYY-MM-DD.
3. status Не обязательный. Массив значений. Фильтровать по статусу (created, request_sent, success, failed, timeout).
4. receipt_type Обязательный. Массив значений. Фильтровать по типу чека (sale, refund, correction).
5. sum_type Обязательный. Массив значений. Включить в выборку чеки, с указанным способом оплаты (sum_cashless, sum_cash, sum_advance, sum_credit).
6. sort Не обязательный. По умолчанию request_datetime. Сортировка по полю (payment_id, refund_id, request_datetime, obtain_datetime, status). 
7. direction Не обязательный. По умолчанию DESC. Направление сортировки (ASC, DESC).
8. from Не обязательный. По умолчанию 0. Начало выборки.
9. limit Не обязательный. По умолчанию 10. Количество возвращаемых строк.
Таблица 8.1.1. Параметры запроса

Если чеки будут найдены, то в ответ вернутся массивы объектов. {«receipts»:[…],»counts»:{…}}

Описание одного объекта массива receipts:

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор чека
2. payment_id Номер платежа, по которому был сгенерирован чек. Может быть пустым, если чек генерировался не по платежу
3. type Тип чека, sale, refund.
4. is_post_sale Был ли данный чек сгенерирован как чек окончательного расчёта
5. refund_id Порядковый номер возврата в рамках указанного платежа, если чек был сгенерирован по определённому возврату.
6. status Статус чека. Может быть created, request_sent, success, timeout, failed.
7. contact Почта или телефон плательщика
8. sum_cashless Сумма, оплаченная безналичными
9. sum_cash Сумма, оплаченная наличными
10. sum_advance Сумма ранее проведённых предоплат или внесённых авансов
11. sum_credit Сумма выданного кредита
12. cart Корзина товаров, таблица 12.1. Строка, кодирующая массив объектов в JSON-формате.
13. receipt_properties Дополнительные свойства чека, таблица 12.5. Строка, кодирующая объект в JSON-формате.
14. fpd Фискальная подпись документа
15. fnd Фискальный номер документа
16. fn Номер фискального накопителя
17. ts Момент времени формирования чека, строка в формате YYYYMMDDTHHmm
18. rnkkt Регистрационный номер ККТ
19. shift_number Номер смены
20. receipt_number Номер чека в смене
21. obtain_datetime Дата/Время проведения платежа
22. request_datetime Дата/Время информирования магазина о проведённом платеже
23. fop_receipt_key Ключ чека. Часть адреса постоянной страницы чека
24. fop_uuid Уникальный идентификатор запроса к кассовому устройству
25. fop_url Строка содержимого QR-кода чека
Таблица 8.1.2 Параметры ответа на запрос (массив receipts)

Описание объекта counts:

Тип Формат ответа
  Параметр Назначение
1. status Количество найденных чеков по статусу печати. Пример: status.request_sent:4
2. receipt_type Количество найденных чеков по типу чека. Пример: receipt_type.sale:4
3. sum_type Количество найденных чеков по способу оплаты. Пример: sum_type.sum_cashless:4
4. page_size Общее количество найденных чеков на страницу
5. totals.sum_type Количество чеков, сгруппированных по способу оплаты
6. totals.status Количество чеков, сгруппированных по статусу печати
7. totals.receipt_type Количество чеков, сгруппированных по типу чека
8. totals.total Всего чеков для запроса без учёта количество показа на страницу
Таблица 8.1.3 Параметры ответа на запрос (массив counts)

Пример ответа на запрос:

 

8.2. Получение количеств чеков за период, сгруппированных по типам. 

Тип Формат запроса
GET /info/receipts/bydatecount/?start=2020-10-18&end=2021-10-18
  Параметр Назначение
1. start Дата начала периода в формате YYYY-MM-DD.
2. end Дата конца периода в формате YYYY-MM-DD.
Таблица 8.2.1. Параметры запроса

Описание возвращаемого объекта:

Тип Формат ответа
  Параметр Назначение
1. status Количество найденных чеков по статусу печати. Пример: status.created:4
2. receipt_type Количество найденных чеков по типу чека. Пример: receipt_type.sale:4
3. sum_type Количество найденных чеков по способу оплаты. Пример: sum_type.sum_cashless:4
8. total Всего чеков для запроса
Таблица 8.1.3 Параметры ответа на запрос

Пример ответа на запрос:

8.3. Получение чеков по платежу /info/receipts/bypaymentid/

Запрос покажет чеки окончательного расчёта и произвольные чеки, сгенерированные по данному платежу. В настоящее время запрос не покажет самый первый чек, выданный при получении платежа.

Тип Формат запроса
GET /info/receipts/bypaymentid/?payment_id=2211
  Параметр Назначение
1. payment_id Идентификатор платежа, по которому необходимо получить данные
Таблица 8.3.1. Параметры запроса

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

 

8.4. Получение чека по его идентификатору /info/receipts/byid/

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

Тип Формат запроса
GET /info/receipts/byid/?id=4201
  Параметр Назначение
1. id Идентификатор чека
Таблица 8.4.1. Параметры запроса

Если чек с таким номером не будет найден, ответ будет пустым. Если чек будет найден, то в ответ вернётся объект следующего вида:

Тип Формат ответа
  Параметр Назначение
1. id Идентификатор чека
2. payment_id Номер платежа, по которому был сгенерирован чек. Может быть пустым, если чек генерировался не по платежу
3. type Тип чека: sale, refund, expense, expense-refund 
4. is_post_sale Был ли данный чек сгенерирован как чек окончательного расчёта, строка "0" или "1" 
5. is_correction Является ли чек чеком коррекции по ФФД 1.2, строка "0" или "1"
6. refund_id Порядковый номер возврата в рамках указанного платежа, если чек был сгенерирован по определённому возврату.
7. status Статус чека. Может быть created, sending, rejected, request_sent, success, timeout, failed .
8. contact Почта или телефон плательщика
9. sum_cashless Сумма, оплаченная безналичными
10. sum_cash Сумма, оплаченная наличными
11. sum_advance Сумма ранее проведённых предоплат или внесённых авансов
12. sum_credit Сумма выданного кредита
13. sum_counter_payment Сумма встречным предоставлением
14. cart Корзина товаров, таблица 12.1. Строка, кодирующая массив объектов в JSON-формате.
15. receipt_properties Дополнительные свойства чека, таблица 12.5. Строка, кодирующая объект в JSON-формате.
16. fpd Фискальная подпись документа
17. fnd Фискальный номер документа
18. fn Номер фискального накопителя
19. ts Момент времени формирования чека, строка в формате YYYYMMDDTHHmm
20. rnkkt Регистрационный номер ККТ
21. shift_number Номер смены
22. receipt_number Номер чека в смене
23. obtain_datetime Дата/Время проведения платежа
24. request_datetime Дата/Время информирования магазина о проведённом платеже
25. fop_receipt_key Ключ чека. Часть адреса постоянной страницы чека
26. fop_uuid Уникальный идентификатор запроса к кассовому устройству
27. fop_url Строка содержимого QR-кода чека
28. custom_params JSON-строка с дополнительными атрибутами чека. Используется для чеков коррекции ФФД 1.2
29. error JSON-строка, содержащая описание ошибки, если чек не был напечатан.  
Таблица 8.4.2 Параметры ответа на запрос

Пример ответа на запрос:

В поле 7 вернётся один из статусов чека. Если чек находится в финальном статусе, его дальнейшее изменение невозможно. При достижении чеком финального статуса в адрес информационной системы ТСП будет направлено callback-уведомление о печати чека. Возможны следующие статусы чеков:

Статус Описание статуса Финальный
created Запрос на печать чека принят, ожидается отправка в сервис-балансировщик. нет
sending Запрос отправляется в сервис-балансировщик. нет
rejected  Сервис-балансировщик отказал в принятии чека, повторение чека без изменения чека или настроек подключения бесполезно. Детали ошибки могут быть приведены в поле ошибки 29. да
request_sent Запрос принят сервисом-балансировщиком и будет передан в устройство ККТ. нет
success Чек сформирован. да
timeout Чек находился в очереди на печать длительное время без результата, и был из неё выброшен. Наиболее вероятно, что ККТ не подключена или не готова к приёму запросов. да
failed  От ККТ получен отказ в печати чека. Детали ошибки могут быть приведены в поле ошибки 29. да
Таблица 8.4.3. Статусы чека

При необходимости можно сформировать ссылку на чек по следующему шаблону:

 

Для чеков коррекции по ФФД 1.2 в поле custom_params будет возвращена JSON-строка, представляющая собой следующий объект:

28.1 correction_type Тип коррекции: self, by_order (самостоятельная, по предписанию ФНС).
28.2 correction_operation_date Дата совершения корректируемого расчёта. Формат: YYYY-MM-DD (тег 1178).
28.3 correction_document_number Номер предписания налогового органа, если correction_type равен by_order (тег 1179), строка до 32 символов.

Если попытка напечатать чек окончилась неудачей (то есть чек находится в статусе rejected или failed), в ответе будет заполнено поле error. Оно будет содержать JSON-строку, содержащую объект ошибки:

29.1 type  Тип ошибки — syntax_error, ffd_error, item_code_error, print_error, queue_error 
29.2 message Словесная расшифровка причины ошибки
29.3 error_id Идентификатор события ошибки в логах системы

Значения различных типов ошибок приведены в следующей таблице:

syntax_error Запрос содержит синтаксические ошибки в значении одного или
нескольких параметров. Отказ до отправки в ФН.
ffd_error Запрос содержит теги или сочетания тегов, не допустимые
согласно ФФД кассового устройства. Отказ при отправке в ФН.
item_code_error Код «Честный знак» товара не прошёл валидацию, а ККТ
настроена на режим отклонения чеков с не валидными кодами
print_error  Общая ошибка, без указания конкретной причины, на этапе обработки запроса в ККТ
queue_error  Ошибка постановки чека в очередь, до передачи запроса в ККТ. 

8.5. Поиск чеков по фискальным атрибутам. 

Тип Формат запроса
GET /info/receipts/search/?start=2020-10-18&end=2021-10-18&query=12345
  Параметр Назначение
1. start Дата начала периода в формате YYYY-MM-DD.
2. end Дата конца периода в формате YYYY-MM-DD.
3. query Строка для поиска. Поиск ведется по полям id, payment_id, contact. Можно выполнять поиск по части строки
Таблица 8.5.1. Параметры запроса

Формат ответа описан в таблице 8.1.1.

8.6. ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО

В настоящее время не используется

 

8.7. ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО

В настоящее время не используется

 

8.8. ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО

В настоящее время не используется

 

8.9. ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО

В настоящее время не используется

 

8.10. ЗАРЕЗЕРВИРОВАНО ЗАРЕЗЕРВИРОВАНО

В настоящее время не используется

 

8.11. Сгенерировать чек по платежу или с произвольными атрибутами /change/receipt/print/

Печать произвольного чека происходит в асинхронном режиме. Необходимо отправить данный запрос, а результат запроса проверить через некоторое время (рекомендуется не ранее, чем через 2 минуты).

Тип Формат запроса
  Параметр Назначение
POST /change/receipt/print/
1. payment_id Номер платежа, по которому нужно выдать чек. Может быть пустым (пустая строка: ''). Передавать обязательно!
2. type Тип чека, строка sale, refund, expense, expense-refund 
3. is_post_sale Пометить как чек окончательного расчёта, строка true или false. При type = refund не передаётся.
4. is_correction Для выдачи чека коррекции по ФФД 1.2. Строка true или false.
5. refund_id Порядковый номер возврата в рамках указанного платежа. Может быть пустым ( '' ). 
6. contact Почта или телефон плательщика. Телефон передаётся строкой в формате +79101234567 
7. sum_cashless Сумма, оплаченная безналичными
9. sum_cash Сумма, оплаченная наличными
10. sum_advance Сумма ранее проведённых предоплат или внесённых авансов
11. sum_credit Сумма выданного кредита
12. sum_counter_payment Сумма встречным предоставлением
13. cart Корзина товаров, таблица 12.1. Строка, кодирующая массив объектов в JSON-формате.
14. receipt_properties Дополнительные свойства чека, таблица 12.5. Строка, кодирующая объект в JSON-формате.
15. receipt_key Уникальный ключ чека, строка длиной не менее 6 символов. Будет отображаться как часть адреса постоянной страницы чека.
Таблица 8.11.1. Параметры запроса

При генерации чеков, не связанных с платежами в PayKeeper, рекомендуется оставлять пустыми payment_id и refund_id, а для сопоставления чека с операцией в информационной системе предприятия заполнять receipt_key своим уникальным идентификатором. Ключ чека рекомендуется составлять из символов a-z, A-Z, _, -, 0-9 достаточно длинным, чтобы не была возможна атака перебором. Результатом данного запроса будет объект с идентификатором чека:

Система не примет запрос, если с данными payment_id, refund_id, is_post_sale, type, receipt_key уже есть успешно сгенерированный или находящийся в процессе генерации чек, или чек, по которому наступил таймаут генерации. В последнем случае ранее отосланный запрос может оказаться успешным, и статус чека будет загружен позднее. Если требуется отправить чек, сохранив связь с платежом или возвратом, но с такими данными чек уже ранее был сгенерирован, нужно сгенерировать для него новый ключ чека.

При формировании чека коррекции по ФФД 1.2 в запросе, помимо поля is_correction = true, нужно передать дополнительные поля в POST-запросе:

 

4.1 correction_type Тип коррекции, строка: self, by_order 
4.2 correction_operation_date Дата совершения корректируемого расчёта. Формат:
YYYY-MM-DD (тег 1178)
4.3 correction_document_number Номер предписания налогового органа. Нужно передавать, если
correction_type равен by_order (тег 1179), строка до
32 символов.

8.12. Отправить запрос о состоянии чеков кассовому устройству. Если у чека нет фискальных атрибутов, этот запрос может их получить. ЗАРЕЗЕРВИРОВАНО

В настоящее время не используется

8.13. Уведомление системы ТСП о достижении чеком финального статуса 

Когда запрос на печать чека переходит в один из финальных статусов (см таблицу 8.4.3), в адрес сайта ТСП может быть отправлен POST-запрос уведомления о статусе чека. Это уведомление направляется однократно, без проверки принятия данного запроса сайтом ТСП.

В теле POST-запроса будут перечислены все параметры из таблицы 8.4.2, но дополнительно будет передана цифровая подпись запроса в параметре sign. Подпись вычисляется следующим образом: все переданные (в том числе пустые) параметры запроса сортируются в алфавитном порядке своих ключей, значения в виде строк конкатенируются через разделитель точка с запятой, берётся hmac_sha256 от этой строки с ключом — секретным словом POST-уведомлений.

Пример вычисления цифровой подписи запроса на языке PHP:

 

 

Заявка на консультацию
Оставьте заявку

Наш сотрудник свяжется с вами в ближайшее время

Получите консультацию

Расскажем про все детали подключения

Получайте платежи

Предоставим личный кабинет
и поможем настроить оплату

Мы гарантируем безопасность и сохранность ваших данных

Нажимая кнопку «Отправить заявку», вы подтверждаете, что согласны на обработку персональных данных

Ответим на вопросы и проконсультируем

+7 (800) 775-45-63 Бесплатный звонок по России

+7 (495) 984-89-15 Бесплатный звонок по Москве