Проверка подлинности чеков - API

Валидатор встраивается в платёжную систему как микросервис и отвечает вердиктом - настоящий чек, поддельный или нужен повторный снимок. Чек он принимает сам: обычно плательщик прикладывает файл напрямую нам - по ссылке, рамкой на вашем сайте или письмом, - и через вашу систему файл не проходит вовсе. Если чек уже у вас, отдайте его одним запросом. Один REST-интерфейс, вердикт с человекочитаемым пояснением, колбэки с подписью.

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

Путей приёма два, и выбираете их вы. Основной - чек приносит плательщик: он прикладывает файл прямо Валидатору, а вы файла не касаетесь вовсе. Второй - чек отдаёте вы одним запросом, когда файл уже лежит у вас. Дальше пути сходятся в одно: та же проверка, те же вердикты, те же колбэки и та же карточка чека.

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

Ваш сервер файл не принимает, не хранит и не пересылает: вы просите у нас адрес под заявку и показываете его плательщику. Своя форма загрузки и своё место под чужие чеки не нужны.

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

Когда выбирают этот путь. Плательщик сидит в мессенджере, в чате поддержки или у оператора, и формы для файла у вас нет; вы не хотите принимать и хранить чужие чеки у себя; интеграцию надо собрать за день - с вашей стороны это один запрос и показ ссылки.

Путь 2 - чек отдаёте вы одним запросом

Файл уже у вас: плательщик приложил его в вашей форме или он лежит в вашем хранилище.

1. Плательщик приложил чек к заявке в вашей системе - фото, снимок экрана или PDF.
2. Вы отдаёте чек Валидатору одним запросом POST /v1/receipts:validate: файл плюс ожидаемая сумма и реквизит; вместо файла можно прислать временную ссылку на ваше хранилище. Ответ приходит сразу - задача принята, ссылки на статус и файл уже в нём. Подача чека »
3. Проверка идёт в фоне - выполняется асинхронно, ваша сделка стоит в ожидании, клиент ничего не перезагружает. Нужен ответ одним запросом - попросите подождать вердикт прямо в подаче полем wait_seconds.
4. Вердикт приходит колбэком (или вы забираете его запросом статуса GET /v1/receipts/{job_id}): accepted - признаков подделки не найдено; resend_requested - заключения по этому файлу нет, нужен новый чек; rejected - чек не принят. Редкий четвёртый исход - unverified, разбор ниже.
5. Вы сообщаете итог ордера обратной связью - она нужна для сверки качества и разбора спорных случаев.

Когда выбирают этот путь. Своя форма загрузки уже есть и менять её не хотят; чек приходит вам не от человека, а другой системой; нужен синхронный фильтр - вердикт прямо в ответе подачи по wait_seconds; чек надо проверить задним числом, из архива.

Варианты встраивания

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

Файл чека может попасть к нам пятью путями - все они сходятся в одну и ту же проверку, с теми же вердиктами и колбэками:

Интерфейсы: что видят люди

API - не единственная поверхность продукта. Ниже - четыре готовых экрана, которые достаются вам без разработки. Макеты схематичны, данные выдуманы.

Облачное хранилище чеков

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

Как устроено шифрование хранения

• Каждый файл чека шифруется при записи - алгоритм AES-256-GCM, тот же класс защиты, что у банковских систем. Шифруется файл в архиве, файл в рабочей записи задачи и образцы обучающей базы.
• Ключ шифрования живёт отдельно от данных и в резервные копии не попадает намеренно: архив чеков и обучающая база без ключа не читаются. Диск или копия, оказавшиеся в чужих руках, самих чеков не раскрывают.
• Файлы не покидают контур: распознавание - локальная нейросеть внутри сервиса, во внешние нейросети, облачные распознаватели и чужие API чек не уходит.
• Доступ - только по вашему ключу API или по ссылке: чужая задача для вашего ключа неотличима от несуществующей, а share_url непрозрачен и подделке не поддаётся.
• Честная граница: шифруются файлы. Служебная запись о проверке - вердикт и сверенные значения, без файла - живёт в журнале решений открытой: без неё нельзя разобрать спорный случай.

