Jornadas e etiquetas

No ar · modo shadowAPI v1.1 and v1

Uma jornada é o momento em que seu backend pede uma avaliação (POST /v1/assessments): um login, um saque, uma ordem. Não é uma página; o Web SDK faz a coleta em qualquer página onde a ação acontecer.

Há dois perfis de requisição na mesma rota, com a mesma autenticação HMAC:

Perfil	`schema_version`	Como o momento é nomeado
v1.1	`event-assessment-request.v1.1`	Uma `tag` livre, escolhida por você (`login`, `saque`, `pix_transfer`, `trade`…)
v1	`event-assessment-request.v1`	Uma de três jornadas fixas: `LOGIN`, `WITHDRAWAL` ou `TRADE`

Cada chamada escolhe o seu perfil pelo seu schema_version; não há nada a configurar por aplicação. Integrações novas devem usar o v1.1. Se você está no v1 hoje, veja como migrar do v1 para o v1.1.

A etiqueta do v1.1

tag é um slug que nomeia o ponto de chamada no seu sistema. Ela não tem cadastro, nem limite, nem ativação, nem lista a manter em sincronia com o FingerTrackID: envie-a em cada chamada.

Gramática: ^[a-z0-9][a-z0-9_]{0,63}$. Letras ASCII minúsculas, dígitos e sublinhado, de 1 a 64 caracteres, começando por uma letra ou um dígito. Não há normalização: Login, pix-transfer ou saque (com um espaço) são recusadas, não corrigidas.
No máximo dez dígitos no total. Onze ou mais dígitos são recusados, juntos ou separados (cpf_12345678901 e cpf_123_456_789_01 da mesma forma), porque esse é o formato de um documento fiscal ou de um número de telefone. Essa verificação não prova que a etiqueta está livre de dados pessoais: essa garantia é sua.
Sem dados pessoais. Nunca coloque na etiqueta um e-mail, documento fiscal, número de telefone, nome, ID de usuário, número de conta ou chave Pix. Uma etiqueta nomeia um momento do seu produto, nunca uma pessoa.
A etiqueta faz parte da identidade da operação. Uma nova tentativa precisa repetir o corpo inteiro, etiqueta incluída; o mesmo external_event_id ou idempotency_key com outra etiqueta é 409 idempotency-conflict.

O que a etiqueta muda, e o que não muda

A etiqueta organiza a sua leitura. No console, você filtra os acessos por etiqueta, vê o volume e o status de cada etiqueta, exporta a etiqueta e lê quantos eventos com a mesma etiqueta chegaram à mesma conta (quando você envia account_ref) ou ao mesmo dispositivo no último minuto, nos últimos cinco minutos e na última hora.

A etiqueta não muda a forma como o FingerTrackID avalia. Toda requisição v1.1 segue o mesmo comportamento interno, qualquer que seja a etiqueta:

a mesma evidência e a mesma política dão o mesmo status, a mesma nota e a mesma recomendação com qualquer etiqueta;
a faixa de deadline_ms é a mesma para toda etiqueta (250–5000 ms, padrão de 5000 ms quando null);
a etiqueta nunca seleciona uma política, um detector, um provedor, um fallback, uma cota nem um preço;
a etiqueta nunca aparece nas métricas, nos logs nem nos traces do FingerTrackID.

Escolha etiquetas que sejam úteis na leitura. Os modelos de jornada sugerem quando chamar, o que enviar e o que observar em dez momentos comuns; são apenas orientação e não têm efeito sobre a avaliação.

Exemplo

O corpo v1.1 não tem campo de valor, moeda, ordem nem beneficiário. O FingerTrackID avalia o dispositivo e o acesso; o seu sistema já tem a transação. Os itens de contexto que dependem de um valor ou de um beneficiário voltam como não avaliados para um evento v1.1, com um motivo que diz que a requisição não os traz.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_withdrawal_0001",
  "idempotency_key": "idem_evt_withdrawal_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_withdrawal_0001",
  "tag": "saque",
  "deadline_ms": null
}

O perfil v1

O perfil v1 tem três jornadas fixas. Cada uma define o action, quais referências são obrigatórias, o formato de journey_context e o orçamento técnico deadline_ms. Ele continua aceito, sem mudança, para as integrações que o usam.

Jornada	`action`	`subject_ref` e `account_ref`	`journey_context`	`deadline_ms` quando `null`	Faixa explícita
`LOGIN`	`LOGIN_ATTEMPT`	Podem ser `null`; `account_ref` exige `subject_ref`	`{}`	5000	250–5000
`WITHDRAWAL`	`WITHDRAWAL_REQUEST`	Ambos obrigatórios	`amount_minor`, `currency`, `beneficiary_ref`	1000	500–1000
`TRADE`	`TRADE_REQUEST`	Ambos obrigatórios	`{}`	750	250–750

`WITHDRAWAL`

amount_minor é um inteiro positivo na menor unidade da moeda — centavos para BRL: 150000 = R$ 1.500,00. Nunca um decimal.
currency é o código ISO 4217 em maiúsculas (^[A-Z]{3}$), e a moeda precisa estar na lista de permissões da política da sua aplicação.
beneficiary_ref é um pseudônimo opaco do beneficiário, criado pelo seu backend.

{ "amount_minor": 150000, "currency": "BRL", "beneficiary_ref": "beneficiary_789" }

`TRADE`

Uma ordem não dispara uma nova coleta nem uma consulta externa por ordem: ela reutiliza a evidência atual da sessão. No navegador, várias ordens podem vir da mesma coleta aceita, cada uma com o seu próprio contexto do evento (veja o SDK). No v1.1, o mesmo fluxo usa a etiqueta trade (ordens, uma avaliação para cada).

`deadline_ms`

É um orçamento técnico interno, contado a partir de quando a requisição entra no serviço. Um número só pode reduzir o padrão.
Não é um SLA. Ele não muda a nota nem a evidência e não faz parte da identidade da operação: mudar só o deadline_ms em uma nova tentativa mantém a mesma operação.
O timeout do seu cliente HTTP precisa somar a latência de rede ao orçamento. Para um LOGIN (v1) ou qualquer etiqueta v1.1 enviada com null, isso significa um timeout acima de cerca de 6 s (5000 ms mais a rede). Um corpo que assina deadline_ms explicitamente pode enviar qualquer valor até 5000, ou null; um corpo já assinado com 750 ou 1000 continua válido e mantém exatamente esse orçamento.

Ação quando não há nota

Quando a avaliação não termina em COMPLETED (INCONCLUSIVE, UNSCORABLE ou FAILED), a recomendação é MONITOR: para toda jornada v1 e para toda etiqueta v1.1.

MONITOR é uma contingência neutra. Não é uma nota favorável, nem uma autorização, nem uma ação tomada; o seu sistema continua decidindo o que fazer. recommendation_basis diz por que não há nota.

Avaliações criadas antes desta mudança podem trazer STEP_UP (LOGIN) ou REVIEW (WITHDRAWAL) sem nota, e o schema v1 ainda as aceita. Baseie seu código nos campos que você recebe (recommended_action, recommendation_basis, fallback_policy_version), não em uma tabela fixa. Nenhum estado sem nota recebe ALLOW.