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)

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

{
  "receipts": [
    {
      "id": "2107145011",
      "payment_id": "0",
      "type": "sale",
      "is_post_sale": "0",
      "refund_id": "0",
      "status": "request_sent",
      "contact": "",
      "sum_cashless": "1.00",
      "sum_cash": "0.00",
      "sum_advance": "0.00",
      "sum_credit": "0.00",
      "cart": [
        {
          "item_type": "goods",
          "payment_type": "prepay",
          "sku": "",
          "name": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean vehicula pharetra maximus. Phasellus ultrices, arcu at lacinia ",
          "price": "1",
          "quantity": "1",
          "item_code": "",
          "tax": "none",
          "sum": 1,
          "agent": {
            "type": "other",
            "phones": null,
            "operation": null,
            "inn": null,
            "name": null,
            "address": null,
            "transfer_phones": null,
            "receiver_phones": null
          },
          "supplier": {
            "phones": [
              "+79101234567"
            ],
            "inn": "5544332219",
            "name": "ООО ТЕСТ"
          }
        }
      ],
      "receipt_properties": "{\"client\":null,\"agent\":{\"type\":\"other\",\"phones\":null,\"operation\":null,\"inn\":null,\"name\":null,\"address\":null,\"transfer_phones\":null,\"receiver_phones\":null},\"supplier\":{\"phones\":[\"+79101234567\"],\"inn\":\"5544332219\",\"name\":\"\\u041e\\u041e\\u041e \\u0422\\u0415\\u0421\\u0422\"}}",
      "fpd": null,
      "fnd": null,
      "fn": null,
      "ts": null,
      "rnkkt": null,
      "shift_number": null,
      "receipt_number": null,
      "request_datetime": "2021-10-12 11:27:12",
      "obtain_datetime": null,
      "fop_receipt_key": "XjtaLpCw_kqfiiI",
      "fop_uuid": "27e80723-21e7-418b-9806-00f1a7e6aef8",
      "fop_url": null
    },
],
  "counts": {
    "status": {
      "request_sent": 4
    },
    "receipt_type": {
      "sale": 4
    },
    "sum_type": {
      "sum_cashless": 4
    },
    "page_size": 4,
    "totals": {
      "sum_type": {
        "sum_cashless": 4,
        "sum_cash": 0,
        "sum_advance": 0,
        "sum_credit": 0
      },
      "status": {
        "created": 0,
        "request_sent": 4,
        "success": 0,
        "failed": 0,
        "timeout": 0
      },
      "receipt_type": {
        "sale": 4,
        "refund": 0,
        "expense": 0,
        "expense_refund": 0,
        "correction": 0
      },
      "total": 4
    }
  }
}

