3. Счета
API вызовы раздела «Счета» могут быть использованы для автоматизации выставления счетов, либо для генерации прямых ссылок на оплату для отображения в личном кабинете, отправки в собственных e-mail’ах, в Telegram, WhatsApp, Viber, SMS или любым другим способом.
Раздел протокола содержит следующие запросы:
| URI | Назначение | |
|---|---|---|
| 3.1 | /info/invoice/byid/ | Получение данных счёта по его номеру |
| 3.2 | /info/invoice/list/ | Получение истории счетов за период |
| 3.3 | /info/invoice/listcount/ | Получение количества счетов за период |
| 3.4 | /change/invoice/preview/ | Подготовка счёта |
| 3.5 | /change/invoice/send/ | Отправка созданного счёта |
| 3.6 | /change/invoice/revoke/ | Отмена созданного счёта |
| 3.7 | /change/invoice/accept-cash/ | Оплата счёта наличными |
3.1. Запрос получения данных счёта /info/invoice/byid/
Для получения данных счёта необходимо выполнить GET-запрос по URL с GET-параметром id, равным номеру нужного счёта.
| Тип | Формат запроса | ||
| GET | /info/invoice/byid/?id=20140402085214805 | ||
| Параметр | Назначение | ||
| 1. | id | Id счёта, по которому нужно получить данные | |
| Таблица 3.1.1. Параметры запроса | |||
В ответ возвращается объект следующего вида:
| Тип | Формат ответа | ||
| Параметр | Назначение | Допустимые значения | |
| 1. | id | Уникальный номер счёта | Строка из символов 0-9 |
| 2. | status | Статус заказа | Строковые значения created, sent, paid, expired |
| 3. | pay_amount | Сумма счёта | Число, разделитель дробной части – точка |
| 4. | clientid | Идентификатор клиента | Строка, любые буквы и цифры |
| 5. | orderid | Номер заказа | Строка, любые буквы и цифры |
| 6. | service_name | Наименование услуги | Строка, любые буквы и цифры |
| 7. | client_email | E-mail клиента | Строка, корректно записанный e-mail |
| 8. | client_phone | Телефон клиента | Строка, любые буквы и цифры |
| 9. | expiry_datetime | Счёт действует до | Дата в формате YYYY-MM-DD HH:MM:SS |
| 10. | created_datetime | Дата создания счёта | Дата в формате YYYY-MM-DD HH:MM:SS |
| 11. | paid_datetime | Дата оплаты счёта | Дата в формате YYYY-MM-DD HH:MM:SS. Если счёт не оплачен — null |
| 12. | user_id | Идентификатор пользователя ЛК, выставившего счёт | Число |
| 13. | payment_id | Номер платежа, которым оплачен счёт | Число, если счёт не оплачен — null |
| Таблица 3.1.2. Параметры ответа на запрос | |||
Пример ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
[ { "id" : "20110115085347329", "clientid" : "Ivanov Ivan Ivanovich", "orderid" : "1337", "paymentid" : "7331", "service_name" : "Document delivery", "client_email" : "ivanov@ivan.ivanovich.com", "client_phone" : "+79254973590", "created_datetime" : "2011-01-15 08:53:47", "paid_datetime" : "2011-01-16 14:12:00", "expiry_datetime" : "2011-01-19 00:00:00", "pay_amount" : "1205.98", "status" : "paid", "user_id" : 9 } ] |
3.2. История счетов /info/invoice/list/
Данный запрос позволяет получить список счетов за указанный период. Для удобства вывода в таблицу можно указать максимальное число объектов в выборке и пропустить первые сколько-то значений. Также, указав статусы, можно выбрать счета только с определёнными статусами. Счета выводятся в порядке от самого нового к самому старому.
| Тип | Формат запроса | ||
| GET | /info/invoice/list/?status[]=paid&start_date=2014-04-15&end_date=2014-04-25&from=30&limit=10 | ||
| Параметр | Назначение | ||
| 1. | status[] | Выбрать счета только с указанными статусами, может принимать значения sent, paid, expired. | |
| 2. | start_date | Выбрать счета, выставленные после даты в формате YYYY-MM-DD | |
| 3. | end_date | Выбрать счета, выставленные до даты в YYYY-MM-DD | |
| 4. | from | Пропустить N результатов в начале выборки | |
| 5. | limit | Выдавать не более указанного числа результатов | |
| Таблица 3.2.1. Параметры запроса | |||
В ответ возвращается массив объектов формата 3.1.1. Пример ответа:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
[ { "id" : "20140415042846859", "status" : "expired", "pay_amount" : "5999.00", "clientid" : "Кристина Бушуева", "orderid" : "3946", "service_name" : "null", "client_email" : "hidden@paykeeper.ru", "client_phone" : "null", "expiry_datetime" : "2014-04-19 00:00:00", "created_datetime": "2014-04-15 04:28:46", "paid_datetime" : "null" }, … ] |
Приведённый в примере запрос найдёт только оплаченные счета, выставленные в период от 15 апреля 2014 года до 25 апреля 2014 года, отбросит первые 30 результатов и выведет следующие 10. Если оплаченных счетов в этот период окажется менее 30, запрос вернёт пустой массив.
3.3. История счетов /info/invoice/listcount/
Данный запрос возвращает количество счетов за указанный период. Запрос возвращает данные, разбитые по статусам счетов sent, paid, expired. Указав статусы, можно подсчитать счета только с определёнными статусами. Для получения данных необходимо выполнить GET-запрос со следующими параметрами:
| Тип | Формат запроса | ||
| GET | /info/invoice/listcount/?status[]=expired&status[]=sent&status[]=paid&start_date=2014-04-15&end_date=2014-04-25 | ||
| Параметр | Назначение | ||
| 1. | status[] | Подсчитать счета только с указанными статусами, может принимать значения sent, paid, expired. | |
| 2. | start_date | Выбрать счета, выставленные после даты в формате YYYY-MM-DD | |
| 3. | end_date | Выбрать счета, выставленные до даты в YYYY-MM-DD | |
| Таблица 3.3.1. Параметры запроса | |||
В ответ возвращается составной объект следующего вида:
- Массив счетов, сгруппированный по статусам.
- Полный счётчик всех счетов с учётом фильтров.
| Тип | Формат ответа | |
| Параметр | Назначение | |
| 1. | statuses | Массив, сгруппированный по различным статусам, состоящий из элементов [status=>”value”,count=>”value”] |
| 2. | fullcount | Полное количество платежей |
| Таблица 3.3.2 Параметры ответа на запрос | ||
Пример ответа на запрос:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "statuses": [ {"status":"paid","count":"7"}, {"status":"expired","count":"9"}, {"status":"sent","count":"1"} ], "fullcount": [ {"count":"17"} ] } |
3.4. Подготовка счёта /change/invoice/preview/
Этот запрос создаёт по переданным параметрам оплаты счёт и генерирует для отображения в виде предварительного просмотра HTML-код письма счёта.
| Тип | Формат запроса | ||
| POST | /change/invoice/preview/ | ||
| Параметр | Назначение | ||
| 1. | pay_amount | Сумма заказа к оплате | |
| 2. | clientid | Идентификатор клиента | |
| 3. | orderid | Номер заказа | |
| 4. | service_name | Наименование услуги | |
| 5. | client_email | E-mail адрес клиента | |
| 6. | client_phone | Телефон клиента | |
| 7. | expiry | Срок действия счёта в формате YYYY-MM-DD или YYYY-MM-DD H:i:s (не включительно) |
|
| 8. | token | Токен безопасности. | |
| Таблица 3.4.1. Параметры запроса | |||
В ответ на данный запрос возвращается объект с полями invoice_id, содержащим уникальный номер созданного счёта, invoice_url, полный URL данного счёта, и invoice, где находится HTML-код предпросмотра e-mail сообщения, которое будет выслано клиенту:
|
1 2 3 4 5 |
{ "invoice_id" : "20120229133742255", "invoice_url" : 'https://pay.example.com/bill/20120229133742255", "invoice" : "<HTML><HEAD><META http-equiv=Content-Type ..." } |
Созданному счёту назначается служебный статус created. Счета с этим статусом не возвращаются в запросе истории счетов.
Плательщику можно передать адрес счёта из invoice_url, по любому каналу (почта, сервисы сообщений и т. п.). При переходе по этому адресу плательщик попадёт на страницу оплаты данного счёта для ввода реквизитов карты.
Также, к полученной ссылке можно добавить GET-параметр pstype с указанием идентификатора способа оплаты:
|
1 |
https://<адрес сервера Paykeeper>/bill/<invoice_id>?pstype= |
Например, если нужно показать плательщику QR-код Системы Быстрых Платежей, идентификатор способа оплаты sbp_default. Если нужно получить содержимое QR-кода для того, чтобы отобразить его своими средствами (в приложении, отправить в письме, напечатать на товарной накладной и т. п.), надо также добавить к URL счёта GET-параметр, returnFormat=json, например:
|
1 |
https://<адрес сервера Paykeeper>/bill/<invoice_id>?pstype=sbp_default&returnFormat=json |
При выставлении счёта возможно, также, указать не только список товарных позиций и дополнительные свойства чека, но и некоторые дополнительные атрибуты платежа. Для этого нужно в переменной service_name передавать JSON-объект со следующими полями:
| Поле | Назначение | ||
| cart | Объект корзины для чека 54-ФЗ | ||
| receipt_properties | Объект дополнительных свойств чека | ||
| lang | Параметр lang платежа | ||
| user_result_callback | Параметр user_result_callback платежа | ||
| service_name | При платеже будет отображаться в качестве наименования услуги | ||
| Таблица 3.4.2. Объект service_name | |||
Пример:
|
1 2 3 4 5 6 7 |
service_name := "{ cart : [ {...} ], user_result_callback : "https://", lang : 'ru'|'en', receipt_properties : { agent_info : {}, supplier_info: {} , ...} service_name : '' }" |
3.5. Отправка счёта клиенту /change/invoice/send/
Данный запрос отправляет клиенту письмо, созданное предыдущим запросом.
| Тип | Формат запроса | ||
| POST | /change/invoice/send/ | ||
| Параметр | Назначение | ||
| 1. | id | Идентификатор созданного счёта, письмо по которому необходимо отправить. | |
| 2. | token | Токен безопасности. | |
| Таблица 3.5.1. Параметры запроса | |||
Результатом данного запроса будет объект
|
1 2 3 |
{ "result" : "success" } |
в случае, если отправка произошла успешно, и объект ошибки, если письмо отправить не удалось.
3.6. Отмена счёта /change/invoice/revoke/
Данный запрос отменяет счёт, который был ранее сформирован.
| Тип | Формат запроса | ||
| POST | /change/invoice/revoke/ | ||
| Параметр | Назначение | ||
| 1. | id | Идентификатор созданного счёта, который нужно отменить. | |
| 2. | token | Токен безопасности. | |
| Таблица 3.6.1. Параметры запроса | |||
Результатом данного запроса будет объект
|
1 2 3 |
{ "result" : "success" } |
3.7. Оплата счёта наличными /change/invoice/accept-cash/
Данный запрос позволяет отметить счёт, как оплаченный наличными.
| Тип | Формат запроса | ||
| POST | /change/invoice/accept-cash/ | ||
| Параметр | Назначение | ||
| 1. | invoice_id | Идентификатор созданного счёта, который нужно оплатить. | |
| 2. | client_phone | Телефон плательщика (необязательный параметр). | |
| 3. | token | Токен безопасности. | |
| Таблица 3.7.1. Параметры запроса | |||
Результатом данного запроса будет следующий объект:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "result" : "success", "payment" : { "id" : "20140415042846859", "status" : "success", "pay_amount" : "777.00", "clientid" : "Иван Иванов", "orderid" : "34567", "service_name" : "null", "client_email" : "hidden@paykeeper.ru", "client_phone" : "+79954332810", "created_datetime": "2023-04-15 04:28:46", "paid_datetime" : "2023-04-19 04:29:15" } } |
Запросы 3.* и личный кабинет PayKeeper
Ниже приведен скриншот, поясняющий применение запросов данного раздела на примере личного кабинета PayKeeper.
Личный кабинет PayKeeper — Раздел счета