Sandbox, diagnóstico, errores y OpenAPI

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: Definir pruebas controladas, diagnóstico permitido, catálogo común de errores y publicación del contrato OpenAPI.

Sandbox

Las simulaciones funcionan únicamente con credenciales de sandbox y no representan movimientos reales.

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Sandbox	`GET`	`/v1/sandbox/capabilities`	Consultar escenarios disponibles.	No	Ninguno
Sandbox	`POST`	`/v1/sandbox/simulations`	Crear simulación genérica.	Obligatoria	Eventos simulados
Sandbox	`GET`	`/v1/sandbox/simulations/{id}`	Consultar simulación.	No	Ninguno
Sandbox	`POST`	`/v1/sandbox/payment-orders/{id}/simulate-payment`	Simular pago exacto.	Obligatoria	payment.detected, payment.reconciled
Sandbox	`POST`	`/v1/sandbox/payment-orders/{id}/simulate-underpayment`	Simular pago menor.	Obligatoria	payment.amount_difference
Sandbox	`POST`	`/v1/sandbox/payment-orders/{id}/simulate-overpayment`	Simular exceso.	Obligatoria	payment.amount_difference, refund.identified
Sandbox	`POST`	`/v1/sandbox/payment-orders/{id}/simulate-late-payment`	Simular pago tardío.	Obligatoria	payment.late_detected
Sandbox	`POST`	`/v1/sandbox/payment-orders/{id}/simulate-ambiguity`	Simular ambigüedad.	Obligatoria	payment.ambiguous
Sandbox	`POST`	`/v1/sandbox/payment-orders/{id}/simulate-evidence`	Simular evidencia y OCR.	Obligatoria	payment.evidence_processed
Sandbox	`POST`	`/v1/sandbox/webhooks/{id}/test-event`	Enviar callback de prueba.	Obligatoria	Evento seleccionado
Sandbox	`POST`	`/v1/sandbox/reset`	Limpiar datos simulados con controles.	Obligatoria	sandbox.reset

Ejemplo: simular pago tardío

POST /v1/sandbox/payment-orders/ypt_01JXYZ/simulate-late-payment
Idempotency-Key: e93fa0b8-20c8-4f8c-a2dc-9150217d7b11

{
  "detected_amount": "85.50",
  "detected_at": "2026-07-20T15:10:00-05:00"
}

{
  "simulation_id": "sim_01JXYZ",
  "status": "completed",
  "events_emitted": [
    "payment.late_detected"
  ],
  "request_id": "req_01JXYZ"
}

Diagnóstico y OpenAPI

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Diagnóstico	`GET`	`/health`	Vida básica del servicio.	No	Ninguno
Diagnóstico	`GET`	`/ready`	Preparación operativa.	No	Ninguno
Integración	`GET`	`/v1/integration/status`	Estado visible para el cliente.	No	Ninguno
Diagnóstico	`GET`	`/v1/diagnostics/request/{request_id}`	Consultar diagnóstico permitido.	No	Ninguno
Referencia	`GET`	`/openapi.json`	Obtener OpenAPI 3.1.	No	Ninguno
Referencia	`GET`	`/v1/reference/changelog`	Consultar cambios.	No	Ninguno

Diagnóstico por request_id

Solo debe devolver información permitida para el cliente. No debe exponer secretos, consultas bancarias ni detalles de infraestructura.

GET /v1/diagnostics/request/req_01JXYZ

{
  "request_id": "req_01JXYZ",
  "status": "completed",
  "endpoint": "POST /v1/payment-orders",
  "http_status": 201,
  "started_at": "2026-07-20T14:30:02-05:00",
  "finished_at": "2026-07-20T14:30:02-05:00"
}

OpenAPI

La especificación objetivo es OpenAPI 3.1 y debe contener:

paths
securitySchemes
schemas
requestBodies
responses
errors
examples
webhooks
versiones
descripciones de idempotencia

El archivo publicado será la fuente procesable por máquinas para SDKs, validadores y pruebas contractuales.

Formato común de error

{
  "error": {
    "code": "possible_duplicate_transaction",
    "message": "Existe una operación reciente con características equivalentes.",
    "retryable": false,
    "details": {
      "candidate_yupy_transaction_id": "ypt_01JXYZ"
    },
    "request_id": "req_01JABC"
  }
}

Catálogo inicial de errores

HTTP	Código	Significado	Acción
401	`invalid_credentials`	Credenciales inválidas.	No
401	`credential_revoked`	Credencial revocada.	No
401	`access_token_expired`	Token vencido.	Sí, renovar
403	`environment_not_allowed`	Ambiente incorrecto.	No
403	`permission_denied`	Permiso insuficiente.	No
422	`validation_error`	Datos inválidos.	Corregir
422	`invalid_amount`	Monto inválido.	Corregir
422	`unsupported_currency`	Moneda no admitida.	Corregir
409	`idempotency_conflict`	Clave usada con otro payload.	No
409	`external_transaction_conflict`	ID externo con otros datos.	No
409	`possible_duplicate_transaction`	Posible duplicado.	Revisar
404	`payment_order_not_found`	Orden inexistente.	No
409	`invalid_state_transition`	Transición no permitida.	No
410	`checkout_session_expired`	Sesión vencida.	Crear otra sesión
404	`shift_not_available`	Turno no disponible.	Revisar
409	`shift_device_mismatch`	Dispositivo no corresponde.	Corregir
415	`evidence_not_supported`	Formato no admitido.	Corregir
413	`evidence_too_large`	Archivo demasiado grande.	Corregir
500	`ocr_failed`	OCR falló.	Según retryable
404	`pending_case_not_found`	Pendiente inexistente.	No
404	`refund_case_not_found`	Devolución inexistente.	No
422	`refund_execution_evidence_required`	Falta evidencia.	Corregir
404	`webhook_endpoint_not_found`	Endpoint inexistente.	No
404	`report_not_ready`	Reporte aún no disponible.	Sí, consultar después
410	`report_expired`	Descarga vencida.	Crear otro reporte
429	`rate_limit_exceeded`	Límite superado.	Sí, esperar
503	`service_unavailable`	Servicio no disponible.	Sí
500	`internal_error`	Error inesperado.	Según retryable

Regla de reintentos

Solo se reintenta cuando retryable sea verdadero o la documentación del endpoint lo permita.
Un reintento de creación conserva el mismo ID externo y la misma Idempotency-Key.
Un error de validación se corrige antes de repetir.
Un 429 debe respetar la espera indicada por el servicio.

Criterios de certificación

Autenticación correcta
Creación idempotente
Detección de duplicados
Web Checkout
POS vía chat
Captura y OCR
Pago exacto
Pago incompleto
Pago en exceso
Pago tardío
Ambigüedad
Cancelación
Webhooks firmados
Reintento de webhooks
Reportes
Errores esperados

API Technical Docs