REST API · v1

API-документация

Выставляйте счёт и получайте платёжную ссылку одним запросом. Приём оплаты идёт через сервис поверх лицензированного платёжного провайдера — данные карт на вашей стороне не хранятся.

Доступ и авторизация

Ключ API выдаётся по запросу подключённой компании. Передавайте его в заголовке Authorization по схеме Bearer. Ключ привязан к вашей организации — не публикуйте его на клиенте.

Authorization: Bearer <ваш_api_ключ>
Content-Type: application/json

Базовый URL: https://app.saldio.ru. Лимит запросов — 60 в минуту на IP (превышение → 429).

Создать счёт

POST /api/v1/invoices

Создаёт счёт и платёжную ссылку. Контрагента можно передать по id (если уже заведён) либо реквизитами — тогда он найдётся по ИНН или будет создан.

Тело запроса

Поле	Тип	Обяз.	Описание
amount	number	да	Сумма к оплате, больше 0.
dueDate	string (ISO)	да	Срок оплаты, ISO-дата.
method	string	нет	sbp \| card \| transfer. По умолчанию sbp.
externalId	string	нет	Ваш идентификатор счёта (идемпотентность).
description	string	нет	Назначение / комментарий.
providerCode	string	нет	Код платёжного провайдера (если их несколько).
counterparty.id	string	нет*	Id уже заведённого контрагента.
counterparty.name	string	нет*	Название. Обязательно, если нет id.
counterparty.inn	string	нет*	ИНН (проверяется по контрольным цифрам). Обязателен, если нет id.
counterparty.kpp	string	нет	КПП.
counterparty.email	string	нет	E-mail для доставки счёта.
counterparty.phone	string	нет	Телефон.
counterparty.address	string	нет	Адрес.

* Либо counterparty.id, либо пара name + inn.

Идемпотентность

Передайте заголовок Idempotency-Key (или externalId в теле): повторный запрос с тем же ключом вернёт ранее созданный счёт, а не создаст дубль.

Пример

curl -X POST https://app.saldio.ru/api/v1/invoices \
  -H "Authorization: Bearer <ваш_api_ключ>" \
  -H "Idempotency-Key: order-10023" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 131500,
    "dueDate": "2026-08-01",
    "method": "sbp",
    "description": "Оплата по договору №10023",
    "counterparty": { "name": "ООО Ромашка", "inn": "7701234567" }
  }'

Ответ 201 Created

{
  "invoiceId": "clx…",
  "number": "СЛД-2026-000042",
  "externalId": "order-10023",
  "status": "sent",
  "amount": 131500,
  "paidAmount": 0,
  "currency": "RUB",
  "method": "sbp",
  "dueDate": "2026-08-01T00:00:00.000Z",
  "checkoutUrl": "https://app.saldio.ru/checkout/clx…",
  "paymentUrl": "https://…",
  "counterparty": { "id": "clc…", "name": "ООО Ромашка", "inn": "7701234567" }
}

Дайте плательщику checkoutUrl — страницу оплаты СБП/картой. Статус счёта меняется на paid после подтверждения оплаты провайдером.

Ошибки

400	Bad Request	Некорректное тело: amount ≤ 0, неверный dueDate/method, невалидный ИНН, нет name.
401	Unauthorized	Нет или неверный ключ API.
409	Conflict	Контрагент на паузе (заблокирован).
429	Too Many Requests	Превышен лимит запросов.

Тело ошибки: { "error": "описание" }.

Нужен ключ API?

Подключите компанию — менеджер выдаст ключ и поможет с первой интеграцией.

Подключить компанию Поддержка