Tipos y payload

Referencia de los valores aceptados en los dos canales de captura. Vale para POST /capture/{token}/events y POST /capture/events.

Campos del evento

Campo	Tipo	Límite	Obligatorio
type	string (enum)	ver tabla abajo	Sí
order_ref	string	100 caracteres	Sí
event_id	string	64 caracteres	Sí en el navegador, opcional en el servidor
payload	objeto	ver campos aceptados	No
captured_at	string (ISO 8601)	-	No, y solo lo usa el canal servidor
merchant_id	string (UUID)	-	Solo en el canal servidor

order_ref

Es el identificador del pedido en tu sistema, y es lo único que une el evento a una transacción. Rapid busca, dentro de tu empresa y del merchant informado:

1. una transacción con external_id igual al order_ref
2. si no la encuentra, una transacción con order_number igual al order_ref

Envía siempre el mismo valor que usaste en external_id al crear la transacción. Un order_ref equivocado no genera error en la llamada: el evento se acepta, no encuentra transacción y se descarta después de la ventana de correlación.

event_id

Identificador del evento, generado por ti. Sirve como clave de idempotencia: reenviar el mismo event_id para el mismo merchant no crea evidencia duplicada.

En el canal navegador es obligatorio (el snippet genera un UUID por evento). En el canal servidor, si lo omites, Rapid genera uno. Envía el tuyo cuando puedas reenviar la misma llamada, es lo que garantiza la idempotencia.

No uses : en el event_id. El carácter se elimina antes del uso interno, lo que haría que dos ids distintos colisionen.

captured_at

Cuándo ocurrió el hecho, en ISO 8601.

Canal	Comportamiento
Navegador	se ignora. Rapid registra la hora en que llegó el evento
Servidor	se usa tal como se envió. Si se omite, vale la hora de la llamada

Si el hecho ocurrió antes de la llamada (un procesamiento por lotes de noche, por ejemplo), usa el canal servidor e informa captured_at.

Valores de type

Valor	Qué registra	Navegador	Servidor
checkout	Finalización de la compra, con los datos del dispositivo	Sí	Sí
terms_acceptance	Aceptación de términos, política o contrato	Sí	Sí
access_log	Acceso al producto o al área con sesión iniciada	Sí	Sí
usage_log	Uso efectivo del producto o servicio	Sí	Sí
delivery_confirmation	Entrega confirmada	No	Sí
scan	Lectura de código de rastreo en tránsito	No	Sí
delivery_gps	Coordenada de la entrega	No	Sí

Los tres últimos existen solo en el canal servidor: son hechos de tu operación, no del navegador del comprador. Usarlos en el canal navegador responde 422 invalid_type.

Campos de payload

El payload tiene una lista cerrada de campos. Una clave fuera de la lista se descarta en silencio, sin error, así que revisa la ortografía.

Campo	Tipo	Usar en
device_id	string	checkout
device_fingerprint	string	checkout
fp	string	checkout, indica el origen de la identificación (pro o fallback)
fp_request_id	string	checkout, exigido para validar la identificación
url	string	terms_acceptance, access_log, usage_log
note	string	cualquier tipo
carrier	string	delivery_confirmation, scan
tracking	string	delivery_confirmation, scan
lat	número	delivery_gps
lng	número	delivery_gps

Reglas:

• solo valores escalares (string, número, booleano). Objetos y listas se descartan
• un string de más de 512 caracteres responde 422 payload_too_large
• un payload ausente o vacío se acepta

El evento checkout

El checkout es el único tipo que graba datos directamente en la transacción, y no solo como registro adjunto. Completa el dispositivo y la IP de la transacción solo cuando esos campos están vacíos: una captura anterior nunca se sobrescribe.

Qué puede grabar cada canal:

Dato de la transacción	Navegador	Servidor
device_id	no graba	graba
device_fingerprint	solo con identificación validada	graba
ip_address	solo con identificación validada	graba

La diferencia existe porque el token del navegador es publicable: cualquier persona que lo tenga puede enviar eventos. Un dato no validado no toca los campos que sostienen la defensa.

Identificación validada significa: enviaste fp_request_id y device_id en el payload, y Rapid confirmó el par contra Fingerprint del lado del servidor. En ese caso el evento también genera un registro de verificación del dispositivo, con las señales de bot, VPN y ventana de incógnito. Sin fp_request_id, el evento sigue valiendo como registro, solo que sin la parte del dispositivo.

Cada fp_request_id vale para una transacción. El mismo par reutilizado en otro pedido se trata como repetición y se ignora.

Ventana de correlación

El evento puede llegar antes de que exista la transacción. Queda en la cola y se reintenta durante unas 68 horas, a intervalos crecientes. Pasada la ventana sin una transacción correspondiente, el evento se descarta.

En la práctica: enviar el checkout en el momento exacto de la compra funciona, aunque tu rutina solo envíe la transacción a Rapid horas después.

Próximos pasos

• Instalar el snippet
• Enviar evento desde el navegador
• Enviar evento desde el servidor