Tipos e payload

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

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. 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
• Enviar evento pelo navegador
• Enviar evento pelo servidor