# Tipos e payload

> Referência dos valores aceitos nos dois canais de captura. Vale para POST /capture/{token}/events e POST /capture/events.

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

Referência dos valores aceitos nos dois canais de captura. Vale para [`POST /capture/{token}/events`](https://doc.rapidchargeback.com/canais/capture/enviar-evento-navegador/) e [`POST /capture/events`](https://doc.rapidchargeback.com/canais/capture/enviar-evento-servidor/).

## Campos do evento

| Campo | Tipo | Limite | Obrigatório |
|---|---|---|---|
| `type` | string (enum) | ver tabela abaixo | Sim |
| `order_ref` | string | 100 caracteres | Sim |
| `event_id` | string | 64 caracteres | Sim no navegador, opcional no servidor |
| `payload` | objeto | ver campos aceitos | Não |
| `captured_at` | string (ISO 8601) | - | Não, e só o canal servidor usa |
| `merchant_id` | string (UUID) | - | Só no canal servidor |

### `order_ref`

É o identificador do pedido no **seu** sistema, e é a única coisa que liga o evento a uma transação. A Rapid procura, dentro da sua empresa e do merchant informado:

1. uma transação com `external_id` igual ao `order_ref`
2. se não achar, uma transação com `order_number` igual ao `order_ref`

Mande sempre o mesmo valor que você usou no `external_id` ao [criar a transação](https://doc.rapidchargeback.com/canais/transactions/criar-transacao/). `order_ref` errado não gera erro na chamada: o evento é aceito, não acha transação e é descartado depois da janela de correlação.

### `event_id`

Identificador do evento, gerado por você. Serve de chave de idempotência: reenviar o mesmo `event_id` para o mesmo merchant não cria evidência duplicada.

No canal navegador ele é **obrigatório** (o snippet gera um UUID por evento). No canal servidor, se você omitir, a Rapid gera um. Mande o seu quando puder reenviar a mesma chamada, é o que garante a idempotência.

Não use `:` no `event_id`. O caractere é removido antes do uso interno, o que faria dois ids diferentes colidirem.

### `captured_at`

Quando o fato aconteceu, em ISO 8601.

| Canal | Comportamento |
|---|---|
| Navegador | ignorado. A Rapid registra o horário em que o evento chegou |
| Servidor | usado como enviado. Omitido, vale o horário da chamada |

Se o fato aconteceu antes da chamada (um processamento em lote à noite, por exemplo), use o canal servidor e informe `captured_at`.

## Valores de `type`

| Valor | O que registra | Navegador | Servidor |
|---|---|---|---|
| `checkout` | Finalização da compra, com os dados do aparelho | Sim | Sim |
| `terms_acceptance` | Aceite de termos, política ou contrato | Sim | Sim |
| `access_log` | Acesso ao produto ou à área logada | Sim | Sim |
| `usage_log` | Uso efetivo do produto ou serviço | Sim | Sim |
| `delivery_confirmation` | Entrega confirmada | Não | Sim |
| `scan` | Leitura de código de rastreio em trânsito | Não | Sim |
| `delivery_gps` | Coordenada da entrega | Não | Sim |

Os três últimos existem só no canal servidor: são fatos da sua operação, não do navegador do comprador. Usá-los no canal navegador responde `422 invalid_type`.

## Campos de `payload`

O `payload` tem **lista fechada** de campos. Chave fora da lista é descartada em silêncio, sem erro, então confira a grafia.

| Campo | Tipo | Usar em |
|---|---|---|
| `device_id` | string | `checkout` |
| `device_fingerprint` | string | `checkout` |
| `fp` | string | `checkout`, indica a origem da identificação (`pro` ou `fallback`) |
| `fp_request_id` | string | `checkout`, exigido para validar a identificação |
| `url` | string | `terms_acceptance`, `access_log`, `usage_log` |
| `note` | string | qualquer tipo |
| `carrier` | string | `delivery_confirmation`, `scan` |
| `tracking` | string | `delivery_confirmation`, `scan` |
| `lat` | número | `delivery_gps` |
| `lng` | número | `delivery_gps` |

Regras:

- só valores escalares (string, número, booleano). Objeto e lista são descartados
- string acima de **512 caracteres** responde `422 payload_too_large`
- `payload` ausente ou vazio é aceito

## O evento `checkout`

O `checkout` é o único tipo que grava dados direto na transação, e não apenas como registro anexo. Ele preenche aparelho e IP da transação **somente quando os campos estão vazios**: captura anterior nunca é sobrescrita.

O que cada canal pode gravar:

| Dado da transação | Navegador | Servidor |
|---|---|---|
| `device_id` | não grava | grava |
| `device_fingerprint` | só com identificação validada | grava |
| `ip_address` | só com identificação validada | grava |

A diferença existe porque o token do navegador é publicável: qualquer pessoa com ele pode mandar eventos. Dado não validado não encosta nos campos que sustentam a defesa.

**Identificação validada** quer dizer: você mandou `fp_request_id` e `device_id` no payload, e a Rapid confirmou o par contra o Fingerprint do lado servidor. Nesse caso o evento também gera um registro de verificação de aparelho, com os sinais de bot, VPN e janela anônima. Sem `fp_request_id`, o evento continua valendo como registro, apenas sem a parte de aparelho.

Cada `fp_request_id` vale para **uma** transação. O mesmo par reaproveitado em outro pedido é tratado como repetição e ignorado.

## Janela de correlação

O evento pode chegar antes da transação existir. Ele fica na fila e é retentado por cerca de **68 horas**, em intervalos crescentes. Passada a janela sem transação correspondente, o evento é descartado.

Na prática: mandar o `checkout` no exato momento da compra funciona, mesmo que a sua rotina só envie a transação à Rapid horas depois.

## Próximos passos

- [Instalar o snippet](https://doc.rapidchargeback.com/canais/capture/instalar-o-snippet/)
- [Enviar evento pelo navegador](https://doc.rapidchargeback.com/canais/capture/enviar-evento-navegador/)
- [Enviar evento pelo servidor](https://doc.rapidchargeback.com/canais/capture/enviar-evento-servidor/)