Границы честно: хранилище - для чеков, прошедших через проверку, произвольные файлы оно не принимает. Что остаётся после нулевого срока и зачем - в разделе «Безопасность и данные».

Путь внедрения - от ключа до боевого режима

Семь шагов по порядку. У каждого есть проверяемый результат: пока он не получен, следующий шаг делать рано. Ссылка в шаге ведёт в раздел, где то же самое разобрано подробно и показано примером - справочник ниже читается уже по надобности, а не подряд.

1. Ключ и адреса
   Подключение оформляем мы: выдаём ключ API, боевой адрес и интеграционный пакет (резервный блок для вашей страницы, закрытый справочник кодов). Тем же разговором согласуются четыре вещи, которые потом меняются дольше кода: список ваших исходящих IP, срок хранения чеков, домен вашего хранилища (если чек будете отдавать ссылкой) и секрет подписи колбэков. Сам адрес колбэков вы задаёте себе в кабинете партнёра, без нас. Ключ передаётся заголовком, храните его в секретах.
   Готово, когда: ключ лежит в секретах вашего стенда, боевой адрес записан в настройки отдельным значением - не в коде. Авторизация »
2. Песочница вместо ожидания
   Ждать ключ не нужно: интеграция собирается на песочнице https://validator.testoporat.com/sandbox - те же адреса и те же имена полей, ключом служит любая строка от 8 символов. Настоящие чеки туда не загружайте, она открыта.
   Готово, когда: ваш код ходит в песочницу и получает от неё ответы. Песочница »
3. Первый чек
   Один запрос POST /v1/receipts:validate: файл плюс поля заявки. Ответ приходит сразу - 202, задача создана, в теле job_id и адреса статуса, файла и карточки. Всегда передавайте request_id: он включает защиту от дублей, и повтор запроса по обрыву сети не заводит вторую задачу. Если у вас путь плательщика, первый чек идёт так же, только заявка заводится запросом POST /v1/upload-links, а файл прикладываете вы сами - открыв выданный upload_url вместо плательщика.
   Готово, когда: в ответе есть job_id, а повторная отправка того же запроса возвращает его же с пометкой "repeated": true. Три запроса подряд » · Подача файлом » · Ссылки загрузки »
4. Вердикт
   Проверка идёт в фоне, результат забирается по status_url: пока "status":"processing" - ждите, при "status":"done" разбирайте вердикт. Вердиктов четыре, и обработаны должны быть все четыре, а у accepted ещё и status_color: жёлтый значит «чек подлинный, но данные разошлись с заявкой», а не «всё сошлось». На пути плательщика тот же вердикт забирается по адресу заявки - GET /v1/upload-links/{token}, отдельного опроса задачи не нужно.
   Готово, когда: в вашей системе есть ветка на каждый вердикт и на жёлтый цвет. Получение результата » · Что делать с каждым вердиктом »
5. Колбэки вместо опроса
   Опрос статуса нужен только на время сборки. В бою вердикт приходит сам: адрес регистрируется в кабинете партнёра, секрет подписи выдаётся при подключении. Подпись проверяйте всегда и по сырому телу запроса - непроверенная подпись означает, что вердикт вам может прислать кто угодно.
   Готово, когда: событие с чужой подписью ваш приёмник отвергает, повторная доставка того же события ничего не ломает, ответ уходит быстрее секунды. Колбэки » · Порядок обработки »
6. Обратная связь по итогу ордера
   Чем закончилась сделка, знаете только вы. Один запрос после вердикта - и спорный случай потом можно разобрать по фактам, а не по памяти.
   Готово, когда: итог ордера уходит нам автоматически, а не руками оператора. Обратная связь »
