Modelos de jornada

Um modelo de jornada é uma orientação para um momento comum do seu produto: quando o seu backend chama POST /v1/assessments, quais referências pseudônimas enviar e o que olhar no console depois. Os modelos existem só nesta documentação e no guia de integração do console. Nada deles fica armazenado, e eles não têm efeito na avaliação: toda requisição v1.1 executa o mesmo comportamento interno, por isso a mesma evidência dá a mesma nota com qualquer etiqueta (jornadas e etiquetas).

A etiqueta sugerida é só uma sugestão. Você pode enviar qualquer etiqueta válida no lugar dela, por exemplo saque em vez de withdrawal; o console mostra a etiqueta que você envia.

A requisição v1.1

Os modelos descrevem a requisição v1.1, que a produção aceita. Uma integração que continua no v1 mantém as suas três jornadas fixas, sem mudança.

Os dez modelos

Modelo	Etiqueta sugerida	Quando o seu backend chama	subject_ref	account_ref
Criação de conta	signup	Depois que o seu backend valida o formulário, antes de ativar a conta	Recomendado (um pseudônimo novo)	Recomendado (um pseudônimo novo)
Login	login	Depois que o seu backend confere a credencial, antes de emitir a sessão	Recomendado quando o usuário está identificado	Recomendado com subject_ref
Recuperação de senha	password_recovery	Quando a senha é efetivamente trocada, não quando o link de redefinição é solicitado	Recomendado só se o seu backend já identificou o usuário; nunca o e-mail	null
Verificação em duas etapas	mfa_challenge	Quando o seu backend valida o código	Recomendado	Recomendado
Alteração de cadastro	profile_change	Quando o seu backend salva um novo e-mail, telefone ou endereço	Recomendado	Recomendado
Depósito	deposit	Quando o seu backend gera a cobrança (QR Code, boleto)	Obrigatório	Obrigatório
Saque	withdrawal	Quando o usuário confirma, antes de o seu backend liquidar	Obrigatório	Obrigatório
Transferência ou Pix	pix_transfer	Quando o usuário confirma, antes de o seu backend liquidar	Obrigatório	Obrigatório
Ordem de negociação	trade	Quando o seu backend aceita a ordem, antes de roteá-la	Obrigatório	Obrigatório
Finalização de compra	checkout	Quando o usuário confirma o pagamento, antes de o seu backend capturá-lo	Recomendado	Opcional

account_ref exige subject_ref: quando um modelo marca a referência da conta como obrigatória, a referência da pessoa também é obrigatória, e um modelo que recomenda account_ref o recomenda junto com subject_ref. Os dois são pseudônimos que o seu backend cria; nunca envie e-mail, documento fiscal, telefone, nome ou número de conta. Envie o mesmo account_ref com o mesmo subject_ref em toda chamada: uma conta fica vinculada à pessoa com que foi enviada pela primeira vez, e outro subject_ref retorna 409 binding-conflict (referências de pessoa e de conta).

Os itens do console sobre uma conta (um dispositivo novo para a conta, outras contas nos mesmos dispositivos, eventos com a mesma etiqueta na mesma conta) precisam de account_ref: sem ele, mostram Conta não informada pelo sistema da empresa. O histórico da conta começa no primeiro acesso dela: com uma coleta do navegador concluída, esse acesso mostra Primeira vez: ainda sem histórico, e sem ela, Sem coleta concluída do navegador. Um acesso posterior avalia Dispositivo novo para esta conta só quando um acesso anterior da mesma conta nos últimos 90 dias também teve uma coleta do navegador cuja instalação do navegador foi vinculada; depois de mais de 90 dias sem um acesso assim, ele mostra Primeira vez de novo (referências de pessoa e de conta).

Regras que todo modelo repete

