Валидатор API

Проверка подлинности чеков об оплате. Вы отдаёте чек и данные заявки - получаете один статус и одно действие: проводить платёж, посмотреть руками или попросить новый чек.

Как это работает

Путей приёма чека два, дальше они сходятся: та же проверка, те же статусы, те же вебхуки.

Путь 1, основной - чек прикладывает плательщик

Файл к вам не попадает вовсе: своя форма загрузки и хранилище чужих чеков не нужны.

1. Вы заводите заявку запросом POST /v1/upload-links с полями заявки. В ответе сразу все адреса: upload_url - страница для плательщика, embed_url - она же рамкой на вашем сайте, email_address - адрес для письма из банка, а для вас status_url и receipt_url.
2. Плательщик открывает страницу (GET /u/{token}) и прикладывает фото, снимок экрана или PDF. Ключ API ему не нужен: пропуск - токен ссылки со сроком и лимитом попыток.
3. Судьба заявки - одним адресом GET /v1/upload-links/{token}: file_received - чек приложен (останавливайте свой таймер), checking и eta_seconds - идёт проверка, job_id и verdict - готово. Не подошёл чек - плательщик шлёт новый по той же ссылке, счёт виден в attempts и resend_left_seconds.

Путь 2 - чек отдаёте вы

Файл уже у вас: из вашей формы, от другой системы или из архива.

1. Вы отдаёте чек запросом POST /v1/receipts:validate: файл (или временная ссылка на него) плюс поля заявки. Ответ приходит сразу, проверка идёт в фоне.
2. Вердикт приходит вебхуком или забирается запросом GET /v1/receipts/{job_id}. Нужен ответ одним запросом - добавьте wait_seconds.

Быстрый старт

Три запроса в песочницу: подать чек, забрать вердикт, сообщить итог ордера. Язык примеров переключается над блоком кода - выбор запоминается на всей странице.

# 1. Подать чек (файлом)
curl -s https://chekvalidator.com/sandbox/v1/receipts:validate \
  -H "Authorization: Bearer sandbox-demo-key" \
  -F "file=@check.jpg" \
  -F "request_id=ORDER-1001" \
  -F "expected_amount=1500.00" \
  -F "requisite=79001234567" \
  -F "initiated_at=2026-08-23T10:15:00"

# Ответ: {"job_id":"...","status":"pending","eta_seconds":3.5,"status_url":"...",...}

# 2. Забрать результат (через пару секунд)
curl -s https://chekvalidator.com/sandbox/v1/receipts/<job_id> \
  -H "Authorization: Bearer sandbox-demo-key"

# Ответ: {"status":"done","verdict":"accepted","status_color":"green",...}

# 3. Сообщить итог ордера
curl -s https://chekvalidator.com/sandbox/v1/receipts/<job_id>/feedback \
  -H "Authorization: Bearer sandbox-demo-key" \
  -H "Content-Type: application/json" \
  -d '{"order_outcome":"approved","comment":"деньги пришли"}'

Доступ и ключи

Ключ передаётся любым из двух заголовков; если пришли оба, читается X-API-Key:

Authorization: Bearer ВАШ_КЛЮЧ
# или
X-API-Key: ВАШ_КЛЮЧ

• нет ключа или ключ неверен - 401;
• за подключением закрепляется список разрешённых IP, запрос с чужого адреса - 403;
• ключ перевыпускаем по вашему запросу, старый перестаёт работать сразу. Храните ключ в секретах и меняйте без выката кода;
• секрет подписи вебхуков меняется в кабинете партнёра самостоятельно.

Подача чека

Отвечает сразу 202: задача создана, проверка идёт в фоне. Тот же 202 приходит и при отказе приёма - тогда в теле "status": "done", "verdict": "rejected" и код причины. Решение принимайте по телу, а не по коду HTTP.

Файлом (multipart/form-data)

Файл - в поле file, остальные поля - строками рядом.

curl -s https://chekvalidator.com/sandbox/v1/receipts:validate \
  -H "Authorization: Bearer sandbox-demo-key" \
  -F "file=@check.jpg" \
  -F "request_id=ORDER-1001" \
  -F "expected_amount=1500.00" \
  -F "requisite=79001234567" \
  -F "initiated_at=2026-08-23T10:15:00" \
  -F "partner_meta={\"order\":1001}"

Ссылкой (application/json)

Чек лежит в вашем хранилище - передайте временную ссылку, файл заберём сами.

