Enviar evento desde el navegador

Registra un evento de captura usando el token publicable. Es el endpoint que llama el snippet, y puedes llamarlo directamente si prefieres no cargar el script.

Endpoint

POST https://api.rapidchargeback.com/api/v1/capture/{token}/events

Autenticación

Ninguna. El token publicable en la URL identifica al merchant.

Content-Type: application/json

El token no es secreto y puede quedar en el HTML de tu tienda. Solo permite escribir, y el evento solo se convierte en evidencia si corresponde a un pedido real tuyo.

Parámetros de URL

Campo	Tipo	Descripción
`token`	string	Token publicable del merchant, generado en el panel

Cuerpo de la solicitud

Campo	Tipo	Descripción	Obligatorio
`type`	string (enum)	`checkout`, `terms_acceptance`, `access_log` o `usage_log`	Sí
`order_ref`	string	Identificador del pedido en tu sistema, hasta 100 caracteres	Sí
`event_id`	string	Identificador del evento, generado por ti, hasta 64 caracteres	Sí
`payload`	objeto	Datos del hecho, con campos de lista cerrada	No

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

Dos puntos específicos de este canal:

event_id es obligatorio aquí. Genera un UUID por evento
captured_at enviado en el cuerpo se ignora. Rapid registra la hora de llegada. Para informar la hora del hecho, usa el canal servidor

Los tipos delivery_confirmation, scan y delivery_gps no existen en este canal: son hechos de tu operación, no del navegador del comprador.

Límite de llamadas

120 solicitudes por minuto, por IP de origen. Es holgado para un checkout real y limita a quien esté usando el token fuera de tu sitio.

Validaciones

Regla	Respuesta
Token desconocido, inactivo o sin merchant	`404 NOT_FOUND`
`type` ausente, o fuera de los cuatro aceptados en este canal	`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` ausente, vacío o 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
Más de 120 solicitudes por minuto	`429 Too Many Requests`

No existe error para un order_ref inexistente. El evento se acepta, queda en la cola y se descarta si ninguna transacción corresponde dentro de la ventana de correlación. Ver Ventana de correlación.

Ejemplo de solicitud

curl -X POST https://api.rapidchargeback.com/api/v1/capture/tu_token_publicable/events \
  -H "Content-Type: application/json" \
  -d '{
    "type": "terms_acceptance",
    "order_ref": "TXN-2026-001",
    "event_id": "019b0000-1111-7000-8000-000000000001",
    "payload": { "url": "https://loja.exemplo.com/checkout" }
  }'

Evento de checkout con identificación del dispositivo:

curl -X POST https://api.rapidchargeback.com/api/v1/capture/tu_token_publicable/events \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout",
    "order_ref": "TXN-2026-001",
    "event_id": "019b0000-1111-7000-8000-000000000002",
    "payload": {
      "device_id": "8kJ2mQvR1nZxYb0T",
      "device_fingerprint": "8kJ2mQvR1nZxYb0T",
      "fp": "pro",
      "fp_request_id": "1712059781234.Xk9Lp2"
    }
  }'

Ejemplos de respuesta

Éxito (202)

{ "accepted": true }

202 significa que el evento entró en la cola, no que ya se convirtió en evidencia. La correlación con la transacción ocurre después.

Error: token desconocido (404)

{ "error": { "code": "NOT_FOUND" } }

Error: tipo no disponible en este canal (422)

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

Error: `event_id` ausente (422)

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

Error: campo del payload demasiado largo (422)

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