Biblioteca API: índice y convenciones

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: Servir como portada y mapa completo de las interfaces que una empresa cliente puede integrar o administrar.

Alcance de esta biblioteca

Esta biblioteca documenta únicamente interfaces destinadas a:

los sistemas de la empresa;
los administradores autorizados de la empresa;
el Web Checkout temporal del comprador;
los canales de POS vía chat;
los ambientes de sandbox y certificación.

Exclusión deliberada: no se publican conectores bancarios, consultas directas a cuentas, procesos internos de conciliación, colas, servicios internos de OCR ni rutas privadas de infraestructura.

Superficies documentadas

API de integración server-to-server
API administrativa para la empresa
Superficie temporal de Web Checkout
Superficie pública protegida para reclamos
Recepción de webhooks
Sandbox y certificación
Reportes y exportaciones
Referencia y OpenAPI

Audiencias

Etiqueta	Audiencia	Autenticación típica
Integración	Backend del sistema de la empresa	Bearer Token
Administración	Consola y administradores autorizados	Sesión o token con permisos administrativos
Checkout temporal	Comprador	Token opaco y temporal
Público protegido	Comprador con código o token de seguimiento	Token limitado, rate limiting y controles antiabuso
Sandbox	Equipo de integración	Credencial exclusiva de sandbox

Base URL

Mientras el dominio final no esté implementado y verificado, los ejemplos utilizan:

<YUPY_API_BASE_URL>

Headers comunes propuestos

Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json
Content-Type: application/json
Idempotency-Key: <UUID>

Idempotency-Key se utiliza en creaciones y mutaciones reintentables. No es necesario para consultas GET.

Respuesta de éxito común

{
  "result": "created",
  "request_id": "req_01JXYZ",
  "data": {
    "...": "..."
  }
}

Respuesta de error común

{
  "error": {
    "code": "validation_error",
    "message": "La solicitud contiene datos inválidos.",
    "fields": {
      "amount": "required"
    },
    "retryable": false,
    "request_id": "req_01JXYZ"
  }
}

Paginación propuesta

GET /v1/payment-orders?page=1&page_size=50

{
  "data": [],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 0,
    "total_pages": 0
  },
  "request_id": "req_01JXYZ"
}

Fechas, horas y montos

Las fechas se expresan en ISO 8601 con zona horaria.
Los montos se representan como cadenas decimales para evitar errores de punto flotante.
La zona horaria operativa debe devolverse o documentarse en cada reporte.
La moneda utiliza códigos ISO, por ejemplo PEN.

Inventario maestro resumido

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`POST`	`/v1/auth/token`	Obtener acceso server-to-server.	No	Ninguno
Integración	`GET`	`/v1/integration/capabilities`	Consultar capacidades habilitadas.	No	Ninguno
Integración	`POST`	`/v1/payment-orders`	Crear Web Checkout o POS vía chat.	Sí	Eventos payment.* y checkout.*
Integración	`GET`	`/v1/payment-orders/{id}`	Consultar estado actual.	No	Ninguno
Checkout temporal	`GET`	`/checkout/{opaque_token}`	Abrir experiencia administrada por YUPY.	No	checkout.opened
POS vía chat	`POST`	`/v1/shifts`	Abrir un turno después de identificar al usuario.	Sí	shift.opened
Integración	`POST`	`/v1/payment-orders/{id}/evidence`	Adjuntar constancia y activar OCR.	Sí	payment.evidence_received
Operación	`GET`	`/v1/pending-cases`	Consultar casos que requieren atención.	No	Ninguno
Operación	`POST`	`/v1/payment-orders/{id}/refund-cases`	Crear caso de devolución.	Sí	refund.identified
Reportes	`POST`	`/v1/report-jobs`	Solicitar una exportación grande.	Sí	report.*
Webhooks	`POST`	`/v1/webhook-endpoints`	Registrar receptor de callbacks.	Sí	webhook.endpoint_created
Sandbox	`POST`	`/v1/sandbox/simulations`	Crear un escenario de prueba.	Sí	Eventos simulados
Referencia	`GET`	`/openapi.json`	Obtener el contrato OpenAPI publicado.	No	Ninguno

Documentos de la biblioteca

Reglas de evolución

Todo endpoint nuevo debe añadirse primero al inventario maestro.
Un cambio incompatible requiere una nueva versión.
Los ejemplos no sustituyen el schema OpenAPI.
Los endpoints implementados deben cambiar de “propuesto” a “implementado”.
Las rutas verificadas en ambiente real pueden pasar a “verificado”.

API Technical Docs