# Enviar evento pelo servidor

> Registre eventos de captura pelo seu backend: entrega confirmada, rastreio, uso do serviço e eventos com data retroativa.

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

Registra um evento de captura pelo seu backend, com as mesmas credenciais das outras APIs. É o canal para fatos que não acontecem no navegador: entrega confirmada, leitura de rastreio, coordenada de entrega, e para qualquer evento que você precise reenviar ou datar.

## Endpoint

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

## Autenticação

Basic Auth com `client_id:client_secret`. Ver [Autenticação](https://doc.rapidchargeback.com/referencia/autenticacao/).

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

Não use o token publicável aqui. A empresa vem da credencial, por isso este canal pode gravar dado de aparelho sem a validação exigida no navegador.

## Corpo da requisição

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| `merchant_id` | string (UUID) | Merchant a que o evento pertence, dentro da sua empresa (ver [Listar merchants](https://doc.rapidchargeback.com/canais/merchants/listar-merchants/)) | Sim |
| `type` | string (enum) | Os quatro tipos do navegador mais `delivery_confirmation`, `scan` e `delivery_gps` | Sim |
| `order_ref` | string | Identificador do pedido no seu sistema, até 100 caracteres | Sim |
| `event_id` | string | Identificador do evento, até 64 caracteres. Omitido, a Rapid gera um | Não |
| `payload` | objeto | Dados do fato, com campos de lista fechada | Não |
| `captured_at` | string (ISO 8601) | Quando o fato aconteceu. Omitido, vale o horário da chamada | Não |

A referência completa dos valores aceitos está em [Tipos e payload](https://doc.rapidchargeback.com/canais/capture/payload/).

Três diferenças em relação ao canal navegador:

- `merchant_id` é obrigatório, porque a credencial identifica a empresa e não o merchant
- `captured_at` é respeitado, então uma rotina em lote pode informar o horário real de cada fato
- `event_id` é opcional, mas mande o seu: é o que torna o reenvio seguro

## Idempotência

Reenviar a mesma chamada com o mesmo `event_id` não duplica a evidência. É o comportamento esperado em retentativa por timeout ou resposta perdida.

Se você omitir o `event_id`, cada chamada gera um identificador novo, e a mesma chamada repetida vira dois registros.

## Validações

| Regra | Resposta |
|---|---|
| Credencial ausente ou inválida | `401 UNAUTHORIZED` |
| `merchant_id` ausente | `422 VALIDATION_ERROR`: *merchant_id required* |
| `type` ausente ou fora do enum | `422 VALIDATION_ERROR`: *invalid_type* |
| `order_ref` ausente, vazio ou acima de 100 caracteres | `422 VALIDATION_ERROR`: *invalid_order_ref* |
| `event_id` acima de 64 caracteres | `422 VALIDATION_ERROR`: *invalid_event_id* |
| Campo de texto do `payload` acima de 512 caracteres | `422 VALIDATION_ERROR`: *payload_too_large* |

`merchant_id` de outra empresa não acusa erro na chamada: o evento é aceito e descartado na correlação, porque a transação é procurada dentro da sua empresa. O mesmo vale para `order_ref` inexistente.

## Exemplo de requisição

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 da 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"
  }'
```

## Exemplos de resposta

### Sucesso (202)

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

`202` quer dizer que o evento entrou na fila. A correlação com a transação acontece depois, pelo `order_ref`.

### Erro: credencial ausente (401)

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

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

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

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

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

## Captura ou evidência

Os dois canais registram fato numa transação, e a escolha é simples:

| Situação | Use |
|---|---|
| A transação já está na Rapid e você tem o UUID dela | [`POST /evidence`](https://doc.rapidchargeback.com/canais/evidence/registrar-evidencia/) |
| Você tem só o seu identificador de pedido, ou o fato acontece antes do envio da transação | este endpoint |
| O fato precisa de campo fora da lista fechada de payload | [`POST /evidence`](https://doc.rapidchargeback.com/canais/evidence/registrar-evidencia/), que aceita payload livre |

## Próximos passos

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