# Tipos y payload

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

Página: https://doc.rapidchargeback.com/es/canais/capture/payload/

Referencia de los valores aceptados en los dos canales de captura. Vale para [`POST /capture/{token}/events`](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-navegador/) y [`POST /capture/events`](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-servidor/).

## 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](https://doc.rapidchargeback.com/es/canais/transactions/criar-transacao/). 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](https://doc.rapidchargeback.com/es/canais/capture/instalar-o-snippet/)
- [Enviar evento desde el navegador](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-navegador/)
- [Enviar evento desde el servidor](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-servidor/)