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
Sección titulada «Endpoint»https://api.rapidchargeback.com/api/v1/capture/eventsAutenticación
Sección titulada «Autenticación»Basic Auth con client_id:client_secret. Ver Autenticación.
Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonNo 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
Sección titulada «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 o número | Identificador del pedido en tu sistema, hasta 100 caracteres | Sí |
event_id | string o número | 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_ides obligatorio, porque la credencial identifica a la empresa y no al merchantcaptured_atse respeta, así que una rutina por lotes puede informar la hora real de cada hechoevent_ides opcional, pero envía el tuyo: es lo que hace seguro el reenvío
Idempotencia
Sección titulada «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.
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.
Validaciones
Sección titulada «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 |
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 512 | 422 VALIDATION_ERROR: payload_too_large |
merchant_id que no es de tu empresa | 422 VALIDATION_ERROR: invalid_merchant_id |
captured_at que no es una fecha ISO 8601, o más de 5 minutos en el futuro | 422 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 disponible | 503 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.
Ejemplo de solicitud
Sección titulada «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
Sección titulada «Ejemplos de respuesta»Éxito (202)
Sección titulada «É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)
Sección titulada «Error: credencial ausente (401)»{ "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid Authorization header" }}Error: merchant_id ausente (422)
Sección titulada «Error: merchant_id ausente (422)»{ "error": { "code": "VALIDATION_ERROR", "message": "merchant_id required" }}Error: tipo inválido (422)
Sección titulada «Error: tipo inválido (422)»{ "error": { "code": "VALIDATION_ERROR", "message": "invalid_type" }}Captura o evidencia
Sección titulada «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 |