Reportes, exportaciones y programaciones

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: Inventariar consultas, exportaciones grandes y reportes programados para la empresa.

Filtros comunes

from
to
timezone
payment_order_status
financial_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 del reporte. El rango temporal y la zona horaria deben aparecer en la respuesta.

En reportes asociados a Payment Orders, payment_order_status representa el lifecycle de la orden —por ejemplo open, confirmed, expired o cancelled— mientras financial_status conserva la dimensión financiera o de Reconciliation, por ejemplo late_detected, amount_difference o ambiguous. failed no es un terminal comercial público de Payment Order y no debe mezclarse con el lifecycle comercial. Los fallos técnicos pertenecen a la telemetría o infraestructura correspondiente.

payment_order_uid identifica la Payment Order dentro de YUPY y external_transaction_id mantiene la correlación comercial con el sistema origen. payment_method representa el medio solicitado. Cuando un reporte exponga información del instrumento resuelto por YUPY, esa dimensión es descriptiva y no implica que el caller la seleccione al crear un Web Checkout.

Reportes de consulta inmediata

Ejemplo: pagos tardíos

GET /v1/reports/late-payments?from=2026-07-01T00:00:00-05:00&to=2026-07-31T23:59:59-05:00&page=1&page_size=50

{
  "report_type": "late_payments",
  "period": {
    "from": "2026-07-01T00:00:00-05:00",
    "to": "2026-07-31T23:59:59-05:00",
    "timezone": "America/Lima"
  },
  "data": [
    {
          "payment_order_uid": "pay_01JXYZ",
          "external_transaction_id": "ORDER-10482",
          "payment_order_status": "expired",
          "financial_status": "late_detected",
          "expected_amount": "85.50",
          "detected_amount": "85.50",
          "closed_at": "2026-07-20T15:00:00-05:00",
          "detected_at": "2026-07-20T15:10:00-05:00"
        }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1
  },
  "request_id": "req_01JXYZ"
}

En este ejemplo la Payment Order ya estaba expired y cerrada cuando se detectó evidencia financiera posterior. financial_status = "late_detected" no reabre la Payment Order, no elimina closed_at y no vuelve a ocupar el Counter que fue liberado.

El antiguo reporte específico de opciones de pago se retira del catálogo activo. Esta página no inventa una ruta sustituta: el análisis por medio e instrumento utiliza las dimensiones payment_method y payment_instrument_type dentro de los reportes que las soporten.

Ejemplo: solicitar CSV

POST /v1/report-jobs
Idempotency-Key: 64d4fde2-a6d4-41a5-bb75-6a5f4fa94fa7

{
  "report_type": "late_payments",
  "format": "csv",
  "filters": {
    "from": "2026-07-01T00:00:00-05:00",
    "to": "2026-07-31T23:59:59-05:00"
  }
}

{
  "job_id": "rpt_01JXYZ",
  "status": "queued",
  "report_type": "late_payments",
  "format": "csv",
  "request_id": "req_01JXYZ"
}

Eventos de trabajos

report.queued
report.processing
report.ready
report.failed
report.cancelled

Reportes programados

Ejemplo: programación

{
  "report_type": "late_payments",
  "frequency": "hourly",
  "timezone": "America/Lima",
  "recipients": [
    {
      "channel": "email",
      "address": "operaciones@empresa.com"
    },
    {
      "channel": "whatsapp",
      "recipient_reference": "supervisor_norte"
    }
  ],
  "active": true
}

La frecuencia, horario, destinatarios y formatos se acuerdan con la empresa. La documentación no promete una frecuencia fija universal.

Errores principales

Changelog — Payment Order / API Engine

2026-08-09 — Payment Order / API Engine v1.0: el ejemplo de pagos tardíos pasó de yupy_transaction_id/ypt_... a payment_order_uid/pay_...; los filtros comunes separaron payment_order_status del financial_status y retiraron el antiguo operational_status; se incorporaron payment_order_uid y payment_instrument_type; se retiró del catálogo activo /v1/reports/payment-options sin inventar una ruta sustituta; y el ejemplo de pago tardío documentó closed_at, payment_order_status = expired y financial_status = late_detected sin reapertura ni reocupación del Counter. Los report jobs, exportaciones, eventos report.* y programaciones se preservaron.

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