• A etiqueta não carrega dado pessoal: nada de e-mail, documento fiscal, nome, ID de usuário ou chave Pix. Ela tem no máximo dez dígitos no total.
• recommended_action é um conselho, não uma ação tomada: o seu sistema decide e age.
• A mesma evidência dá a mesma nota em todos os modelos e com todas as etiquetas.
• Uma nova tentativa repete o corpo inteiro, inclusive a etiqueta. Mudar qualquer campo, exceto deadline_ms, com o mesmo external_event_id ou o mesmo idempotency_key é 409 idempotency-conflict; uma nova tentativa que muda só deadline_ms é a mesma operação e responde 200.

Um modelo nunca traz valor, moeda, ordem, beneficiário, prazo próprio, fallback, política, peso, provedor, aplicabilidade de sinal, cota, preço nem classe interna. O corpo v1.1 não tem campo para nenhum deles.

Modelo por modelo

Cada exemplo é um corpo v1.1 sintético, formatado para leitura. Na chamada real, envie o JSON compacto que JSON.stringify(object) produz e substitua o token pelo que o Web SDK devolveu para aquela ação, ou por null quando não houver nenhum.

Criação de conta

• Etiqueta sugerida: signup
• Quando chamar: depois que o seu backend valida o formulário, antes de ativar a conta.
• Referências: subject_ref recomendado (um pseudônimo novo); account_ref recomendado (um pseudônimo novo).
• O que olhar no console: DEVICE_MULTI_USER, BOT_AUTOMATION e EMULATED_ENVIRONMENT; outras contas vistas no mesmo dispositivo (precisa de account_ref); eventos com a mesma etiqueta no mesmo dispositivo (muitos cadastros a partir de um só dispositivo).

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_signup_0001",
  "idempotency_key": "idem_evt_signup_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_signup_0001",
  "tag": "signup",
  "deadline_ms": null
}

Login

• Etiqueta sugerida: login
• Quando chamar: depois que o seu backend confere a credencial, antes de emitir a sessão.
• Referências: subject_ref recomendado quando o usuário está identificado; account_ref recomendado, sempre junto com subject_ref.
• O que olhar no console: BOT_AUTOMATION e BROWSER_SPOOFING; NETWORK_TOR, NETWORK_VPN e NETWORK_HOSTING; um dispositivo novo para a conta (precisa de account_ref).

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_login_0001",
  "idempotency_key": "idem_evt_login_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_login_0001",
  "tag": "login",
  "deadline_ms": null
}

Recuperação de senha

• Etiqueta sugerida: password_recovery
• Quando chamar: quando a senha é efetivamente trocada, não quando o link de redefinição é solicitado.
• Referências: subject_ref recomendado só se o seu backend já identificou o usuário; nunca o e-mail; account_ref null.
• O que olhar no console: NETWORK_TOR, NETWORK_VPN e NETWORK_HOSTING; PRIVATE_BROWSING; dispositivos vistos para a pessoa.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_password_recovery_0001",
  "idempotency_key": "idem_evt_password_recovery_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": null,
  "event_context_token": "ect_password_recovery_0001",
  "tag": "password_recovery",
  "deadline_ms": null
}

Verificação em duas etapas

• Etiqueta sugerida: mfa_challenge
• Quando chamar: quando o seu backend valida o código.
• Referências: subject_ref recomendado; account_ref recomendado.
• O que olhar no console: continuidade com o dispositivo do login: um dispositivo novo para a conta (precisa de account_ref) ou um cookie de dispositivo perdido.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_mfa_challenge_0001",
  "idempotency_key": "idem_evt_mfa_challenge_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_mfa_challenge_0001",
  "tag": "mfa_challenge",
  "deadline_ms": null
}

Alteração de cadastro

• Etiqueta sugerida: profile_change
• Quando chamar: quando o seu backend salva um novo e-mail, telefone ou endereço.
• Referências: subject_ref recomendado; account_ref recomendado.
• O que olhar no console: um dispositivo novo para a conta (precisa de account_ref); NETWORK_TOR, NETWORK_VPN e NETWORK_HOSTING.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_profile_change_0001",
  "idempotency_key": "idem_evt_profile_change_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_profile_change_0001",
  "tag": "profile_change",
  "deadline_ms": null
}

Depósito

