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.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.
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.4.2 Параметры ответа на запрос

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

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

 

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.
3. is_post_sale Пометить как чек окончательного расчёта, строка true или false. При type = refund не указывается
4. refund_id Порядковый номер возврата в рамках указанного платежа. Может быть пустым (»).
5. contact Почта или телефон плательщика
6. sum_cashless Сумма, оплаченная безналичными
7. sum_cash Сумма, оплаченная наличными
8. sum_advance Сумма ранее проведённых предоплат или внесённых авансов
6. contact Почта или телефон плательщика
7. contact Почта или телефон плательщика
8. contact Почта или телефон плательщика
9. sum_credit Сумма выданного кредита
10. cart Корзина товаров, таблица 12.1. Строка, кодирующая массив объектов в JSON-формате.
11. receipt_properties Дополнительные свойства чека, таблица 12.5. Строка, кодирующая объект в JSON-формате.
12. 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 уже есть успешно сгенерированный или находящийся в процессе генерации чек, или чек, по которому наступил таймаут генерации. В последнем случае ранее отосланный запрос может оказаться успешным, и статус чека будет загружен позднее. Если требуется отправить чек, сохранив связь с платежом или возвратом, но с такими данными чек уже ранее был сгенерирован, нужно сгенерировать для него новый ключ чека.

 

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

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