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
Seção intitulada “Campos do evento”| Campo | Tipo | Limite | Obrigatório |
|---|---|---|---|
type | string (enum) | ver tabela abaixo | Sim |
order_ref | string ou número | 100 caracteres | Sim |
event_id | string ou número | 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
Seção intitulada “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:
- uma transação com
external_idigual aoorder_ref - se não achar, uma transação com
order_numberigual aoorder_ref - se ainda não achar, nas transações com
external_sourceshopify, oorder_reftambém vale sem o#da frente (1001acha#1001, e#1001acha1001) e pelo GID do pedido (gid://shopify/Order/<id>ougid://shopify/OrderIdentity/<id>acha o<id>)
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. Para corrigir, reenvie pelo servidor com o mesmo event_id e o order_ref certo (ver Idempotência).
Espaços no começo e no fim são retirados. Número inteiro também é aceito e vira texto (1001 é o mesmo que "1001").
event_id
Seção intitulada “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 servidor, o reenvio com outro order_ref, ou depois do descarte, substitui o envio anterior; no navegador, o mesmo event_id é sempre tratado como repetição.
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
Seção intitulada “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
Seção intitulada “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
Seção intitulada “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, até 100 caracteres | checkout |
device_fingerprint | string, até 255 caracteres | 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:
- no canal navegador, cada tipo aceita só os campos que o snippet monta:
checkoutleva os quatro de identificação do aparelho, eterms_acceptance,access_logeusage_loglevam sóurl.note,carrier,tracking,latelngsão do canal servidor urlprecisa serhttpouhttps; outra coisa é descartada, sem erro. Parâmetros (?...) e âncora (#...) são retirados antes de gravar, então dado do comprador na URL não fica na evidência- no canal navegador,
urlde outro domínio que não o site de onde veio o evento também é descartada. Evento sem site de origem (semOriginnemReferer) só mantémurldos sites autorizados da loja; antes de haver site autorizado, aurldele é descartada latfora de -90 a 90 elngfora de -180 a 180 são descartados, sem errocarrieretrackingdedelivery_confirmationescanvão na defesa da disputa como transportadora e código de rastreio; vírgula separa mais de um valor. Com a entrega confirmada e datada, só valem a entrega e as leituras feitas até ela. A primeira leitura (scan) com um dos dois, feita depois da compra e antes da entrega confirmada, vira a data de envio- registro de acesso, uso, entrega ou leitura com data anterior à compra não entra como prova na defesa
- só valores escalares (string, número, booleano). Objeto e lista são descartados
device_idacima de 100 caracteres,device_fingerprintacima de 255 e os outros campos de texto acima de 512 respondem422 payload_too_large.device_idedevice_fingerprintaceitam número inteiro, gravado como textopayloadausente ou vazio é aceito, mas não entra como prova na defesa:terms_acceptance,access_log,usage_logedelivery_confirmationsem nenhum dado ficam gravados e não contam como aceite, acesso ou entrega. No canal navegador, em que esses tipos só levamurl, é o caso do evento semurlválida
O evento checkout
Seção intitulada “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 | não 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.
O canal servidor não grava IP porque o IP da chamada é o do seu servidor, não o do comprador. Mande o IP do comprador em ip_address ao criar a transação.
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. A identificação precisa ter sido feita no máximo 24 horas antes do evento e, no canal navegador, no mesmo site de onde ele veio. 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 identificação validada, o checkout do canal navegador não preenche aparelho nem IP e não gera registro de verificação, mas conta no painel como evento recebido quando a transação do pedido chega à Rapid. Os outros tipos (access_log, usage_log, terms_acceptance) viram registro normalmente, com ou sem fp_request_id.
Cada fp_request_id gera o registro de verificação de aparelho em uma transação só. Se o mesmo par chegar em outro pedido, esse pedido não ganha o registro de verificação, mas os campos de aparelho e IP dele são preenchidos como na tabela acima, só quando estão vazios.
Janela de correlação
Seção intitulada “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.