Москва: 8 (495) 984-87-51
Санкт-Петербург: 8 (812) 385-75-57
8 (800) 775-37-51Контакт центр

3. Счета

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/ Назначение:Поиск счёта по значениям параметров в диапазоне дат

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

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

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 или YYYY-MM-DD H:i:s (не включительно)
8. Параметр:token Назначение:Токен безопасности.
Таблица 3.4.1. Параметры запроса

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

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

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

Также, к полученной ссылке можно добавить GET-параметр pstype с указанием идентификатора способа оплаты:

Например, если нужно показать плательщику QR-код Системы Быстрых Платежей, идентификатор способа оплаты sbp_default.  Если нужно получить содержимое QR-кода для того, чтобы отобразить его своими средствами (в приложении, отправить в письме, напечатать на товарной накладной и т. п.), надо также добавить к URL счёта GET-параметр, returnFormat=json, например:

При выставлении счёта возможно, также, указать не только список товарных позиций и дополнительные свойства чека, но и некоторые дополнительные атрибуты платежа. Для этого нужно в переменной service_name передавать JSON-объект со следующими полями:

Поле Назначение
Поле:cart Назначение:Объект корзины для чека 54-ФЗ
Поле:receipt_properties Назначение:Объект дополнительных свойств чека
Поле:lang Назначение:Параметр lang платежа
user_result_callback Параметр user_result_callback платежа
Поле:service_name Назначение:При платеже будет отображаться в качестве наименования услуги
Таблица 3.4.2. Объект service_name

Пример:

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

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

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

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

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

3.6. Отмена счёта /change/invoice/revoke/

Данный запрос отменяет счёт, который был ранее сформирован.

Тип Формат запроса
Тип:POST Формат запроса:/change/invoice/revoke/
Параметр Назначение
1. Параметр:id Назначение:Идентификатор созданного счёта, который нужно отменить.
2. Параметр:token Назначение:Токен безопасности.
Таблица 3.6.1. Параметры запроса

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

3.7. Оплата счёта наличными /change/invoice/accept-cash/

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

Тип Формат запроса
Тип:POST Формат запроса:/change/invoice/accept-cash/
Параметр Назначение
1. Параметр:invoice_id Назначение:Идентификатор созданного счёта, который нужно оплатить.
2. Параметр:client_phone Назначение:Телефон плательщика (необязательный параметр).
3. Параметр:token Назначение:Токен безопасности.
Таблица 3.7.1. Параметры запроса

Результатом данного запроса будет следующий объект:

3.8. Поиск счета по значениям параметров в диапазоне дат /info/invoice/search/

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

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

Пример возвращаемого массива:

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

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

Личный кабинет PayKeeper — Раздел счета