Reportes operativos

Estado documental: Contrato propuesto. Los tiempos, frecuencias y formatos definitivos dependen de la implementación y de la configuración contratada.

Objetivo operativo

La operación de YUPY debe permitir que la empresa conozca:

qué se cobró
qué se confirmó
qué sigue esperando
qué tiene diferencia
qué llegó tarde
qué es ambiguo
qué requiere evidencia
qué debe devolverse
quién debe actuar

Bandeja de pendientes

La empresa debe disponer de una vista central con:

payment_order_uid, identidad canónica YUPY de la Payment Order;
external_transaction_id, identidad comercial estable de la operación en el sistema origen;
tipo de caso;
estado;
monto esperado;
monto detectado;
diferencia;
usuario;
turno;
dispositivo;
canal;
fecha;
antigüedad;
evidencia;
acción requerida;
responsable;
última actualización.

Tipos principales

late_payment
amount_difference
underpayment
overpayment
ambiguous_payment
evidence_review
cancelled_order_with_payment
refund_required
delivery_failure
unresolved_payment
operational_error

Flujo del caso

Caso creado
    ↓
Alerta enviada
    ↓
Responsable asignado
    ↓
Caso revisado
    ↓
Evidencia solicitada o recibida
    ↓
Resolución registrada
    ↓
Auditoría y reporte

Asignación

Un pendiente puede asignarse a:

vendedor;
supervisor;
responsable del dispositivo;
administrador;
equipo operativo;
otro responsable configurado.

Alertas inmediatas

La empresa configura:

eventos que generan alertas;
destinatarios;
canal;
horario;
escalamiento;
frecuencia;
recordatorios;
nivel de prioridad.

Canales:

WhatsApp
correo electrónico
chat operativo
consola
webhook

Eventos que pueden alertar

pago confirmado;
pago tardío;
diferencia;
ambigüedad;
constancia recibida;
revisión requerida;
cancelación;
pago posterior a cancelación;
entrega fallida;
turno próximo a vencer;
turno cerrado;
devolución pendiente;
reporte listo;
webhook fallido.

Escalamiento

Caso creado
→ vendedor

Sin atención dentro del periodo configurado
→ supervisor

Caso crítico o vencido
→ administrador

Los tiempos exactos son configurables y no forman parte de una promesa universal.

Operación del vendedor

El vendedor puede acceder únicamente a la información necesaria para su turno, según permisos:

operaciones;
estados;
diferencias;
casos vinculados;
evidencia;
alertas;
cierre;
resumen operativo.

No obtiene automáticamente acceso a reportes generales ni administración.

Cierre de turno

El cierre puede producir un resumen con:

operaciones creadas;
pagos conciliados;
pendientes;
diferencias;
casos tardíos;
casos que requieren seguimiento.

Turno cerrado
≠ conciliación detenida
≠ pendientes eliminados
≠ ingresos ignorados

Reportes inmediatos

La empresa puede consultar:

overview
transactions
reconciliation
pending-cases
late-payments
amount-differences
underpayments
overpayments
ambiguous-payments
cancelled-with-payment
evidence
ocr
refunds
shifts
users
devices
checkout-sessions
deliveries
webhook-deliveries
api-usage
duplicate-detections
confirmation-times
claims
audit-log
source-health

source-health presenta una vista resumida del estado de las fuentes necesarias para operar, sin exponer credenciales, consultas privadas ni infraestructura interna.

Filtros

from
to
timezone
status
financial_status
operational_status
payment_order_uid
payment_method
payment_instrument_type
channel
user_id
shift_id
device_id
external_transaction_id
min_amount
max_amount
page
page_size
sort

Los filtros disponibles dependen de cada reporte.

Exportaciones grandes

Los reportes pequeños pueden responder inmediatamente. Las exportaciones grandes se gestionan como trabajos:

reporte solicitado
→ queued
→ processing
→ ready
→ descarga temporal

Formatos posibles:

CSV
XLSX
JSON
PDF, cuando corresponda

Los formatos definitivos dependen de la implementación.

Reportes programados

La empresa puede configurar:

tipo de reporte;
frecuencia;
periodo;
zona horaria;
destinatarios;
canal;
formato;
filtros;
horario.

{
  "report_type": "late_payments",
  "frequency": "daily",
  "timezone": "America/Lima",
  "recipients": [
    {
      "channel": "email",
      "address": "operaciones@empresa.com"
    }
  ]
}

