Enviar evento desde el servidor

Registra un evento de captura desde tu backend, con las mismas credenciales de las otras APIs. Es el canal para hechos que no ocurren en el navegador: entrega confirmada, lectura de rastreo, coordenada de entrega, y para cualquier evento que necesites reenviar o fechar.

Endpoint

POST https://api.rapidchargeback.com/api/v1/capture/events

Autenticación

Basic Auth con client_id:client_secret. Ver Autenticación.

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

No uses el token publicable aquí. La empresa viene de la credencial, por eso este canal puede grabar datos del dispositivo sin la validación exigida en el navegador.

Cuerpo de la solicitud

Campo	Tipo	Descripción	Obligatorio
`merchant_id`	string (UUID)	Merchant al que pertenece el evento, dentro de tu empresa (ver Listar merchants)	Sí
`type`	string (enum)	Los cuatro tipos del navegador más `delivery_confirmation`, `scan` y `delivery_gps`	Sí
`order_ref`	string	Identificador del pedido en tu sistema, hasta 100 caracteres	Sí
`event_id`	string	Identificador del evento, hasta 64 caracteres. Si se omite, Rapid genera uno	No
`payload`	objeto	Datos del hecho, con campos de lista cerrada	No
`captured_at`	string (ISO 8601)	Cuándo ocurrió el hecho. Si se omite, vale la hora de la llamada	No

La referencia completa de los valores aceptados está en Tipos y payload.

Tres diferencias respecto del canal navegador:

merchant_id es obligatorio, porque la credencial identifica a la empresa y no al merchant
captured_at se respeta, así que una rutina por lotes puede informar la hora real de cada hecho
event_id es opcional, pero envía el tuyo: es lo que hace seguro el reenvío

Idempotencia

Reenviar la misma llamada con el mismo event_id no duplica la evidencia. Es el comportamiento esperado en un reintento por timeout o respuesta perdida.

Si omites el event_id, cada llamada genera un identificador nuevo, y la misma llamada repetida se convierte en dos registros.

Validaciones

Regla	Respuesta
Credencial ausente o inválida	`401 UNAUTHORIZED`
`merchant_id` ausente	`422 VALIDATION_ERROR`: merchant_id required
`type` ausente o fuera del enum	`422 VALIDATION_ERROR`: invalid_type
`order_ref` ausente, vacío o de más de 100 caracteres	`422 VALIDATION_ERROR`: invalid_order_ref
`event_id` de más de 64 caracteres	`422 VALIDATION_ERROR`: invalid_event_id
Campo de texto del `payload` de más de 512 caracteres	`422 VALIDATION_ERROR`: payload_too_large

Un merchant_id de otra empresa no da error en la llamada: el evento se acepta y se descarta en la correlación, porque la transacción se busca dentro de tu empresa. Lo mismo vale para un order_ref inexistente.

Ejemplo de solicitud

Entrega confirmada:

curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_confirmation",
    "order_ref": "TXN-2026-001",
    "event_id": "entrega-TXN-2026-001",
    "payload": { "carrier": "correios", "tracking": "AA123456789BR" },
    "captured_at": "2026-04-03T11:20:00Z"
  }'

Coordenada de la entrega:

curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_gps",
    "order_ref": "TXN-2026-001",
    "event_id": "gps-TXN-2026-001",
    "payload": { "lat": -23.5614, "lng": -46.6559 },
    "captured_at": "2026-04-03T11:20:00Z"
  }'

Ejemplos de respuesta

Éxito (202)

{ "accepted": true }

202 significa que el evento entró en la cola. La correlación con la transacción ocurre después, por el order_ref.

Error: credencial ausente (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Error: `merchant_id` ausente (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "merchant_id required"
  }
}

Error: tipo inválido (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "invalid_type"
  }
}

Captura o evidencia

Los dos canales registran un hecho en una transacción, y la elección es simple:

Situación	Usa
La transacción ya está en Rapid y tienes su UUID	`POST /evidence`
Solo tienes tu identificador de pedido, o el hecho ocurre antes del envío de la transacción	este endpoint
El hecho necesita un campo fuera de la lista cerrada del payload	`POST /evidence`, que acepta payload libre