curl -s https://chekvalidator.com/sandbox/v1/receipts:validate \
  -H "Authorization: Bearer sandbox-demo-key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://storage.example.com/tmp/check.jpg?sig=...",
    "request_id": "ORDER-1001",
    "expected_amount": "1500.00",
    "requisite": "79001234567",
    "initiated_at": "2026-08-23T10:15:00"
  }'

Поля заявки

Без любого из трёх обязательных полей подача отклоняется кодом CONTEXT_FIELDS_MISSING - и в бою, и в песочнице.

Ответ подачи

{
  "request_id": "ORDER-1001",
  "job_id": "3f8a1c2e-...",
  "status": "pending",
  "comment": "Чек принят, идёт проверка",
  "eta_seconds": 3.5,
  "status_url":  "https://.../v1/receipts/3f8a1c2e-...",
  "receipt_url": "https://.../v1/receipts/3f8a1c2e-.../file",
  "share_url":   "https://.../r/<токен>"
}

eta_seconds - через сколько ждать вердикт, status_url - где его забирать, receipt_url - файл чека по ключу, share_url - карточка проверки без ключа. Отказы по самому файлу при подаче файлом (UNSUPPORTED_FORMAT, FILE_TOO_LARGE, IMAGE_TOO_LARGE, CONTENT_TYPE_MISMATCH) приходят не здесь, а вердиктом задачи.

Ссылки загрузки

Заявка, по которой чек прикладывает сам плательщик. Поля заявки те же и так же обязательны; ttl_minutes - срок жизни ссылки, по умолчанию час, не больше суток.

curl -s https://chekvalidator.com/sandbox/v1/upload-links \
  -H "Authorization: Bearer sandbox-demo-key" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "ORDER-1002",
    "expected_amount": "900.00",
    "requisite": "79007654321",
    "initiated_at": "2026-08-23T12:00:00",
    "ttl_minutes": 60
  }'

# Ответ 201:
{
  "token": "kZ2r...",                                # непрозрачная строка, на формат не опирайтесь
  "upload_url":    "https://.../u/kZ2r...",          # страница загрузки для плательщика
  "embed_url":     "https://.../u/kZ2r...?embed=1",  # та же страница в iframe на вашем сайте
  "expires_at":    "2026-08-23T13:00:00",            # до этого момента ссылка ждёт чек
  "max_attempts":  3,                                # попыток загрузки на одну ссылку
  "email_address": "order-1002.a1b2c3@...",          # чек можно прислать письмом; null - канал выключен
  "status_url":    "https://.../v1/upload-links/kZ2r...",
  "receipt_url":   "https://.../v1/upload-links/kZ2r.../file"
}

Попытки кончились (max_attempts) - выпускайте новую ссылку.

Состояние заявки. status: pending - ссылка ждёт чек, done - проверка закончена, expired - срок вышел без чека, not_found - ссылки нет. Рядом: file_received, uploaded_at, attempts, expires_at, job_id, verdict, checking, eta_seconds, resend_deadline, resend_left_seconds и адреса status_url, receipt_url, share_url.

Чек по адресу заявки: 202 и waiting, пока чека нет, 202 и processing, пока идёт проверка, 410 - срок вышел без чека; дальше как у файла чека.

Повторные подачи

Повтор той же подачи с тем же request_id не создаёт новую задачу: вернётся та же job_id с "repeated": true и тем же 202 - ретраи по обрыву сети безопасны. Память о заявке держится сутки. Без request_id защиты от дублей нет.

{"request_id":"ORDER-1001","job_id":"3f8a1c2e-...","status":"done",
 "repeated":true,"verdict":"accepted",...}

Результат проверки

Ответ всегда 200, разбирайте по полю status: processing - ждите, done - готово, not_found - задачи нет, она чужая или старше суток. Результат доступен сутки, файл - столько, сколько выбрано в настройке хранения.

{
  "job_id": "3f8a1c2e-...",
  "request_id": "ORDER-1001",
  "status": "done",
  "status_key": "chist",
  "status_text": "Чист",
  "status_action": "Проводить платёж.",
  "status_explain": "Чек прошёл проверку: подделки не нашли, данные сошлись с заявкой.",
  "status_hex": "#1e8e5a",
  "warning": null,
  "file_delivery": "передаём",
  "file_delivery_reason": "",
  "verdict": "accepted",
  "reason_code": null,
  "status_color": "green",
  "comment": "Признаков подделки не найдено",
  "points": [],
  "mismatches": [],
  "extracted": {
    "amount": "1500.00",
    "payment_time": "2026-08-23T10:17:41",
    "bank": "...",
    "transfer_type": "..."
  },
  "file_available": true,
  "file_cropped": false,
  "partner_meta": "{\"order\":1001}"
}

