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

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

[
      {
      "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
       }
]

[

{

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

[
     { 
     "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"
     },
…
]

[

{

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

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

{
    "statuses":
    [
        {"status":"paid","count":"7"},
        {"status":"expired","count":"9"},
        {"status":"sent","count":"1"}
    ],
    "fullcount":
    [
        {"count":"17"}
    ]
}

{

"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 сообщения, которое будет выслано клиенту:

{ 
  "invoice_id" : "20120229133742255", 
  "invoice_url" : 'https://pay.example.com/bill/20120229133742255",
  "invoice"    : "&lt;HTML&gt;&lt;HEAD&gt;&lt;META http-equiv=Content-Type ..."
}

{

"invoice_id" : "20120229133742255",

"invoice_url" : 'https://pay.example.com/bill/20120229133742255",

"invoice" : "<HTML><HEAD><META http-equiv=Content-Type ..."

}

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

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

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

https://<адрес сервера Paykeeper>/bill/<invoice_id>?pstype=

1	https://<адрес сервера Paykeeper>/bill/<invoice_id>?pstype=

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

https://<адрес сервера Paykeeper>/bill/<invoice_id>?pstype=sbp_default&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

Пример:

service_name := "{
  cart : [ {...} ],
  user_result_callback : "https://",
  lang : 'ru'|'en',
  receipt_properties : {  agent_info : {}, supplier_info: {} , ...}
  service_name : ''
}"

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

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

{ 
  "result" : "success"
}

{

"result" : "success"

}

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

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

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

Тип	Формат запроса
Тип:POST	Формат запроса:/change/invoice/revoke/

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

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

{ 
  "result" : "success"
}

{

"result" : "success"

}

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

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

Тип	Формат запроса
Тип:POST	Формат запроса:/change/invoice/accept-cash/

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

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

{ 
  "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"
     }
}

{

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

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

[ 
     {
        "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"
    }, ...

]

[

{

"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"

}, ...

]

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

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

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