Разработчикам

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

REST API v1. JSON, Bearer-аутентификация и предсказуемые статусы.

01 / Авторизация

API подготовлен; реальная проверка станет доступна после получения прямого доступа к ФНС. Доступ выдаётся по заявке в кабинете и только для согласованных сценариев. После одобрения создайте ключ и передавайте его в заголовке. Секрет показывается один раз.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Вызовы выполняются с вашего сервера. Ключ нельзя публиковать в JavaScript, мобильном приложении или открытом репозитории. Cookie-сессия не авторизует API.

02 / Проверить чек

POST /api/v1/receipts

Передайте строку QR или отдельные поля fn, i, fp, t, s, n. consent: true означает, что вы получили согласие владельца на обработку данных чека.

curl https://check.pav.studio/api/v1/receipts \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"qr":"YOUR_RECEIPT_QR_STRING","consent":true}'

Поле	Формат
fn	ФН, строка из 16 цифр
i	ФД, от 1 до 10 цифр
fp	ФП, от 1 до 10 цифр, не более 4294967295
t	Дата покупки: YYYYMMDDTHHmm
s	Сумма в рублях, строка «1490.00»
n	1 — приход, 2 — возврат прихода, 3 — расход, 4 — возврат расхода

201 — новая проверка завершена; 202 — запрос принят и ожидает данных; 200 — ранее сохранённый результат. Повторная отправка тех же реквизитов тем же аккаунтом возвращает сохранённый чек и не расходует новую проверку.

{
  "id": "UUID",
  "status": "verified",
  "status_label": "Чек найден",
  "message": "…",
  "fiscal": {"fn": "…", "i": "…", "fp": "…"},
  "receipt": {"user": "…", "totalSum": 149000, "items": []},
  "created_at": "2026-11-02T09:00:00+00:00",
  "updated_at": "2026-11-02T09:00:01+00:00"
}

Это пример структуры, а не реальный чек. В объекте receipt денежные значения — в копейках; fiscal.s — в рублях. При отсутствии результата receipt равен null.

03 / Получить результат

GET /api/v1/receipts/{id}

Только чеки владельца API-ключа. Для ожидания повторяйте запрос с интервалом не менее 15 секунд и прекращайте опрос при конечном статусе.

Статус	Значение
verified	Получены фискальные данные, реквизиты совпадают.
processing / pending	Запрос обрабатывается. Фоновые попытки ограничены.
not_found	Чек не возвращён источником. Это не доказательство подделки.
mismatch	Реквизиты ответа отличаются от запроса.
unavailable	Источник недоступен; лимит возвращён. Можно повторить POST.

04 / Лимиты и ошибки

GET /api/v1/usage

Остаток общего лимита аккаунта: daily_limit, daily_used, daily_left, monthly_limit, monthly_used, monthly_left. Ключ дополнительно ограничен своими квотами. Web и API расходуют один общий бюджет. Сутки и календарный месяц определяются по Москве.

{"error":{"code":"quota_exceeded","message":"…"}}

HTTP	Действие клиента
400	Исправьте реквизиты, JSON или передайте согласие.
401 / 403	Проверьте ключ и одобрение доступа.
404	Чек отсутствует или принадлежит другому аккаунту.
405 / 415	Проверьте метод и Content-Type.
429	Учитывайте Retry-After. Проверьте суточную и месячную квоту в кабинете.
503	Сервис/источник недоступен. Проверка не списана.