Copayex Client API – Endpoints para clientes

Copayex Client API expone recursos REST para crear ítems cobrables, registrar pagos y monitorear eventos en plataformas omnicanal. Todas las rutas se sirven bajo la siguiente base:

Base URL: https://api.copayex.com

Las respuestas utilizan JSON estándar y los códigos HTTP siguen las convenciones habituales (2xx éxito, 4xx errores de cliente, 5xx incidentes internos).

Autenticación y encabezados obligatorios

• Todas las rutas (excepto emisión de token) necesitan un bearer token.
• Header Authorization: Bearer <client_access_token> con JWT válido emitido para el client_id.
• Fechas en ISO8601; pageIndex base 0; pageSize tamaño por página.

Cómo obtener tus credenciales

1. Ingresá al panel de Copayex y navegá a Configuración → Integraciones → API Keys.
2. Creá una integración con el nombre de tu aplicación. Podés definir una fecha de expiración opcional.
3. El panel generará un clientId y una apiKey. Solo podrás ver la apiKey completa inmediatamente después de crearla: guardala en un gestor seguro.
4. Usa esos valores para solicitar el token (POST /api/token) y luego envialo en el header Authorization para todas las requests subsecuentes.

Obtención de clientId y apiKey

En la vista de Integraciones podés definir:

• Nombre de la aplicación: identifica al cliente; se mostrará en el panel de auditoría.
• Expiración (opcional): fecha hasta la cual la apiKey será válida. Si la dejás vacía, permanecerá activa hasta que la revokes manualmente.
• Crear integración: al confirmar, Copayex mostrará el clientId y la apiKey. Copiá la apiKey en ese momento, ya que no volverá a mostrarse completa.

Resumen de controladores

Navegación sugerida

• Obtener token: obtén el JWT de cliente con clientId + apiKey.
• Items: define qué cobran tus usuarios, asocia QRs y controla estados (active, finished, void).
• Payments: registra aportes parciales, consulta historiales y solicita devoluciones.
• Static QRs: genera códigos permanentes para tiendas físicas o kioscos.
• Webhooks: suscríbete a eventos (payments.item.*) y monitorea los deliveries para reintentar fallos.

Cada sección profundiza en tablas de parámetros (Path, Query, Body) y detalla las respuestas esperadas.

Consideraciones adicionales

• Auditoría: todas las acciones registran eventos en AuditLogService con clientId o apiKeyId para trazabilidad.
• Paginación: define siempre pageSize/pageIndex. Sin ellos, se usan valores por defecto que pueden variar por entorno.
• Rotación de secretos: la respuesta incluye secret y graceDays.