Evidencias, OCR, reclamos y pendientes

Estado documental: Contrato propuesto. Las rutas, campos, límites y tiempos pasan a estado confirmado solo después de su implementación y verificación.

Objetivo: Documentar la carga de constancias, OCR, reclamos del comprador y resolución de casos pendientes.

Evidencia y OCR

Ejemplo: subir constancia

POST /v1/payment-orders/ypt_01JXYZ/evidence
Authorization: Bearer <ACCESS_TOKEN>
Idempotency-Key: 8e0752b4-217e-4754-a57f-dabf83cc5b32
Content-Type: multipart/form-data

file=@payment-proof.jpg
evidence_type=payment_receipt
reported_by=seller
shift_id=shf_01JXYZ
device_id=dev_01JXYZ

{
  "result": "evidence_received",
  "evidence_id": "evi_01JXYZ",
  "payment_reported": true,
  "ocr": {
    "status": "queued"
  },
  "request_id": "req_01JXYZ"
}

Ejemplo: resultado OCR

{
  "evidence_id": "evi_01JXYZ",
  "status": "processed",
  "extracted": {
    "amount": "80.00",
    "currency": "PEN",
    "payment_method_candidate": "yape",
    "paid_at_candidate": "2026-07-20T14:37:00-05:00",
    "operation_reference_candidate": "12345678",
    "recipient_candidate": "EMPRESA EJEMPLO"
  },
  "confidence": {
    "amount": 0.98,
    "paid_at": 0.89
  },
  "request_id": "req_01JXYZ"
}

OCR aporta evidencia complementaria. No confirma por sí solo que el dinero llegó.

Estados OCR

queued
processing
processed
partial
unreadable
rejected
failed

Reclamos públicos protegidos

Ejemplo: crear reclamo

{
  "transaction_code": "YP-7H2K9",
  "reason": "payment_not_confirmed",
  "buyer_name": "María Ramos",
  "contact": {
    "channel": "email",
    "value": "maria@example.com"
  }
}

{
  "claim_token": "<OPAQUE_CLAIM_TOKEN>",
  "claim_status": "created",
  "request_id": "req_01JXYZ"
}

Este flujo debe usar rate limiting, controles antiabuso, token opaco y exposición mínima de datos.

Gestión de reclamos por la empresa

Casos pendientes

Tipos principales:

late_payment
amount_difference
underpayment
overpayment
ambiguous_payment
evidence_review
cancelled_order_with_payment
refund_required
delivery_failure
unresolved_payment
operational_error

Ejemplo: resolver un caso

POST /v1/pending-cases/case_01JXYZ/resolve

{
  "resolution": "accept_late_payment",
  "reason": "La empresa confirmó que la venta continúa vigente.",
  "evidence_ids": [
    "evi_01JXYZ"
  ]
}

{
  "case_id": "case_01JXYZ",
  "status": "resolved",
  "resolved_at": "2026-07-20T16:30:00-05:00",
  "request_id": "req_01JXYZ"
}

Resoluciones permitidas

confirm_reconciliation
maintain_pending
request_more_evidence
mark_unresolved
accept_late_payment
reject_commercial_operation
create_supplemental_order
create_refund_case
close_without_financial_match

Errores principales