7. Переход на боевой контур
   Меняются ровно две вещи - адрес и ключ. Но боевой контур строже песочницы: он требует обязательные поля заявки и по-настоящему проверяет подлинность. Сверьтесь с таблицей различий и пройдите чек-лист до выката, а не после.
   Готово, когда: адрес и ключ песочницы в боевой конфигурации не встречаются ни разу, чек-лист пройден целиком. Различия песочницы и боя » · Чек-лист внедрения »

Быстрый старт - три запроса в песочницу

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

# 1. Подать чек (файлом)
curl -s https://validator.testoporat.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://validator.testoporat.com/sandbox/v1/receipts/<job_id> \
  -H "Authorization: Bearer sandbox-demo-key"

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

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

Авторизация

Ключ API выдаётся на подключение (у нас это называется «партнёр»). Передавайте его любым из двух заголовков - подойдёт любой, а если пришли оба, читается X-API-Key:

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

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

Подача чека

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

Способ 1 - файл телом запроса (multipart/form-data)

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

curl -s https://validator.testoporat.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}"

Способ 2 - временная ссылка (application/json)

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

curl -s https://validator.testoporat.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"
  }'

Поля заявки

Ответ подачи

{
  "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 - файл чека (по ключу API): пока идёт проверка отвечает 202 со статусом processing, потом отдаёт файл;
• share_url - ссылка на карточку проверки без ключа API;
• partner_meta возвращается тем же ответом, если вы его прислали.

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

Пока проверка идёт - "status":"processing". Когда закончена - "status":"done" и полный вердикт. Третье состояние - "status":"not_found": такой задачи нет, она чужая или ей больше суток (результат доступен по status_url сутки с момента подачи, сам файл чека живёт столько, сколько попросил партнёр). Ответ всегда 200 - разбирайте по полю status:

{
  "job_id": "3f8a1c2e-...",
  "request_id": "ORDER-1001",
  "status": "done",
  "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}"
}

Рядом едут служебные поля (отпечаток файла, длительность проверки и другие) - их состав может меняться, опирайтесь на перечисленные ниже. Блок extracted приходит только тогда, когда из чека удалось что-то извлечь.

Вердикты и коды причин

Что делать с каждым вердиктом

Та же четвёрка, но со стороны вашего процесса: что происходит со сделкой, что видит плательщик и есть ли у вас файл чека. Столбец «что видит плательщик» - про ваш экран; на пути плательщика просьбу прислать чек заново он уже увидел на нашей странице, и ваше дело - дождаться нового файла. Обратная связь по итогу ордера отправляется при любом вердикте - это единственное действие, одинаковое для всех.

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

Отказ приёма приходит обычным ответом подачи со status: "done", вердиктом rejected и машинным кодом.

Коды причин: нужен новый чек (resend_requested)

Файл не удалось прочитать или чек из него не выделить. Поле comment уже сформулировано человеческим языком - его можно показывать как есть.

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

Сюда попадают случаи, когда проверку не удалось довести до конца. Сделка из-за этого стоять не должна: часть таких чеков доставляется по ссылкам и без заключения - смотрите поле file_available.

Повторные подачи - защита от дублей

Сетевые ретраи безопасны: повтор той же подачи не создаёт новую задачу - вернётся та же job_id с пометкой "repeated": true и тем же 202. Пока проверка идёт, ответ повтора приходит со "status":"pending" и без вердикта; когда готова - со "status":"done", verdict и reason_code, а полный результат забирается по status_url. Память о поданной заявке держится сутки, как и сам результат. Без request_id защиты от дублей нет.

# повторная отправка того же запроса по обрыву сети - безопасна
{"request_id":"ORDER-1001","job_id":"3f8a1c2e-...","status":"done",
 "repeated":true,"verdict":"accepted",...}

Файл чека и ссылки

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

Срок хранения файла - настройка партнёра: от «не хранить вовсе» до бессрочно. По той же настройке чек может сниматься с хранения сразу после того, как вы забрали его по ключу API - тогда повторный запрос того же файла ответит 409 или 404. Открытие share_url выдачей партнёру не считается и файл не снимает.

Снять чек с хранения самим: вы забрали файл к себе или обязаны удалить его по требованию плательщика. Ответ - {"job_id": "...", "stored": false, "deleted": true}.

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

Колбэки - вердикт сам приходит к вам

Вместо опроса статуса подключите колбэки: сервис сам пришлёт события на ваш адрес. Адрес колбэков вы задаёте в кабинете партнёра - принимается только 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 от тела запроса, ключ - ваш секрет колбэков. Непроверенная подпись означает, что вердикт вам может прислать кто угодно.

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

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

Подписывается сырое тело запроса в том виде, в каком оно пришло: считайте подпись ДО разбора JSON - пересобранное тело даёт другие байты, и подпись не сойдётся. Подпись - шестнадцатеричная строка в нижнем регистре; событие без заголовка подписи считайте чужим.

Доставка

Доставка «как минимум один раз», в два круга. Сразу - три попытки с паузами в секунды: это переживает моргание сети. Если приёмник не ответил, событие ложится в очередь досылки и повторяется с растущими паузами - через полминуты, две минуты, десять, полчаса, два часа, шесть, двенадцать, - пока не кончится окно доставки в сутки. Выкат новой версии вашего приёмника или перезагрузка сервера событие больше не теряют: поднявшись, вы получите всё накопленное. Очередь живёт в базе, поэтому переживает и наш перезапуск.

• повторы приходят с тем же X-Validator-Event-Id - заголовок не меняется между попытками и досылками. Обрабатывайте события идемпотентно: сверяйте этот идентификатор (или пару job_id + event) и не откатывайте уже принятый вердикт;
• окно кончилось - мы перестаём стучаться и помечаем событие просроченным у себя; вердикт в любой момент забирается по status_url, он никуда не девается;
• успехом считается только ответ 2xx: отвечайте быстро, тяжёлую обработку уводите в фон;
• колбэков не будет вовсе, если подача отклонена на приёме или сервис ответил 503 - ответ приходит сразу в самом запросе; повторная подача той же заявки ("repeated": true) событий заново не шлёт;
• при подаче с wait_seconds вердикт возвращается прямо в ответе, но колбэки всё равно придут - будьте готовы получить вердикт дважды.

Приёмник колбэка - порядок действий

Порядок именно такой: каждый следующий шаг опирается на предыдущий.

1. Прочитать сырое тело запроса байтами и проверить по нему подпись из X-Validator-Signature. До разбора JSON: пересобранное тело даёт другие байты, и подпись не сойдётся. Подпись не сошлась или заголовка нет - событие чужое, дальше не идём.
2. Посмотреть X-Validator-Event-Id: это событие уже обрабатывали - ответить 2xx и выйти. Доставка «как минимум один раз», повторы приходят с тем же идентификатором, и защита от повтора - на вашей стороне.
3. Разобрать тело: event говорит, что случилось, job_id и request_id - по какой заявке, partner_meta вернётся тем же, что вы прислали.
4. Записать событие у себя и сразу ответить 2xx. Тяжёлую работу - в фон: успехом считается только быстрый ответ, медленный приёмник ловит повторные доставки на ровном месте.
5. Уже в фоне применить вердикт к сделке. Принятый вердикт назад не откатывать: более позднее событие того же типа - это повтор, а не новое решение.

Что делать, если колбэк не пришёл вовсе: вердикт никуда не девается и в любой момент забирается по status_url. Опрос статуса - штатный запасной путь, а не поломка.

Ссылки загрузки - чек без вашей формы

Если вам неоткуда взять файл (клиент в мессенджере, у оператора нет формы) - создайте ссылку загрузки: плательщик открывает её и прикладывает чек прямо нам, дальше всё идёт обычным путём - с вердиктом, статусом и колбэками. Поля заявки те же и так же обязательны; ttl_minutes задаёт срок жизни ссылки - по умолчанию час, не больше суток.

curl -s https://validator.testoporat.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, если срок ссылки вышел, а чек так и не пришёл; дальше - как у обычной ссылки на файл чека.

Обратная связь - итог ордера

Сообщите, чем закончился ордер на вашей стороне: это нужно для сверки качества и разбора спорных случаев. Обратная связь отправляется после вердикта - по задаче, о которой у нас есть записанное решение.

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

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

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

Интерактивная схема API - все маршруты с полями, телами и кодами ответов; кнопка «Try it out» выполняет запросы в песочнице, а не в бою. Та же схема файлом: openapi.yaml - её понимают Swagger, Postman, Insomnia и генераторы клиентов, так что готовый код для своего языка получается без переписывания примеров руками. Файл собирается из кода при каждой сборке, поэтому не расходится с тем, что сервис делает на самом деле.

Ошибки и статусы HTTP

Форм тела ошибки три, разборщик должен знать все:

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

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

Песочница

Открыть песочницу »

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

• Ключ - любая строка от 8 символов: Authorization: Bearer sandbox-demo-key;
• вердикт «созревает» через ~4 секунды после подачи: сначала processing, потом done;
• коды SANDBOX_* существуют только здесь;
• данные держатся в памяти около часа и не сохраняются; не загружайте настоящие чеки - песочница для синтетики;
• ответы помечены заголовком X-Sandbox: true;
• колбэки в песочнице включаются полем callback_url прямо в подаче - это удобство отладки, только здесь. В боевом контуре такого поля нет: адрес колбэков задаётся один раз в кабинете партнёра;
• боевой контур строже: он требует обязательные поля заявки и умеет wait_seconds, а песочница - нет. Адрес песочницы и её ключи в боевой конфигурации быть не должны: она открыта, и её подписи ничего не доказывают.

# сценарий «подделка»: подаём файл, вердикт забираем по status_url через ~4 секунды
curl -s https://validator.testoporat.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"

Переход на боевой контур

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

Что сделать в день перехода: переключить адрес и ключ значениями настроек (без выката кода), прогнать на боевом контуре один настоящий чек и убедиться, что вердикт дошёл обоими путями - и по status_url, и колбэком с верной подписью. Дальше - чек-лист внедрения целиком.

Чек-лист внедрения

1. Заявка полная: expected_amount, requisite и initiated_at уходят всегда - без любого из них боевой контур подачу отклоняет.
2. Транспорт: путь приёма выбран и отработан в песочнице. Подача файлом - обычный multipart. Подача ссылкой согласована с нами заранее: домен вашего хранилища вносится в список разрешённых, иначе придёт FETCH_DISABLED или DOMAIN_NOT_ALLOWED. Путь плательщика - решено, где показываете upload_url (страница, рамка или письмо), а срок жизни ссылки и число попыток выставлены в кабинете под ваши сделки.
3. request_id передаётся всегда; ретраи по обрыву сети не плодят у вас дублей (проверьте обработку "repeated": true).
4. Все четыре вердикта обработаны, а у accepted разобран и status_color: жёлтый - это расхождение с заявкой, а не «всё сошлось». На resend_requested плательщик видит просьбу прислать чек заново, а не «отказ».
5. Колбэки: адрес зарегистрирован в кабинете, секрет подписи получен и хранится в секретах, подпись проверяется по сырому телу, повторная доставка события безопасна, ответ быстрый.
6. Список ваших исходящих IP согласован с нами, срок хранения чеков выбран.
7. Падение и недоступность Валидатора не останавливают ваши сделки: таймауты и повторы настроены.
8. Обратная связь по итогу ордера отправляется после вердикта.
9. Ключ хранится в секретах, не в коде; на смену ключа ваша система способна без выката.

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

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