Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

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.

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

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.

CampoTipoDescripciónObligatorio
merchant_idstring (UUID)Merchant al que pertenece el evento, dentro de tu empresa (ver Listar merchants)Sí
typestring (enum)Los cuatro tipos del navegador más delivery_confirmation, scan y delivery_gpsSí
order_refstring o númeroIdentificador del pedido en tu sistema, hasta 100 caracteresSí
event_idstring o númeroIdentificador del evento, hasta 64 caracteres. Si se omite, Rapid genera unoNo
payloadobjetoDatos del hecho, con campos de lista cerradaNo
captured_atstring (ISO 8601)Cuándo ocurrió el hecho. Si se omite, vale la hora de la llamadaNo

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

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.

Para corregir un evento enviado con el order_ref equivocado, o que se descartó porque la transacción llegó después de la ventana de correlación, reenvíalo con el mismo event_id y el order_ref correcto: el nuevo envío reemplaza al anterior. Si el anterior todavía se está procesando, la respuesta es 503; reenvía después del Retry-After. Un evento que ya se convirtió en evidencia no se reemplaza.

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

ReglaRespuesta
Credencial ausente o inválida401 UNAUTHORIZED
merchant_id ausente422 VALIDATION_ERROR: merchant_id required
type ausente o fuera del enum422 VALIDATION_ERROR: invalid_type
order_ref ausente, vacío o de más de 100 caracteres422 VALIDATION_ERROR: invalid_order_ref
event_id de más de 64 caracteres422 VALIDATION_ERROR: invalid_event_id
device_id de más de 100 caracteres, device_fingerprint de más de 255 u otro campo de texto del payload de más de 512422 VALIDATION_ERROR: payload_too_large
merchant_id que no es de tu empresa422 VALIDATION_ERROR: invalid_merchant_id
captured_at que no es una fecha ISO 8601, o más de 5 minutos en el futuro422 VALIDATION_ERROR: invalid_captured_at
Merchant con demasiados eventos del servidor esperando la transacción (tope separado del navegador)429 TOO_MANY_PENDING_EVENTS
Captura temporalmente no disponible503 CAPTURE_TEMPORARILY_UNAVAILABLE, con Retry-After

Ante un 503, reenvía el evento después de los segundos del header Retry-After. Con el mismo event_id, el reenvío nunca duplica la evidencia.

Un order_ref inexistente no da error en la llamada: el evento se acepta y se descarta en la correlación si ninguna transacción tuya tiene ese identificador.

Entrega confirmada:

Ventana de terminal
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:

Ventana de terminal
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"
}'
{ "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": {
"code": "UNAUTHORIZED",
"message": "Missing or invalid Authorization header"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "merchant_id required"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "invalid_type"
}
}

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

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