API вызовы раздела «Счета» могут быть использованы для автоматизации выставления счетов, либо для генерации прямых ссылок на оплату для отображения в личном кабинете, отправки в собственных e-mail’ах, в Telegram, WhatsApp, Viber, SMS или любым другим способом.
Раздел протокола содержит следующие запросы:
URI | Назначение | |
---|---|---|
3.1 | URI:/info/invoice/byid/ | Назначение:Получение данных счёта по его номеру |
3.2 | URI:/info/invoice/list/ | Назначение:Получение истории счетов за период |
3.3 | URI:/info/invoice/listcount/ | Назначение:Получение количества счетов за период |
3.4 | URI:/change/invoice/preview/ | Назначение:Подготовка счёта |
3.5 | URI:/change/invoice/send/ | Назначение:Отправка созданного счёта |
3.6 | URI:/change/invoice/revoke/ | Назначение:Отмена созданного счёта |
3.7 | URI:/change/invoice/accept-cash/ | Назначение:Оплата счёта наличными |
3.8 | URI:/info/invoice/search/ | Назначение:Поиск счёта по значениям параметров в диапазоне дат |
Для получения данных счёта необходимо выполнить 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 } ] |
Данный запрос позволяет получить список счетов за указанный период. Для удобства вывода в таблицу можно указать максимальное число объектов в выборке и пропустить первые сколько-то значений. Также, указав статусы, можно выбрать счета только с определёнными статусами. Счета выводятся в порядке от самого нового к самому старому.
Тип | Формат запроса | |
Тип: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, запрос вернёт пустой массив.
Данный запрос возвращает количество счетов за указанный период. Запрос возвращает данные, разбитые по статусам счетов 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"} ] } |
Этот запрос создаёт по переданным параметрам оплаты счёт и генерирует для отображения в виде предварительного просмотра 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 : '' }" |
Данный запрос отправляет клиенту письмо, созданное предыдущим запросом.
Тип | Формат запроса | |
Тип:POST | Формат запроса:/change/invoice/send/ |
Параметр | Назначение | |
1. | Параметр:id | Назначение:Идентификатор созданного счёта, письмо по которому необходимо отправить. |
2. | Параметр:token | Назначение:Токен безопасности. |
Таблица 3.5.1. Параметры запроса |
Результатом данного запроса будет объект
1 2 3 |
{ "result" : "success" } |
в случае, если отправка произошла успешно, и объект ошибки, если письмо отправить не удалось.
Данный запрос отменяет счёт, который был ранее сформирован.
Тип | Формат запроса | |
Тип:POST | Формат запроса:/change/invoice/revoke/ |
Параметр | Назначение | |
1. | Параметр:id | Назначение:Идентификатор созданного счёта, который нужно отменить. |
2. | Параметр:token | Назначение:Токен безопасности. |
Таблица 3.6.1. Параметры запроса |
Результатом данного запроса будет объект
1 2 3 |
{ "result" : "success" } |
Данный запрос позволяет отметить счёт, как оплаченный наличными.
Тип | Формат запроса | |
Тип: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" } } |
Запрос возвращает счета, чьи номера, параметры оплаты, номера карт или коды авторизаций содержат указанную в запросу подстроку. Поиск осуществляется в пределах диапазона дат, который задаётся параметрами запроса.
Тип | Формат запроса | |
Тип:GET | Формат запроса:/info/invoice/search/?query=4038*9682&start_date=2016-01-01&end_date=2017-04-04 |
Параметр | Назначение | |
1. | Параметр:query | Назначение:Подстрока для поиска в параметрах счета id, id платежа и clientid, а также в опциях orderid, service_name, client_email, client_phone. Поиск поддерживает синтаксис MySQL like. Символ * заменяется на %. |
2. | Параметр:start_date | Назначение:Дата начала периода в формате YYYY-MM-DD. |
3. | Параметр:end_date | Назначение:Дата конца периода в формате YYYY-MM-DD. |
Таблица 3.8.1. Параметры запроса |
Ответ на запрос содержит массив объектов следующего вида.
Тип | Формат ответа | |
Параметр | Назначение | |
1. | Параметр:id | Назначение:Номер счета |
2. | Параметр:
user_id
|
Назначение:Идентификатор пользователя, создавшего счет |
3. | Параметр:
status
|
Назначение:Статус счета, может принимать значения created, sent, paid, expired |
4. | Параметр:pay_amount | Назначение:Сумма заказа к оплате |
5. | Параметр:clientid | Назначение:Идентификатор клиента |
6. | Параметр:orderid | Назначение:Номер заказа |
7. | Параметр:
paymentid
|
Назначение:Идентификатор платежа |
8. | Параметр:service_name | Назначение:Наименование услуги |
9. | Параметр:client_email | Назначение:E-mail адрес клиента |
10. | Параметр:client_phone | Назначение:Телефон клиента |
11. | Параметр:
expiry_datetime
|
Назначение:Срок действия счёта в формате YYYY-MM-DD или YYYY-MM-DD H:i:s (не включительно) |
12. | Параметр:
created_datetime
|
Параметр:Дата-время создания счета YYYY-MM-DD H:i:s |
13. | Параметр:
paid_datetime
|
Назначение:Дата-время оплаты счета YYYY-MM-DD H:i:s |
Таблица 3.8.2 Параметры ответа на запрос |
Пример возвращаемого массива:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
[ { "id": "20240320163112427", "user_id": "3", "status": "paid", "pay_amount": "123.00", "clientid": "Иванов В.В.", "orderid": "135", "paymentid": "253", "service_name": "Оплата за услуги ", "client_email": "test@test.ru", "client_phone": "+7", "expiry_datetime": null, "created_datetime": "2024-03-20 16:31:12", "paid_datetime": "2024-03-20 16:32:26" }, ... ] |
Ниже приведен скриншот, поясняющий применение запросов данного раздела на примере личного кабинета PayKeeper.