Остальные служебные поля (например, authenticity) могут меняться - решение принимайте по полям выше.

Статусы и коды причин

Разбирайте ответ по status_key: он есть у каждой завершённой проверки, и у каждого значения ровно одно действие.

Если заключения нет вовсе, приходит neyasno.

Прежняя форма: verdict и status_color

Код, написанный по старым полям, работает как раньше. В прежней форме пять вердиктов:

Коды приёма файла

Приходят с verdict: rejected и status_key: prishlite_zanovo.

Коды «нужен новый чек»

Приходят с verdict: resend_requested; comment готов для плательщика.

Коды наших технических обстоятельств

Коды признаков подделки при rejected приходят, но открыто не расшифровываются: открытый список проверок был бы инструкцией для изготовителей подделок. Справочник входит в пакет подключения.

Файл чека

Файл по ключу API. Пока проверка идёт - 202 и processing; если она затянулась, файл может прийти раньше вердикта с заголовком X-Validator-Verdict: pending. Файла не будет (нужен новый чек, отказ, снят с хранения) - 409 с вердиктом и кодом; чужая задача - 404.

Снять чек с хранения досрочно. Ответ: {"job_id": "...", "stored": false, "deleted": true}.

Карточка без ключа - share_url вида /r/<токен>: в браузере это статус, заключение и сам чек, программе по тому же адресу приходит файл. Удобно для карточки операции в вашей админке. Ссылка равноценна документу: храните как секрет и не отдавайте плательщику. Живёт, пока чек на хранении. По настройке файл отдаётся очищенным от служебных полей (EXIF, GPS, метаданные PDF).

Вебхуки

Вердикт приходит сам на ваш адрес. Адрес задаётся в кабинете партнёра (только https и публичный адрес), секрет подписи выдаётся при подключении и меняется в кабинете.

# тело события: имя дублируется полем event и заголовком X-Validator-Event
{
  "event": "receipt.verdict",
  "job_id": "3f8a1c2e-...",
  "request_id": "ORDER-1001",
  "status": "done",
  "verdict": "accepted",
  "status_color": "green",
  "reason_code": null,
  "comment": "Признаков подделки не найдено",
  "points": [],
  "file_available": true,
  "status_url":  "https://.../v1/receipts/3f8a1c2e-...",
  "receipt_url": "https://.../v1/receipts/3f8a1c2e-.../file",
  "share_url":   "https://.../r/<токен>"
}
# у receipt.accepted вместо вердикта - "status": "pending" и comment;
# partner_meta едет в каждом событии, если вы его прислали

Подпись - проверять обязательно

Заголовок X-Validator-Signature - HMAC-SHA256 от сырого тела, ключ - ваш секрет, шестнадцатеричная строка в нижнем регистре. Считайте подпись до разбора JSON: пересобранное тело даёт другие байты. Нет заголовка или не сошлась - событие чужое.

# Python: проверка подписи
import hmac, hashlib

def подпись_верна(тело: bytes, заголовок: str, секрет: str) -> bool:
    ожидаемая = hmac.new(секрет.encode(), тело, hashlib.sha256).hexdigest()
    return hmac.compare_digest(ожидаемая, заголовок)

Доставка

• «Как минимум один раз»: сразу три попытки, затем очередь досылки через полминуты, 2, 10 и 30 минут, 2, 6 и 12 часов - в пределах суток. Очередь переживает перезапуски с обеих сторон.
• Повторы идут с тем же X-Validator-Event-Id: обрабатывайте идемпотентно и не откатывайте уже принятый вердикт.
• Успех - только ответ 2xx: отвечайте сразу, тяжёлую работу уводите в фон.
• Событий нет, если подача отклонена на приёме, получила 503 или это повтор ("repeated": true). При wait_seconds вердикт придёт и в ответе, и вебхуком.
• Окно кончилось или вебхук не дошёл - вердикт всегда можно забрать по status_url.

Приёмник по шагам

1. Прочитать сырое тело байтами и проверить подпись.
2. X-Validator-Event-Id уже видели - ответить 2xx и выйти.
3. Разобрать тело: event, job_id, request_id, partner_meta.
4. Записать событие и сразу ответить 2xx.
5. В фоне применить вердикт к сделке.

Итог ордера

Чем закончился ордер у вас - после вердикта, по любому статусу. Нужно для разбора спорных случаев и снятия блокировки «Повтор».

{"order_outcome": "approved", "comment": "деньги поступили"}
# order_outcome: approved | declined; comment - до 1000 символов, лишнее обрезаем

