Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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

CampoTipoLimiteObrigatório
typestring (enum)ver tabela abaixoSim
order_refstring ou número100 caracteresSim
event_idstring ou número64 caracteresSim no navegador, opcional no servidor
payloadobjetover campos aceitosNão
captured_atstring (ISO 8601)-Não, e só o canal servidor usa
merchant_idstring (UUID)-Só no canal servidor

É 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
  3. se ainda não achar, nas transações com external_source shopify, o order_ref também vale sem o # da frente (1001 acha #1001, e #1001 acha 1001) e pelo GID do pedido (gid://shopify/Order/<id> ou gid://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").

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.

Quando o fato aconteceu, em ISO 8601.

CanalComportamento
Navegadorignorado. A Rapid registra o horário em que o evento chegou
Servidorusado 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.

ValorO que registraNavegadorServidor
checkoutFinalização da compra, com os dados do aparelhoSimSim
terms_acceptanceAceite de termos, política ou contratoSimSim
access_logAcesso ao produto ou à área logadaSimSim
usage_logUso efetivo do produto ou serviçoSimSim
delivery_confirmationEntrega confirmadaNãoSim
scanLeitura de código de rastreio em trânsitoNãoSim
delivery_gpsCoordenada da entregaNãoSim

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.

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

CampoTipoUsar em
device_idstring, até 100 caracterescheckout
device_fingerprintstring, até 255 caracterescheckout
fpstringcheckout, indica a origem da identificação (pro ou fallback)
fp_request_idstringcheckout, exigido para validar a identificação
urlstringterms_acceptance, access_log, usage_log
notestringqualquer tipo
carrierstringdelivery_confirmation, scan
trackingstringdelivery_confirmation, scan
latnúmerodelivery_gps
lngnúmerodelivery_gps

Regras:

  • no canal navegador, cada tipo aceita só os campos que o snippet monta: checkout leva os quatro de identificação do aparelho, e terms_acceptance, access_log e usage_log levam só url. note, carrier, tracking, lat e lng são do canal servidor
  • url precisa ser http ou https; 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, url de outro domínio que não o site de onde veio o evento também é descartada. Evento sem site de origem (sem Origin nem Referer) só mantém url dos sites autorizados da loja; antes de haver site autorizado, a url dele é descartada
  • lat fora de -90 a 90 e lng fora de -180 a 180 são descartados, sem erro
  • carrier e tracking de delivery_confirmation e scan vã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_id acima de 100 caracteres, device_fingerprint acima de 255 e os outros campos de texto acima de 512 respondem 422 payload_too_large. device_id e device_fingerprint aceitam número inteiro, gravado como texto
  • payload ausente ou vazio é aceito, mas não entra como prova na defesa: terms_acceptance, access_log, usage_log e delivery_confirmation sem nenhum dado ficam gravados e não contam como aceite, acesso ou entrega. No canal navegador, em que esses tipos só levam url, é o caso do evento sem url válida

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çãoNavegadorServidor
device_idnão gravagrava
device_fingerprintsó com identificação validadagrava
ip_addresssó com identificação validadanã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.

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.