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
status
financial_status
operational_status
payment_method
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.

Reportes de consulta inmediata

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Reportes	`GET`	`/v1/reports/overview`	Resumen ejecutivo del periodo.	No	Ninguno
Reportes	`GET`	`/v1/reports/transactions`	Detalle de transacciones.	No	Ninguno
Reportes	`GET`	`/v1/reports/reconciliation`	Resultados de conciliación.	No	Ninguno
Reportes	`GET`	`/v1/reports/pending-cases`	Pendientes y antigüedad.	No	Ninguno
Reportes	`GET`	`/v1/reports/late-payments`	Pagos tardíos.	No	Ninguno
Reportes	`GET`	`/v1/reports/amount-differences`	Todas las diferencias.	No	Ninguno
Reportes	`GET`	`/v1/reports/underpayments`	Pagos incompletos.	No	Ninguno
Reportes	`GET`	`/v1/reports/overpayments`	Pagos en exceso.	No	Ninguno
Reportes	`GET`	`/v1/reports/ambiguous-payments`	Casos ambiguos.	No	Ninguno
Reportes	`GET`	`/v1/reports/cancelled-with-payment`	Canceladas con pago posterior.	No	Ninguno
Reportes	`GET`	`/v1/reports/evidence`	Constancias recibidas.	No	Ninguno
Reportes	`GET`	`/v1/reports/ocr`	Resultados y calidad OCR.	No	Ninguno
Reportes	`GET`	`/v1/reports/refunds`	Devoluciones y estados.	No	Ninguno
Reportes	`GET`	`/v1/reports/shifts`	Turnos.	No	Ninguno
Reportes	`GET`	`/v1/reports/users`	Actividad por usuario.	No	Ninguno
Reportes	`GET`	`/v1/reports/devices`	Actividad por dispositivo.	No	Ninguno
Reportes	`GET`	`/v1/reports/payment-options`	Uso de QR y transferencia.	No	Ninguno
Reportes	`GET`	`/v1/reports/checkout-sessions`	Sesiones y vencimientos.	No	Ninguno
Reportes	`GET`	`/v1/reports/deliveries`	Entregas conversacionales.	No	Ninguno
Reportes	`GET`	`/v1/reports/webhook-deliveries`	Callbacks enviados.	No	Ninguno
Reportes	`GET`	`/v1/reports/api-usage`	Consumo de API.	No	Ninguno
Reportes	`GET`	`/v1/reports/duplicate-detections`	Duplicados detectados.	No	Ninguno
Reportes	`GET`	`/v1/reports/confirmation-times`	Tiempos de confirmación.	No	Ninguno
Reportes	`GET`	`/v1/reports/claims`	Reclamos.	No	Ninguno
Reportes	`GET`	`/v1/reports/audit-log`	Auditoría cliente.	No	Ninguno
Reportes	`GET`	`/v1/reports/source-health`	Salud resumida de fuentes, sin secretos.	No	Ninguno

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": [
    {
      "yupy_transaction_id": "ypt_01JXYZ",
      "external_transaction_id": "ORDER-10482",
      "expected_amount": "85.50",
      "detected_amount": "85.50",
      "detected_at": "2026-07-20T15:10:00-05:00",
      "state": "late_detected"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1
  },
  "request_id": "req_01JXYZ"
}

Exportaciones grandes

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Reportes	`POST`	`/v1/report-jobs`	Solicitar exportación grande.	Obligatoria	report.queued
Reportes	`GET`	`/v1/report-jobs`	Listar trabajos.	No	Ninguno
Reportes	`GET`	`/v1/report-jobs/{job_id}`	Consultar estado.	No	Ninguno
Reportes	`GET`	`/v1/report-jobs/{job_id}/download`	Descargar archivo temporal.	No	Ninguno
Reportes	`POST`	`/v1/report-jobs/{job_id}/cancel`	Cancelar trabajo pendiente.	Obligatoria	report.cancelled

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

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Administración	`POST`	`/v1/report-schedules`	Crear programación.	Obligatoria	report_schedule.created
Administración	`GET`	`/v1/report-schedules`	Listar programaciones.	No	Ninguno
Administración	`GET`	`/v1/report-schedules/{id}`	Consultar programación.	No	Ninguno
Administración	`PATCH`	`/v1/report-schedules/{id}`	Modificar programación.	Obligatoria	report_schedule.updated
Administración	`DELETE`	`/v1/report-schedules/{id}`	Desactivar programación.	Obligatoria	report_schedule.deactivated
Administración	`POST`	`/v1/report-schedules/{id}/run`	Ejecutar ahora.	Obligatoria	report.queued
Administración	`GET`	`/v1/report-schedules/{id}/runs`	Consultar ejecuciones.	No	Ninguno

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

HTTP	Código	Descripción
422	`report_type_not_supported`	Tipo no disponible.
202	`report_not_ready`	Trabajo todavía en proceso.
410	`report_expired`	Descarga temporal vencida.
500	`report_generation_failed`	No pudo generarse.
422	`invalid_report_filter`	Filtro no válido para el reporte.

API Technical Docs