# Ответ: {"job_id": "...", "feedback": "recorded", "order_outcome": "approved"}
# 422 - order_outcome не approved и не declined
# 404 - по этой задаче у нас нет записанного решения

Ошибки HTTP

Формы тела ошибки: {"detail": "..."} у 401 и 403; {"error": "..."} у 422 и 404 итога ордера; обычный ответ подачи с verdict, reason_code, stage и detail у отказов приёма.

Служебные адреса и схема

Машинная схема всех маршрутов - openapi.yaml: её понимают Postman, Insomnia и генераторы клиентов. Собирается из кода, поэтому не расходится с сервисом. Та же схема в виде страницы Swagger с запросами в песочницу.

Подсистемы

Если за одним ключом стоят разные ваши системы (касса, бот, ручной разбор) и они по-разному умеют ждать, заведите их в кабинете («Интеграция» → «Подсистемы») и присылайте идентификатор полем subsystem - при подаче и при создании ссылки загрузки.

• латиница, цифры, дефис, подчёркивание, до 32 знаков; поле необязательное;
• незнакомый идентификатор подачу не рушит: чек идёт по умолчанию, в ответе subsystem_unknown: true;
• подсистема, которая не умеет ждать, промежуточного «пришлите заново» не получает: придёт один финальный вебхук - итог по новому чеку или ne_podtverzhdyon, когда вышел её предел ожидания. Это не отказ;
• в вебхуке оба статуса: subsystem_status и полный full_status_key; изменения настроек действуют на новые подачи.

Три срока - не перепутайте

Песочница

https://chekvalidator.com/sandbox - открытый двойник API для отладки: те же адреса, поля и строгость приёма, но подлинность не проверяется - вердикт выбирается по имени файла. Попробовать мышкой - в быстром старте.

• ключ - любая строка от 8 символов; ответы помечены заголовком X-Sandbox: true;
• вердикт созревает около 4 секунд: сначала processing, потом done;
• вебхуки включаются полем callback_url прямо в подаче - только здесь;
• данные живут около часа в памяти; настоящие чеки сюда не загружайте.

# сценарий «подделка»: подаём файл, вердикт забираем по status_url через ~4 секунды
curl -s https://chekvalidator.com/sandbox/v1/receipts:validate \
  -H "Authorization: Bearer sandbox-demo-key" \
  -F "file=@fake-check.jpg;filename=fake-check.jpg" \
  -F "request_id=TEST-FAKE-1" \
  -F "expected_amount=1500.00" \
  -F "requisite=79001234567" \
  -F "initiated_at=2026-09-01T10:15:00"

Переход в бой

В коде меняются две настройки - адрес и ключ. Приём одинаковый, различия осознанные:

Чек-лист перед выкатом

1. В каждой подаче есть expected_amount, requisite, initiated_at и request_id; повтор с "repeated": true не плодит дублей.
2. На каждый status_key есть ветка; жёлтый accepted не считается зелёным; «Пришлите заново» плательщик видит как просьбу, а не отказ.
3. Вебхуки: адрес в кабинете, секрет в секретах, подпись по сырому телу, повтор события безопасен, ответ быстрый.
4. Подача ссылкой - домен хранилища согласован; путь плательщика - решено, где показываете upload_url.
5. IP согласованы, срок хранения выбран, ключ в секретах и меняется без выката.
6. Наша недоступность не останавливает сделки: таймауты и повторы настроены.
7. Итог ордера уходит автоматически. В день перехода - один настоящий чек, вердикт пришёл и по status_url, и вебхуком с верной подписью.

Безопасность и данные

• Каждый файл чека шифруется при записи (AES-256-GCM); ключ живёт отдельно от данных и в резервные копии не попадает.
• Срок хранения файла - ваша настройка, от «не хранить» до бессрочно; снять чек досрочно - DELETE /v1/receipts/{job_id}/file. Рабочая запись задачи живёт около суток зашифрованной; запись о проверке без файла остаётся в журнале решений для разбора споров.
• Чеки боевых подключений хранятся в закрытом зашифрованном хранилище для разбора спорных случаев и повышения качества; тестовые подключения туда не попадают.
• Распознавание - внутри сервиса: во внешние нейросети и чужие API чек не уходит.
• Чужая задача для вашего ключа неотличима от несуществующей; share_url - как сам документ.
• Загрузка по ссылкам ограждена от SSRF; вебхуки подписаны HMAC-SHA256.

Изменения API

Изменения обратно совместимы: поля и значения только добавляются, старые сохраняют смысл.