Webhook de reporte listo

Este ejemplo utiliza el mismo sobre canónico de eventos:

{
  "event_id": "evt_01JREP",
  "event_type": "report.ready",
  "event_version": "1.0",
  "created_at": "2026-07-20T17:00:00-05:00",
  "data": {
    "job_id": "rpt_01JXYZ",
    "report_type": "late_payments",
    "format": "csv",
    "status": "ready"
  }
}

Auditoría operativa

Se registra:

creación;
asignación;
alerta;
reconocimiento;
nota;
evidencia;
resolución;
cambio de responsable;
exportación;
descarga;
cierre;
error;
reintento.

Criterios de aceptación

Existe bandeja de pendientes.
Cada caso tiene responsable y antigüedad.
Las alertas son configurables.
WhatsApp y correo pueden utilizarse.
El vendedor solo ve información operativa autorizada.
El cierre no detiene conciliaciones.
Existen reportes inmediatos y exportaciones.
Los reportes grandes son asíncronos.
Pueden programarse entregas.
Las acciones operativas quedan auditadas.

Dimensiones canónicas de Payment Order

Los reportes operativos deben correlacionar una operación de cobro mediante identidades con responsabilidades distintas. payment_order_uid es la identidad canónica que genera YUPY para la Payment Order; external_transaction_id conserva la identidad comercial estable del sistema origen. Ninguna de las dos sustituye a la otra.

external_transaction_id
        ↓ correlación comercial
payment_order_uid
        ↓ identidad YUPY
casos, eventos, conciliación y reportes

Los nombres de vistas o reportes históricos que utilicen la palabra “transactions” no redefinen la entidad de cobro: cuando una fila representa una operación de cobro YUPY, la entidad canónica es la Payment Order. La palabra “transacción” puede seguir utilizándose para una transacción financiera real u otros conceptos que no sean la identidad de la Payment Order.

Método e instrumento de pago

La dimensión de pago debe mantener separados payment_method y payment_instrument_type. En el flujo QR actual:

payment_method = "qr"
payment_instrument_type = "qr_bbva"

Yape y Plin son mecanismos que el pagador puede utilizar para pagar el QR BBVA. No deben presentarse en reporting como instrumentos concretos pares de qr_bbva. El antiguo concepto payment-options queda retirado del catálogo activo de reportes.

Claims, evidencia y confirmación financiera

Los reportes deben distinguir la evidencia operativa de la confirmación financiera. Una acción del vendedor, un claim del comprador, una foto/captura, OCR o payment.reported pueden producir seguimiento, evidencia o un caso de revisión, pero no confirman financieramente el pago por sí solos.

claim / foto / OCR / payment.reported
        ↓
verificación / Reconciliation
        ↓
payment.reconciled
        ↓
Payment Order = confirmed

Cuando Reconciliation normaliza evidencia suficiente, payment.reconciled representa confirmación financiera. Los reportes pueden entonces correlacionar el resultado con la Payment Order y, cuando esté disponible, con confirmed_at.

Cierre y evidencia tardía

Una Payment Order que termina comercialmente en confirmed, expired o cancelled registra su cierre y libera el Counter exclusivo. failed no es un cuarto terminal comercial público; los fallos técnicos se registran en la infraestructura correspondiente. Si después de una expiración o cancelación aparece evidencia financiera tardía, esta permanece vinculada a la Payment Order histórica para auditoría, revisión y reporting.

payment.late_detected no reabre la Payment Order original, no elimina su cierre y no vuelve a ocupar el Counter ya liberado. La resolución comercial posterior continúa siendo un proceso separado.

Changelog — Payment Order / API Engine

2026-08-09 — Payment Order / API Engine v1.0: se alinearon los reportes operativos con payment_order_uid y external_transaction_id; se retiró del catálogo activo el antiguo payment-options; se separaron payment_method y payment_instrument_type; se documentó qr + qr_bbva y la diferencia respecto de Yape/Plin; se distinguieron claims/evidencia de payment.reconciled; y se preservó que la evidencia financiera tardía permanece asociada a la Payment Order histórica sin reabrirla ni reocupar su Counter.

Exposición externa: el callback payment_order.terminal usa pagado | cancelado | timeout.

API Technical Docs