Pular para o conteúdo
FingerTrackIDFingerTrackID Docs
No ar em produção, em modo shadow: o FingerTrackID recomenda, o seu sistema decide.Status →

Entrega da implementação para o seu desenvolvedor ou IA

Use esta página como o roteiro de implementação para a equipe ou a IA que integra o seu produto. Cadastre sua empresa e sua aplicação e, depois, prepare o navegador e o backend juntos. Toda empresa segue este mesmo fluxo; não é necessário nenhum cliente de demonstração pré-configurado nem integração específica de um site. Quando um agente de IA de programação fizer o trabalho, forneça a ele também os arquivos de documentação e as regras de repositório para agentes de IA.

Comece em SHADOW: o FingerTrackID avalia e recomenda enquanto seu produto continua autenticando os usuários e executando as próprias decisões.

Dados emitidos

Seção intitulada “Dados emitidos”

Obtenha o que segue da configuração real e da entrega verificada do cadastro. Marque um dado ausente como impedimento; não o deduza de um exemplo, da configuração de outra empresa nem da URL da documentação.

Dado Onde ele entra
IDs da empresa/aplicação e ambiente Configuração da integração e referências de suporte
Arquivo privado aprovado do SDK, versão exata, SHA-256 e SHA-512 Baixado no console (Início › Configuração do SDK, ou Integração e saúde › Pacote do SDK Web); confira os dois hashes com os que o console mostra antes da instalação
Chave pública da aplicação (pub_app_…) Configuração do SDK de navegador; um localizador público
Origem HTTPS de coleta exata e origens permitidas do site Configuração do navegador e CSP; o domínio first-party ativo é obrigatório
Dois nomes/destinos CNAME exatos e valor TXT de titularidade atual Seu provedor de DNS; publique os registros emitidos e aguarde a verificação
Origem da API: https://api.fingertrackid.com (também mostrada no console como Endereço da API de risco, na etapa Credencial servidor a servidor) Configuração do backend; só a origem, exatamente como está escrita, não o servidor de exemplo do OpenAPI nem uma rota
key_id UUIDv7, capacidades habilitadas, limites de taxa e de rajada Configuração do backend; use o escopo da credencial emitida
Segredo HMAC recebido uma única vez no console, codificação hex Gerenciador de segredos do backend, direto do console; nunca forneça o valor a uma IA
Política ativa, release qualificado e o perfil de requisição em uso (v1.1, ou v1 e as jornadas dele) Interpretação esperada da resposta e o feature gate de produção
Acesso nominal ao console e confirmação da ativação Acesso humano, verificação de e-mail/autenticador obrigatória e registro operacional

A entrega padrão do Web SDK é um arquivo privado aprovado, baixado no console com o SHA-256 e o SHA-512 que o FingerTrackID registrou para ele. Esses digests não implicam uma assinatura independente. Não existe instalação por script: a distribuição por script não está habilitada (instalação).

Material HMAC nunca entra neste roteiro nem em um arquivo de configuração gerado. O FingerTrackID gera o segredo, e um administrador da empresa ou gestor de integração o recebe uma única vez no console e o guarda direto no gerenciador de segredos do backend; ele nunca é mostrado de novo. Enquanto o console mostrar a solicitação da credencial como Aguardando você receber o segredo, a assinatura real fica bloqueada; prepare apenas referências e testes com vetores sintéticos.

Configuração gerenciada antes da implementação

