# Enviar evento desde el servidor

> Registra eventos de captura desde tu backend: entrega confirmada, rastreo, uso del servicio y eventos con fecha retroactiva.

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

Registra un evento de captura desde tu backend, con las mismas credenciales de las otras APIs. Es el canal para hechos que no ocurren en el navegador: entrega confirmada, lectura de rastreo, coordenada de entrega, y para cualquier evento que necesites reenviar o fechar.

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/capture/events
```

## Autenticación

Basic Auth con `client_id:client_secret`. Ver [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/).

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

No uses el token publicable aquí. La empresa viene de la credencial, por eso este canal puede grabar datos del dispositivo sin la validación exigida en el navegador.

## Cuerpo de la solicitud

| Campo | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| `merchant_id` | string (UUID) | Merchant al que pertenece el evento, dentro de tu empresa (ver [Listar merchants](https://doc.rapidchargeback.com/es/canais/merchants/listar-merchants/)) | Sí |
| `type` | string (enum) | Los cuatro tipos del navegador más `delivery_confirmation`, `scan` y `delivery_gps` | Sí |
| `order_ref` | string | Identificador del pedido en tu sistema, hasta 100 caracteres | Sí |
| `event_id` | string | Identificador del evento, hasta 64 caracteres. Si se omite, Rapid genera uno | No |
| `payload` | objeto | Datos del hecho, con campos de lista cerrada | No |
| `captured_at` | string (ISO 8601) | Cuándo ocurrió el hecho. Si se omite, vale la hora de la llamada | No |

La referencia completa de los valores aceptados está en [Tipos y payload](https://doc.rapidchargeback.com/es/canais/capture/payload/).

Tres diferencias respecto del canal navegador:

- `merchant_id` es obligatorio, porque la credencial identifica a la empresa y no al merchant
- `captured_at` se respeta, así que una rutina por lotes puede informar la hora real de cada hecho
- `event_id` es opcional, pero envía el tuyo: es lo que hace seguro el reenvío

## Idempotencia

Reenviar la misma llamada con el mismo `event_id` no duplica la evidencia. Es el comportamiento esperado en un reintento por timeout o respuesta perdida.

Si omites el `event_id`, cada llamada genera un identificador nuevo, y la misma llamada repetida se convierte en dos registros.

## Validaciones

| Regla | Respuesta |
|---|---|
| Credencial ausente o inválida | `401 UNAUTHORIZED` |
| `merchant_id` ausente | `422 VALIDATION_ERROR`: *merchant_id required* |
| `type` ausente o fuera del enum | `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` 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* |

Un `merchant_id` de otra empresa no da error en la llamada: el evento se acepta y se descarta en la correlación, porque la transacción se busca dentro de tu empresa. Lo mismo vale para un `order_ref` inexistente.

## Ejemplo de solicitud

Entrega confirmada:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_confirmation",
    "order_ref": "TXN-2026-001",
    "event_id": "entrega-TXN-2026-001",
    "payload": { "carrier": "correios", "tracking": "AA123456789BR" },
    "captured_at": "2026-04-03T11:20:00Z"
  }'
```

Coordenada de la entrega:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_gps",
    "order_ref": "TXN-2026-001",
    "event_id": "gps-TXN-2026-001",
    "payload": { "lat": -23.5614, "lng": -46.6559 },
    "captured_at": "2026-04-03T11:20:00Z"
  }'
```

## Ejemplos de respuesta

### Éxito (202)

```json
{ "accepted": true }
```

`202` significa que el evento entró en la cola. La correlación con la transacción ocurre después, por el `order_ref`.

### Error: credencial ausente (401)

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}
```

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

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "merchant_id required"
  }
}
```

### Error: tipo inválido (422)

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

## Captura o evidencia

Los dos canales registran un hecho en una transacción, y la elección es simple:

| Situación | Usa |
|---|---|
| La transacción ya está en Rapid y tienes su UUID | [`POST /evidence`](https://doc.rapidchargeback.com/es/canais/evidence/registrar-evidencia/) |
| Solo tienes tu identificador de pedido, o el hecho ocurre antes del envío de la transacción | este endpoint |
| El hecho necesita un campo fuera de la lista cerrada del payload | [`POST /evidence`](https://doc.rapidchargeback.com/es/canais/evidence/registrar-evidencia/), que acepta payload libre |

## Próximos pasos

- [Tipos y payload](https://doc.rapidchargeback.com/es/canais/capture/payload/)
- [Instalar el snippet](https://doc.rapidchargeback.com/es/canais/capture/instalar-o-snippet/)
- [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/)