API вызовы раздела «Счета» могут быть использованы для автоматизации выставления счетов, либо для генерации прямых ссылок на оплату для отображения в личном кабинете, отправки в собственных e-mail’ах, в Telegram, 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/ | Отмена созданного счёта |
Для получения данных счёта необходимо выполнить 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. | paymentid | Номер платежа | Номер платежа, которым был оплачен счёт. Если счёт не оплачен — null |
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 |
Таблица 3.1.2. Параметры ответа на запрос |
Пример ответа на запрос:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
[ { "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" } ] |
Данный запрос позволяет получить список счетов за указанный период. Для удобства вывода в таблицу можно указать максимальное число объектов в выборке и пропустить первые сколько-то значений. Также, указав статусы, можно выбрать счета только с определёнными статусами. Счета выводятся в порядке от самого нового к самому старому.
Тип | Формат запроса | ||
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 (не включительно) | |
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=<ps_type> |
При выставлении счёта возможно, также, указать не только список товарных позиций и дополнительные свойства чека, но и некоторые дополнительные аттрибуты платежа. Для этого нужно в переменной 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" } |
Ниже приведен скриншот поясняющий применение запросов данного раздела на примере личного кабинета PayKeeper.