# 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.

Página: https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-navegador/

Registra un evento de captura usando el token publicable. Es el endpoint que llama el [snippet](https://doc.rapidchargeback.com/es/canais/capture/instalar-o-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](https://doc.rapidchargeback.com/es/canais/capture/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](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-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](https://doc.rapidchargeback.com/es/canais/capture/payload/#ventana-de-correlación).

## Ejemplo de solicitud

```bash
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:

```bash
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)

```json
{ "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)

```json
{ "error": { "code": "NOT_FOUND" } }
```

### Error: tipo no disponible en este canal (422)

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

### Error: `event_id` ausente (422)

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

### Error: campo del payload demasiado largo (422)

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

## Próximos pasos

- [Instalar el snippet](https://doc.rapidchargeback.com/es/canais/capture/instalar-o-snippet/)
- [Enviar evento desde el servidor](https://doc.rapidchargeback.com/es/canais/capture/enviar-evento-servidor/)
- [Configuración del snippet](https://doc.rapidchargeback.com/es/canais/capture/config-do-snippet/)