• Etiqueta sugerida: deposit
• Quando chamar: quando o seu backend gera a cobrança (QR Code, boleto).
• Referências: subject_ref obrigatório; account_ref obrigatório.
• O que olhar no console: um dispositivo novo para a conta; NETWORK_TOR, NETWORK_VPN e NETWORK_HOSTING; eventos com a mesma etiqueta na mesma conta. Os itens de conta precisam de account_ref, que este modelo exige.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_deposit_0001",
  "idempotency_key": "idem_evt_deposit_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_deposit_0001",
  "tag": "deposit",
  "deadline_ms": null
}

Saque

• Etiqueta sugerida: withdrawal
• Quando chamar: quando o usuário confirma, antes de o seu backend liquidar.
• Referências: subject_ref obrigatório; account_ref obrigatório.
• O que olhar no console: um dispositivo novo para a conta; NETWORK_TOR, NETWORK_VPN e NETWORK_HOSTING; eventos com a mesma etiqueta na mesma conta e no mesmo dispositivo.

O que um saque v1.1 não mostra

A requisição v1.1 não traz valor nem beneficiário, por isso os itens de contexto que dependem deles (beneficiários compartilhados, beneficiários por dispositivo, contas por beneficiário e o valor sacado em 24 horas) voltam como não avaliados, com um motivo que diz que a requisição não os traz. Se você precisa deles hoje, integre o saque com a jornada v1 WITHDRAWAL, que mantém journey_context sem mudança.

{
  "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": "withdrawal",
  "deadline_ms": null
}

Transferência ou Pix

• Etiqueta sugerida: pix_transfer
• Quando chamar: quando o usuário confirma, antes de o seu backend liquidar.
• Referências: subject_ref obrigatório; account_ref obrigatório.
• O que olhar no console: o mesmo que para um saque.

O que um saque v1.1 não mostra

A requisição v1.1 não traz valor nem beneficiário, por isso os itens de contexto que dependem deles (beneficiários compartilhados, beneficiários por dispositivo, contas por beneficiário e o valor sacado em 24 horas) voltam como não avaliados, com um motivo que diz que a requisição não os traz. Se você precisa deles hoje, integre o saque com a jornada v1 WITHDRAWAL, que mantém journey_context sem mudança.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_pix_transfer_0001",
  "idempotency_key": "idem_evt_pix_transfer_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_pix_transfer_0001",
  "tag": "pix_transfer",
  "deadline_ms": null
}

Ordem de negociação

• Etiqueta sugerida: trade
• Quando chamar: quando o seu backend aceita a ordem, antes de roteá-la.
• Referências: subject_ref obrigatório; account_ref obrigatório.
• O que olhar no console: veja ordens, uma avaliação para cada.

Uma avaliação por ordem, sem dados da ordem. O fluxo completo e as observações sobre custo e capacidade estão em ordens, uma avaliação para cada.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_trade_0001",
  "idempotency_key": "idem_evt_trade_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_trade_0001",
  "tag": "trade",
  "deadline_ms": null
}

Finalização de compra

• Etiqueta sugerida: checkout
• Quando chamar: quando o usuário confirma o pagamento, antes de o seu backend capturá-lo.
• Referências: subject_ref recomendado; account_ref opcional.
• O que olhar no console: BOT_AUTOMATION, BROWSER_SPOOFING e EMULATED_ENVIRONMENT; eventos com a mesma etiqueta no mesmo dispositivo.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_checkout_0001",
  "idempotency_key": "idem_evt_checkout_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": null,
  "event_context_token": "ect_checkout_0001",
  "tag": "checkout",
  "deadline_ms": null
}

Como escolher as suas etiquetas

• Nomeie o momento, não o resultado: withdrawal, não withdrawal_blocked.
• Mantenha uma etiqueta por momento. O console nunca junta duas etiquetas, por isso saque e withdrawal são duas linhas em todo relatório.
• Mantenha a etiqueta estável entre as versões do seu produto: uma etiqueta renomeada começa uma linha nova no console.