Documentation Index Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
Use this file to discover all available pages before exploring further.
Todos los endpoints POST de la External Payments API requieren el header Idempotency-Key
Cómo funciona
Envía un UUID único
Genera un UUID v4 por cada intento de pago y ponlo en Idempotency-Key.
La clave queda vinculada
Si la request tiene éxito, Cobrix asocia la clave al pago creado.
Los reintentos devuelven el mismo pago
Reenviar con la misma clave retorna el pago original , no crea uno nuevo.
Scope por empresa
Las claves están namespaced por empresa, así que distintas empresas pueden usar la misma clave sin conflicto.
Reintento seguro # Primera request → crea el pago POST /api/external/payments Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 → 201 Created { "id": "pay-abc", "status": "pending" } # Reintento (timeout) → devuelve el mismo pago POST /api/external/payments Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 → 201 Created { "id": "pay-abc", "status": "pending" }
Buenas prácticas
Generar UUID v4 Usa crypto.randomUUID() (Node), uuid.uuid4() (Python) o equivalente.
Persistir junto al pedido Guarda la Idempotency-Key en tu base de datos junto con el order/invoice.
Reintentar con la misma key Si la request falla con timeout, reintenta con la misma clave .
Nunca reusar No uses la misma clave para dos intenciones de pago distintas.
Implementación import { randomUUID } from 'node:crypto' async function createPayment ( order ) { // Genera la clave una sola vez y persístela if ( ! order . idempotencyKey ) { order . idempotencyKey = randomUUID () await db . orders . update ({ id: order . id , idempotencyKey: order . idempotencyKey }) } const response = await fetch ( ` ${ BASE_URL } /api/external/payments` , { method: 'POST' , headers: { 'Content-Type' : 'application/json' , 'X-API-Key' : API_KEY , 'Idempotency-Key' : order . idempotencyKey , }, body: JSON . stringify ({ customerEmail: order . email , amountMinor: order . amountMinor , currency: order . currency , externalReference: order . id , }), }) return response . json () }
Errores relacionados Mensaje Causa "Idempotency-Key header is required"Falta el header en un POST "Duplicate idempotency key" (409)Misma clave con body diferente al request original
