Документация API: чек в JSON за четыре запроса

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

Самый экономный формат — multipart/form-data. Один чек может состоять из нескольких файлов — например, длинная лента, снятая в три кадра: передайте их несколькими полями files[] в правильном порядке.

curl https://api.getnowhere.ru/v1/receipts \
  -H "Authorization: Bearer nw_live_••••••••" \
  -H "Idempotency-Key: order-4417" \
  -F "files[]=@receipt.jpg" \
	-F "external_id=order-4417" \
	-F "mode=default"

Ответ приходит сразу с кодом 202: задача принята, но ещё не выполнена.

{
  "data": {
    "id": "rcpt_01M085N5YV65EY5GAXCPTYZ65X",
    "status": "queued",
    "external_id": "order-4417",
	"test_mode": false,
	"mode": "default",
    "created_at": "2026-08-17T15:28:18.890Z"
  }
}

Дальше опрашивайте задачу по её идентификатору или дождитесь вебхука receipt.succeeded.

curl https://api.getnowhere.ru/v1/receipts/rcpt_01M085N5YV65EY5GAXCPTYZ65X \
  -H "Authorization: Bearer nw_live_••••••••"

Форматы и настройки

Если клиенту удобнее одно JSON-тело, тот же POST /v1/receipts принимает массив files. Элементом может быть чистая base64-строка или объект с data, filename и необязательным content_type. Поддерживаются и data URL. Формат изображения всё равно проверяется по байтам, а не по заявленному MIME-типу.

curl https://api.getnowhere.ru/v1/receipts \
  -H "Authorization: Bearer nw_live_••••••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4417" \
  --data '{
    "files": [{
      "data": "data:image/jpeg;base64,/9j/4AAQSkZJRg…",
      "filename": "receipt.jpg"
    }],
    "external_id": "order-4417",
    "country": "RU",
    "retention": "none",
    "mode": "fast"
  }'

Base64 увеличивает тело примерно на треть, поэтому для больших изображений лучше multipart. fast обычно быстрее, но на сложных длинных чеках может быть менее точным; для финансового контура оставляйте default.

Аутентификация

Ключ передаётся заголовком Authorization: Bearer nw_live_…. Другие способы не поддерживаются намеренно: ключ в строке запроса оседает в логах прокси, в истории браузера и в заголовке Referer, откуда его уже не отозвать.

Ключи бывают двух видов. nw_live_ запускает распознавание и расходует операцию по тарифу. nw_test_ проходит ту же очередь и отправляет те же вебхуки, но возвращает фиксированный sandbox-чек без вызова модели и списания — на нём удобно держать CI.

Полный ключ показывается один раз, при создании. Мы храним только его хеш и последние четыре символа для опознания в кабинете, поэтому восстановить утерянный ключ невозможно — только выпустить новый.

Статусы задачи

Распознавание асинхронное: задача проходит от queued до одного из двух конечных состояний.

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

Справочник

Ошибки

Любая ошибка приходит в одном и том же виде: код, человекочитаемое сообщение и идентификатор запроса. Указав requestId в обращении в поддержку, вы даёте нам точную строку лога.

{
  "code": "UNAUTHORIZED",
  "message": "invalid api key",
  "requestId": "0f5d9a87-af51-4078-be30-fc8b0f3c79e2"
}

Хранение данных

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

Разобранный результат хранится отдельно и по своему сроку: тот, кто просит не хранить изображения, обычно всё ещё хочет перечитать вчерашний JSON. Оба срока настраиваются в проекте: none, 7d или 30d.

Удалить результат раньше срока можно запросом DELETE /v1/receipts/{id}. Сама задача останется в журнале обращений — со статусом, временем и списанием, но без данных чека.