Запись чека (нормативная)

5.3 Запись чека (нормативная)

Запись чека в том виде, в каком её возвращает собственный API приложения (чтения с сессионной аутентификацией под /api/receipts). Показанные имена полей репрезентативны для хранимой записи.

json

// Receipt
{
  "receipt_id": "6f2b8c1e-4a7d-4f2b-9c41-0e5d8a3b7f10",
  "user": "yumo_user",
  "uploaded_at": "2026-05-17T14:23:11Z",
  "receipt_date": "2026-05-17",
  "currency": "TRY",
  "merchant": {
    "merchant_id": "f3b1c2d4-...",
    "display_name": "Migros",
    "city": "Istanbul",
    "tax_id": "6200278131"
  },
  "totals": {
    "subtotal": "234.50",
    "tax_total": "42.21",
    "grand_total": "276.71",
    "currency": "TRY"
  },
  "tax_lines": [
    { "rate_pct": 18.0, "base": "200.00", "amount": "36.00" },
    { "rate_pct": 8.0,  "base": "77.50",  "amount": "6.20"  }
  ],
  "payment_method": "credit_card",
  "document_type": "receipt",
  "is_payment_proof": true,
  "line_items": [
    {
      "raw_text": "SUT 1L PINAR",
      "canonical_product_id": "3f6a...-...",
      "qty": 2.0,
      "unit_price": "23.50",
      "line_total": "47.00",
      "tax_rate_pct": 8.0,
      "match_confidence": "0.XX"
    }
  ],
  "pipeline": {
    "document_reader_class": "receipt_ocr",
    "ocr_confidence": "0.XX",
    "extraction_route_class": "structured_receipt",
    "extraction_confidence": "0.XX",
    "rules_confidence": "0.XX",
    "self_consistency_check": false
  },
  "trust": {
    "score": "0.XX",
    "band": "<band>",
    "signals_present": ["total_reconciliation", "merchant_consistency"]
  },
  "rewards": {
    "bint_credited": "125.00",
    "reward_epoch": null
  },
  "status": "verified",
  "proof_status": null,
  "linked_receipt_id": null
}

Значения достоверности и оценка доверия показаны как заполнители. Производственные диапазоны, границы полос и веса сигналов управляются во внутреннем операционном слое.

Соглашения о полях

Соглашение	Правило
ID	UUID в качестве первичных ключей для чеков и торговцев; серийные целочисленные id в таблицах событий и реестра.
Суммы в валюте	Десятичные значения, сериализуемые как канонические десятичные строки (2 знака после запятой для денег).
Метки времени	ISO 8601 с суффиксом `Z`. Всегда UTC.
Хэши	Шестнадцатеричные символы в нижнем регистре, алгоритм именуется контекстом поля.
Nullable	Отсутствующие поля используют явный `null`.
Перечисление статусов	`verified`, `saved`, `analyzed`.

Статусы и обработка доказательства оплаты

Действующие значения статуса:

analyzed  — выход конвейера получен, запись ещё не сохранена как удержанная
saved     — сохранена пользователем
verified  — прошла ворота верификации; пригодна для вознаграждений и агрегированного слоя

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

Поток ручной проверки для пограничных случаев запланирован; он не входит в действующий набор статусов.

Чек verified зарабатывает bINT. Агрегированная обработка неверифицированных записей следует правилам 5.8.