{

"receipts": [

{

"id": "2107145011",

"payment_id": "0",

"type": "sale",

"is_post_sale": "0",

"refund_id": "0",

"status": "request_sent",

"contact": "",

"sum_cashless": "1.00",

"sum_cash": "0.00",

"sum_advance": "0.00",

"sum_credit": "0.00",

"cart": [

{

"item_type": "goods",

"payment_type": "prepay",

"sku": "",

"name": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean vehicula pharetra maximus. Phasellus ultrices, arcu at lacinia ",

"price": "1",

"quantity": "1",

"item_code": "",

"tax": "none",

"sum": 1,

"agent": {

"type": "other",

"phones": null,

"operation": null,

"inn": null,

"name": null,

"address": null,

"transfer_phones": null,

"receiver_phones": null

"supplier": {

"phones": [

"+79101234567"

"inn": "5544332219",

"name": "ООО ТЕСТ"

}

"receipt_properties": "{\"client\":null,\"agent\":{\"type\":\"other\",\"phones\":null,\"operation\":null,\"inn\":null,\"name\":null,\"address\":null,\"transfer_phones\":null,\"receiver_phones\":null},\"supplier\":{\"phones\":[\"+79101234567\"],\"inn\":\"5544332219\",\"name\":\"\\u041e\\u041e\\u041e \\u0422\\u0415\\u0421\\u0422\"}}",

"fpd": null,

"fnd": null,

"fn": null,

"ts": null,

"rnkkt": null,

"shift_number": null,

"receipt_number": null,

"request_datetime": "2021-10-12 11:27:12",

"obtain_datetime": null,

"fop_receipt_key": "XjtaLpCw_kqfiiI",

"fop_uuid": "27e80723-21e7-418b-9806-00f1a7e6aef8",

"fop_url": null

"counts": {

"status": {

"request_sent": 4

"receipt_type": {

"sale": 4

"sum_type": {

"sum_cashless": 4

"page_size": 4,

"totals": {

"sum_type": {

"sum_cashless": 4,

"sum_cash": 0,

"sum_advance": 0,

"sum_credit": 0

"status": {

"created": 0,

"request_sent": 4,

"success": 0,

"failed": 0,

"timeout": 0

"receipt_type": {

"sale": 4,

"refund": 0,

"expense": 0,

"expense_refund": 0,

"correction": 0

"total": 4

}

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

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

{
  "sum_type": {
    "sum_cashless": 15,
    "sum_cash": 0,
    "sum_advance": 5,
    "sum_credit": 0
  },
  "status": {
    "created": 1,
    "request_sent": 11,
    "success": 7,
    "failed": 1,
    "timeout": 0
  },
  "receipt_type": {
    "sale": 20,
    "refund": 0,
    "expense": 0,
    "expense_refund": 0,
    "correction": 0
  },
  "total": 20
}

{

"sum_type": {

"sum_cashless": 15,

"sum_cash": 0,

"sum_advance": 5,

"sum_credit": 0

"status": {

"created": 1,

"request_sent": 11,

"success": 7,

"failed": 1,

"timeout": 0

"receipt_type": {

"sale": 20,

"refund": 0,

"expense": 0,

"expense_refund": 0,

"correction": 0

"total": 20

}

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

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

{
     "id": "4201",
     "payment_id":"2098",
     "type":"sale",
     "is_post_sale":"1",
     "refund_id":null,
     "status":"success",
     "contact":"client@mail.ru",
     "sum_cashless":"0.00",
     "sum_cash":"0.00",
     "sum_advance":"15529.10",
     "sum_credit":"0.00",
     "cart":"[{\"name\":\"TEST 3\",\"quantity\":1,\"price\":15529.10,\"sum\":15529.10,\"tax\":\"none\",\"payment_type\":\"full\"}]",
     "receipt_properties":"null",
     "fpd":"2020473855",
     "fnd":"8930",
     "fn":"9999078900001341",
     "ts":"20190621T1638",
     "rnkkt":"0000000400054952",
     "shift_number":"7123",
     "receipt_number":"6162",
     "obtain_datetime":"2019-05-11 09:12:22",
     "request_datetime":"2019-05-11 09:12:01",
     "fop_receipt_key":"VhamK7kl",
     "fop_uuid":"6ee-cs-130",
     "fop_url":"t=20190511T0912&amp;s=15529.10&amp;fn=9999078900001341&amp;i=8930&amp;fp=2020473855&amp;n=1"
}

{

"id": "4201",

"payment_id":"2098",

"type":"sale",

"is_post_sale":"1",

"refund_id":null,

"status":"success",

"contact":"client@mail.ru",

"sum_cashless":"0.00",

"sum_cash":"0.00",

"sum_advance":"15529.10",

"sum_credit":"0.00",

"cart":"[{\"name\":\"TEST 3\",\"quantity\":1,\"price\":15529.10,\"sum\":15529.10,\"tax\":\"none\",\"payment_type\":\"full\"}]",

"receipt_properties":"null",

"fpd":"2020473855",

"fnd":"8930",

"fn":"9999078900001341",

"ts":"20190621T1638",

"rnkkt":"0000000400054952",

"shift_number":"7123",

"receipt_number":"6162",

"obtain_datetime":"2019-05-11 09:12:22",

"request_datetime":"2019-05-11 09:12:01",

"fop_receipt_key":"VhamK7kl",

"fop_uuid":"6ee-cs-130",

"fop_url":"t=20190511T0912&s=15529.10&fn=9999078900001341&i=8930&fp=2020473855&n=1"

}

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

https://&lt;адрес сервера Paykeeper&gt;/receipt/

1	https://<адрес сервера Paykeeper>/receipt/

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	Сумма ранее проведённых предоплат или внесённых авансов
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 достаточно длинным, чтобы не была возможна атака перебором. Результатом данного запроса будет объект с идентификатором чека:

{
     'receipt_id' : 816
}

{

'receipt_id' : 816

}

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

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

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