Seção intitulada “Configuração gerenciada antes da implementação”
  1. No Início do console, conclua Criar a aplicação com origens exatas do site, como https://app.yourcompany.com, e não com URLs individuais de /login ou /register.
  2. Conclua Configurar a coleta web com uma das origens da aplicação e o domínio-base que pertence a você, yourcompany.com. O coletor é collect.yourcompany.com, e o SDK coleta por ele em toda origem permitida da aplicação sob esse domínio (por exemplo, https://yourcompany.com e https://www.yourcompany.com); a lista é editada depois em Integração e saúde › Origens das páginas. O perfil web cooperativo padrão (COOPERATIVE_WEB_SHADOW_V1) produz recomendações MONITOR só de observação; a presença dele não demonstra detecção de fraude calibrada.
  3. Publique os registros DNS emitidos assim que a plataforma tiver preparado o vínculo first-party exato. Mantenha os dois CNAMEs como somente DNS. O valor TXT de titularidade não muda: se a janela de verificação da plataforma tiver expirado, Verificar agora a renova com o mesmo valor, sem solicitação ao FingerTrackID e sem mudança no DNS.
  4. Acompanhe a mesma solicitação enquanto a plataforma executa as etapas automáticas (release, política, admissão e domínio); o progresso da configuração diz quando uma etapa depende de você. Aguardando revisão não é configuração concluída; a etapa só está pronta quando o Início a mostra como Concluída. Se um trabalho em espera for cancelado, os artefatos já criados permanecem; uma solicitação cancelada não é uma reversão nem uma integração concluída.
  5. Conclua Credencial servidor a servidor, receba o segredo uma única vez com Receber segredo e guarde-o no gerenciador de segredos do backend; depois, confirme o key_id público, as permissões e a admissão de produção ativa. Novos clientes gerenciados começam com 5 requisições por segundo e rajada de 10; o console mostra o limite em vigor e como aumentá-lo (limites).
  6. Conclua Configuração do SDK assim que o domínio de coleta estiver ativo e obtenha o arquivo privado exato do SDK e os dados da integração. Prepare o código com os identificadores reais emitidos e vetores de assinatura sintéticos; habilite a coleta e as chamadas reais só depois da confirmação explícita de ativação da aplicação e das provas técnicas aplicáveis.

A ativação do SDK de navegador e a ativação da API assinada são confirmadas separadamente. Um coletor habilitado não dispensa o recebimento do segredo da credencial, a admissão nem a verificação de isolamento da autenticação/de runtime para as chamadas do seu backend.

Limite este roteiro a IDs públicos, registros DNS, hashes, origens e referências de ativação. Não inclua planos de infraestrutura privada, arquivos de credencial de nuvem, localizadores de segredo nem bytes HMAC.

Contratos públicos legíveis por máquina

Seção intitulada “Contratos públicos legíveis por máquina”

Baixe exatamente estes arquivos e preserve os diretórios relativos deles:

O documento OpenAPI de avaliação mantém o servidor de exemplo histórico, os identificadores de schema e a anotação de implementação planejada. Esses não são valores de ambiente emitidos nem prova de implantação; a origem da API de produção é https://api.fingertrackid.com. Os schemas/exemplos públicos continuam sendo as fontes exatas do contrato, e não uma aproximação. Leia juntas as páginas de autenticação, requisição, resposta, erros e regras de nova tentativa.

Integração no navegador

Seção intitulada “Integração no navegador”
  1. Confira e instale o pacote privado do SDK. Inicialize-o só em código de navegador, com uma cópia do SDK e um cliente para o ciclo de vida atual do documento/da conta.
  2. Depois de qualquer consentimento aplicável, prepare o contexto na primeira intenção no formulário da ação avaliada (foco ou pointer-down, nunca no carregamento da página) com createActionContextHelper; ele só coleta de novo quando a coleta sairia da janela de evidência (60 ou 300 segundos) antes da sua margem, quando a sessão dela terminou, depois de consultas recusadas repetidas ou uma vez por página depois de uma limitação transitória; enquanto os contextos de evento estiverem indisponíveis, ele adiciona no máximo uma coleta a cada 300 segundos (etapas e motivos); siga o ciclo de vida do SDK. Em um login com MFA, o contexto vai junto com o envio do MFA. Se o login redirecionar para o Google ou outro provedor, siga login com Google, OAuth e outros redirecionamentos. Páginas de login, de cadastro e de recuperação de senha podem ser locais de coleta. No v1.1, cada momento que seu backend avalia recebe a própria etiqueta (signup, password_recovery…); no v1, eles não são jornadas adicionais. Não leia nem envie ao SDK valores de formulário, senhas, códigos de recuperação nem referências de identidade escolhidas pelo navegador.
  3. Para cada nova ação de negócio que o backend vai avaliar, obtenha um contexto de ação retido no envio dela, esperando no máximo o seu próprio teto e nunca abortando o SDK; com o SDK 0.3.0, o take() do helper faz isso e nunca rejeita. Uma falha do SDK, da rede ou do contexto precisa deixar a sua operação de negócio normal funcionando.
  4. Passe só o token capturado e o expiresAt dele, ou null, na requisição de negócio autenticada e protegida contra CSRF que você já tem; o backend envia null se o token estiver para expirar. Repita a mesma ação com o mesmo handle e o mesmo resultado capturado, inclusive null. Não colete de novo nem substitua um token para mudar uma avaliação existente.
  5. Mantenha o cliente do documento vivo até o seu backend responder: fechá-lo antes de a avaliação ser armazenada invalida o contexto. Mantenha-o fora de componentes de página que são desmontados no envio e segure a navegação de um formulário clássico até o contexto se resolver ou o seu teto acabar; preserve os prazos originais.
  6. No logout/na troca de conta, feche o cliente e descarte os handles antes de reinicializar. Nunca atrase o logout para terminar uma coleta opcional nem persista handles/tokens do SDK em armazenamento.
  7. Mantenha a sua origem de coleta fora da propagação de trace da instrumentação da página: um cabeçalho de requisição a mais faz toda requisição do SDK falhar (cabeçalhos de tracing).

O navegador nunca assina requisições S2S nem escolhe a identidade confiável de pessoa/conta. Use a interface aprovada do SDK em vez de implementar você mesmo os endpoints de transporte dele.

Integração no backend

Seção intitulada “Integração no backend”

Integrações novas usam a requisição v1.1 (event-assessment-request.v1.1): você dá nome a cada momento avaliado com a sua própria etiqueta (login, saque, pix_transfer…), e toda etiqueta é avaliada da mesma forma. Os modelos de jornada sugerem etiquetas e pontos de chamada para momentos comuns. A produção aceita a requisição v1.1 com a sua tag.

A requisição v1 continua suportada, sem mudança. Ela tem exatamente LOGIN, WITHDRAWAL e TRADE, com as ações e contextos fechados delas; não invente REGISTER nem PASSWORD_RECOVERY nem rotule como LOGIN uma operação não relacionada. Uma integração que já está no v1 migra chamada por chamada (migrando do v1 para o v1.1).

Em uma primeira integração de login, use a etiqueta login (no v1: LOGIN com action: "LOGIN_ATTEMPT") depois que o backend concluir a autenticação real e o MFA exigido e derivar o subject_ref da pessoa e o account_ref da conta como pseudônimos com chave estáveis (referências de pessoa e de conta). Envie a avaliação imediatamente: o contexto do navegador desse login precisa ser armazenado antes do expiresAt dele. Uma sessão provisória ou um pedido de OTP não é autenticação concluída. Preserve a resposta de login existente mesmo se o FingerTrackID estiver indisponível.

Para cada avaliação lógica:

  1. Derive no backend occurred_at, as referências de identidade (o mesmo par subject_ref e account_ref para a mesma pessoa e a mesma conta em toda chamada), external_event_id e idempotency_key. Nunca aceite valores do navegador como autoridade para esses campos.
  2. Valide a requisição fechada e serialize-a uma única vez. Guarde os bytes originais exatos e o token, inclusive null, com a operação lógica.
  3. Para cada tentativa de envio, gere um novo request_id UUIDv7, um timestamp atual e uma assinatura sobre esses mesmos bytes. Decodifique a chave hex de 64 caracteres nos 32 bytes dela antes do HMAC.
  4. Valide a avaliação ou o Problem retornado. Confira o evento esperado e a tag dele (v1.1) ou a journey (v1), e preserve os campos de política/release/recomendação retornados.
  5. Siga a matriz de nova tentativa. Um resultado desconhecido é reconciliado pelo mesmo POST e pelos bytes originais; um 410 definitivo nunca dispara IDs de operação regenerados.

Contexto ausente significa evidência do navegador ausente. Isso não garante INCONCLUSIVE, 201, uma nota nem sucesso. trust_score: null significa sem nota, nunca um padrão de 0 ou 100. O cliente decide e executa a ação; o FingerTrackID nunca aplica um bloqueio no seu produto.

Feedback e verificação no console

Seção intitulada “Feedback e verificação no console”

Quando a sua credencial tiver as capacidades ativas exigidas, use os contratos de ação do cliente e de desfecho para informar a sua decisão real e a evidência posterior. Um bloqueio, um cancelamento ou uma nota não é confirmação de fraude. Não declare o alinhamento que o FingerTrackID precisa derivar nem sobrescreva a verdade histórica com a política mais recente.

Use o console para inspecionar Acessos, Integração e saúde, Configuração de risco, Auditoria e Uso, de acordo com o seu papel. O uso é uma estimativa a partir de registros imutáveis, não uma fatura nem uma métrica de precisão de fraude.

Revisão e ativação

Seção intitulada “Revisão e ativação”

Mostre o diff da sua integração e as verificações sintéticas do vetor de assinatura, da validação de schema, do comportamento em duplicata/nova tentativa, de resultados desconhecidos/expirados, de falha na inicialização do SDK/no contexto síncrono, de rede/contexto indisponível, de logout/troca de conta e do posicionamento correto da autenticação no servidor. Demonstre que o seu produto continua funcionando quando a integração está desabilitada ou indisponível.

O FingerTrackID confirma os dados efetivos, o domínio, a instalação da credencial, a admissão ativa, a política/o release e as provas aplicáveis antes de habilitar o tráfego real. Guarde os IDs de requisição/operação, os IDs de correlação, os timestamps e os códigos de erro públicos para o suporte. Nunca registre em log tokens, segredos, cookies, dados pessoais nem payloads completos.

Antes de entrar no ar, leia as orientações de integração: sempre envie a avaliação (com null quando não houver contexto), use fail-open com erros visíveis, analise o período em modo shadow com feedback e teste em produção sem sandbox. Para a sua política de privacidade, veja dados coletados e tratamento.

Termine com o checklist de integração.