Чек: receipt-v4 и статус

Основной сценарий v4 из двух шагов: отправить документ, затем опрашивать статус до результата.

Отправить документ

По HTTP добавьте базу контура и заголовок token, см. адреса. По TCP путь тот же, токен не нужен. Поля документа описаны отдельно.

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/receipt-v4' \
  -H 'token: <токен>' -H 'Content-Type: application/json' \
  -d '{
    "id": "07b2f33c-0eaf-4353-abbf-794654654654",
    "operation": "INCOME",
    "cashless": true,
    "products": [
      { "id": "456587988", "name": "Молоко", "price": 100.00, "quantity": 6.1,
        "vat_value": 12.0, "st_value": 1.0, "calcItemAttributeCode": "0" }
    ]
  }'

curl -X POST 'http://192.168.0.50:8090/gate/receipt-v4' \
  -H 'Content-Type: application/json' -H 'Expect:' \
  -d '{ … то же тело … }'

Ответ:

{ "id": "07b2f33c-0eaf-4353-abbf-794654654654", "status": "OK", "info": "Document accepted", "kkmID": "65f1234567890abcdef12345" }

Опросить статус

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/receipt-status-v4' \
  -H 'token: <токен>' -H 'Content-Type: application/json' \
  -d '{ "id": "07b2f33c-0eaf-4353-abbf-794654654654" }'

curl -X POST 'http://192.168.0.50:8090/gate/receipt-status-v4' \
  -H 'Content-Type: application/json' -H 'Expect:' \
  -d '{ "id": "07b2f33c-0eaf-4353-abbf-794654654654" }'

Ещё не готово:

{ "status": "PROCESSING", "info": "В процессе" }

Формат итогового ответа и значения статусов описаны в разделе ответ и статусы.

Сколько ждать

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

POST receipt-v4 (id, документ)
если ответ.status == ERROR:
    прервать, показать ответ.info

пока не истёк таймаут 3–5 минут:
    подождать 1–2 с
    POST receipt-status-v4 (id)
    если status == OK или PAID:  успех, сохранить qr и fdNumber
    если status == CANCELLED:    отменено на терминале
    если status == PROCESSING:   продолжить
    если status == ERROR:
        если info == "Request already working": продолжить
        иначе: неуспех, показать info

таймаут истёк:
    не считать документ непроведённым
    повторить receipt-status-v4 позже с тем же id

Повторы и обрывы связи

Главное правило: новый id для того же заказа создавать нельзя, это единственный способ получить двойной чек.

Результат по HTTP остаётся доступным и через сутки: сервер ищет чек в своей базе по id. По TCP результат живёт в памяти приложения, перезапуск его стирает.

Что ответит повтор

Эти ответы приходят со status: OK: документ уже известен, повторно он пробит не будет.