3. Счета

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

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

 

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. Пример ответа:

Приведённый в примере запрос найдёт только оплаченные счета, выставленные в период от 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 Параметры ответа на запрос

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

 

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 (не включительно)
8.	token	Токен безопасности.

В ответ на данный запрос возвращается объект с полями invoice_id, содержащим уникальный номер созданного счёта, invoice_url , полный URL данного счёта, и invoice, где находится HTML-код предпросмотра e-mail сообщения, которое будет выслано клиенту:

Созданному счёту назначается служебный статус created. Счета с этим статусом не возвращаются в запросе истории счетов.

Плательщику можно передать адрес счёта из invoice_url , по любому каналу (почта, сервисы сообщений и т.п.). При переходе по этому адресу плательщик попадёт на страницу оплаты данного счёта для ввода реквизитов карты.

3.5. Отправка счёта клиенту /change/invoice/send/

Данный запрос отправляет клиенту письмо, созданное предыдущим запросом.

Тип	Формат запроса
POST	/change/invoice/send/
	Параметр	Назначение
1.	id	Идентификатор созданного счёта, письмо по которому необходимо отправить.
2.	token	Токен безопасности.

Результатом данного запроса будет объект

в случае, если отправка произошла успешно, и объект ошибки, если письмо отправить не удалось.

Запросы 3.* и личный кабинет PayKeeper

Ниже приведен скриншот поясняющий применение запросов данного раздела на примере личного кабинета PayKeeper.