ERP Platform Docs

03-scheta

время чтения ~3 мин.

3. Счета

Источник: https://docs.paykeeper.ru/dokumentatsiya-json-api/scheta/

API-вызовы раздела «Счета» позволяют автоматически выставлять счета или формировать прямые ссылки на оплату для показа в ЛК, email-рассылке или мессенджерах.

Список запросов

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/Аннулировать счёт
3.7 /change/invoice/accept-cash/Пометить счёт оплаченным наличными
3.8 /info/invoice/search/Поиск счетов

3.1 Данные счёта /info/invoice/byid/

Тип: GET
Формат: /info/invoice/byid/?id=20140402085214805

Параметры: id — ID счёта.

Параметры ответа:

ПолеНазначениеФормат
idУникальный номер счётастрока 0-9
statusСтатусcreated, sent, paid, expired
pay_amountСуммачисло
clientidИдентификатор клиентастрока
orderidНомер заказастрока
service_nameНазвание услугистрока
client_emailEmailemail
client_phoneТелефонстрока
expiry_datetimeСрок действияYYYY-MM-DD HH:MM:SS
created_datetimeДата созданияYYYY-MM-DD HH:MM:SS
paid_datetimeДата оплатыYYYY-MM-DD HH:MM:SS / null
user_idID пользователя-создателячисло
paymentidНомер платежачисло / null

Пример:

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

Параметры:

ПараметрНазначение
status[]sent, paid, expired
start_dateНачало (YYYY-MM-DD)
end_dateКонец (YYYY-MM-DD)
fromПропустить N
limitМаксимум результатов

Формат ответа как в 3.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"
  }
]

3.3 Количество счетов /info/invoice/listcount/

Тип: GET
Формат: /info/invoice/listcount/?status[]=expired&status[]=sent&status[]=paid&start_date=2014-04-15&end_date=2014-04-25

Параметры ответа:

ПолеНазначение
statusesГруппировка по статусу
fullcountОбщее количество

Пример:

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

3.4 Подготовить счёт /change/invoice/preview/

Тип: POST
Формат: /change/invoice/preview/

Параметры:

ПараметрНазначение
pay_amountСумма
clientidID клиента
orderidНомер заказа
service_nameНазвание услуги
client_emailEmail
client_phoneТелефон
expiryСрок (YYYY-MM-DD или YYYY-MM-DD H:i:s)
tokenТокен

Создаёт счёт и возвращает HTML-превью письма.

Пример ответа:

{
  "invoice_id": "20120229133742255",
  "invoice_url": "https://pay.example.com/bill/20120229133742255",
  "invoice": "<HTML><HEAD><META http-equiv=Content-Type ..."
}

Созданные счета имеют статус created. Можно добавить ?pstype= для способа оплаты (например, sbp_default для QR СБП).

service_name как JSON-объект (для чека 54-ФЗ):

{
  "cart": "[{\"name\":\"Товар 1\",\"price\":100,\"quantity\":1,\"sum\":\"100\",\"tax\":\"vat20\"},{\"name\":\"Товар 2\",\"price\":100,\"quantity\":2,\"sum\":\"200\",\"tax\":\"vat10\"}]",
  "receipt_properties": "{\"agent\":{\"type\":\"other\"},\"supplier\":{\"name\": \"ООО ПОСТАВЩИК\", \"inn\": \"1234567890\", \"phones\": [\"+79990000000\"]}}",
  "lang": "ru",
  "user_result_callback": "https://ваш-сайт.ru/callback",
  "service_name": "Онлайн-заказ"
}

3.5 Отправить счёт /change/invoice/send/

Тип: POST
Формат: /change/invoice/send/

Параметры: id, token.

Ответ:

{"result": "success"}

3.6 Аннулировать счёт /change/invoice/revoke/

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

Параметры: id, token.

Ответ:

{"result": "success"}

3.7 Пометить счёт оплаченным наличными /change/invoice/accept-cash/

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

Параметры:

ПараметрНазначение
invoice_idID счёта
client_phoneТелефон плательщика (опционально)
tokenТокен

Ответ:

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

Параметры:

ПараметрНазначение
queryПодстрока (id, payment id, clientid, orderid, service_name, email, phone). MySQL LIKE; * = %
start_dateНачало
end_dateКонец

Параметры ответа: как в 3.1 + user_id.

Пример:

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

Вид графа

Обратные ссылки