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
Sección titulada «Campos del evento»| Campo | Tipo | Límite | Obligatorio |
|---|---|---|---|
type | string (enum) | ver tabla abajo | Sí |
order_ref | string o número | 100 caracteres | Sí |
event_id | string o número | 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
Sección titulada «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:
- una transacción con
external_idigual alorder_ref - si no la encuentra, una transacción con
order_numberigual alorder_ref - si aún no la encuentra, en las transacciones con
external_sourceshopify, elorder_reftambién vale sin el#del inicio (1001encuentra#1001, y#1001encuentra1001) y por el GID del pedido (gid://shopify/Order/<id>ogid://shopify/OrderIdentity/<id>encuentra el<id>)
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. Para corregirlo, reenvía por el servidor con el mismo event_id y el order_ref correcto (ver Idempotencia).
Los espacios al inicio y al final se quitan. Un número entero también se acepta y se convierte en texto (1001 es lo mismo que "1001").
event_id
Sección titulada «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 servidor, el reenvío con otro order_ref, o después del descarte, reemplaza al envío anterior; en el navegador, el mismo event_id siempre se trata como repetición.
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
Sección titulada «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
Sección titulada «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
Sección titulada «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, hasta 100 caracteres | checkout |
device_fingerprint | string, hasta 255 caracteres | 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:
- en el canal navegador, cada tipo acepta solo los campos que arma el snippet:
checkoutlleva los cuatro de identificación del dispositivo, yterms_acceptance,access_logyusage_logllevan solourl.note,carrier,tracking,latylngson del canal servidor urltiene que serhttpohttps; cualquier otra cosa se descarta, sin error. Los parámetros (?...) y el ancla (#...) se quitan antes de guardar, así que los datos del comprador en la URL no quedan en la evidencia- en el canal navegador, una
urlde otro dominio que no sea el sitio de donde vino el evento también se descarta. Un evento sin sitio de origen (sinOriginniReferer) solo mantiene laurlde los sitios autorizados de la tienda; antes de que haya un sitio autorizado, suurlse descarta latfuera de -90 a 90 ylngfuera de -180 a 180 se descartan, sin errorcarrierytrackingdedelivery_confirmationyscanvan en la defensa de la disputa como transportista y número de seguimiento; la coma separa más de un valor. Con la entrega confirmada y fechada, solo cuentan la entrega y las lecturas hechas hasta ella. La primera lectura (scan) con uno de los dos, hecha después de la compra y antes de la entrega confirmada, pasa a ser la fecha de envío- un registro de acceso, uso, entrega o lectura con fecha anterior a la compra no se usa como prueba en la defensa
- solo valores escalares (string, número, booleano). Objetos y listas se descartan
device_idde más de 100 caracteres,device_fingerprintde más de 255 y los demás campos de texto de más de 512 responden422 payload_too_large.device_idydevice_fingerprintaceptan un número entero, que se graba como texto- un
payloadausente o vacío se acepta, pero no entra como prueba en la defensa:terms_acceptance,access_log,usage_logydelivery_confirmationsin ningún dato quedan guardados y no cuentan como aceptación, acceso o entrega. En el canal navegador, donde estos tipos solo llevanurl, es el caso del evento sin unaurlválida
El evento checkout
Sección titulada «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 | no 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.
El canal servidor no graba la IP porque la IP de la llamada es la de tu servidor, no la del comprador. Envía la IP del comprador en ip_address al crear la transacción.
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. La identificación tiene que haberse hecho como máximo 24 horas antes del evento y, en el canal navegador, en el mismo sitio de donde vino. 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 identificación validada, el checkout del canal navegador no completa el dispositivo ni la IP y no genera registro de verificación, pero cuenta en el panel como evento recibido cuando la transacción del pedido llega a Rapid. Los otros tipos (access_log, usage_log, terms_acceptance) se registran normalmente, con o sin fp_request_id.
Cada fp_request_id genera el registro de verificación del dispositivo en una sola transacción. Si el mismo par llega en otro pedido, ese pedido no recibe el registro de verificación, pero sus campos de dispositivo e IP se completan como en la tabla de arriba, solo cuando están vacíos.
Ventana de correlación
Sección titulada «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.