Documentação ANBD-GENESIS

Visão geral

O que é o ANBD-GENESIS

O ANBD-GENESIS é uma infraestrutura de decisão adaptativa entregue como API. Você envia um evento — um texto, uma solicitação, um sinal de negócio — e recebe, em milissegundos, uma decisão auditável: EXECUTAR, REAVALIAR, ESCALAR, ABSTER ou RECUPERAR, acompanhada de um nível de confiança explícito e da justificativa completa do racional.

Internamente, o motor representa cada padrão como um hypervector binário (Vector Symbolic Architecture) e aprende continuamente a partir do próprio uso, ajustando força e confiança dos padrões a cada novo evento e feedback — sem pipeline de re-treinamento manual. A arquitetura é multi-tenant desde a concepção: dados, histórico e credenciais de cada cliente ficam completamente isolados.

Autenticação

Chave de API (X-API-Key)

Toda rota de cliente é autenticada pelo cabeçalho X-API-Key, recebido no momento da criação da conta (POST /v1/signup). A chave é exibida uma única vez — o servidor armazena apenas o hash SHA-256 dela, nunca o valor em texto puro, e ela não pode ser recuperada posteriormente.

Requisições sem X-API-Key, ou com uma chave inválida/revogada, recebem 401 Unauthorized. Rotas administrativas usam um cabeçalho separado, X-Admin-Key, restrito à equipe operadora da plataforma.

Endpoint principal

Avaliar um evento

Envia um evento para o motor e recebe a decisão correspondente, com justificativa e métricas de confiança.

Parâmetros de entrada

Exemplo de requisição

Exemplo de resposta

Ações possíveis

Confiança e justificativa

confidence_level resume o nível de confiança em três faixas (BAIXA, MEDIA, ALTA), enquanto confidence_score, principal_score, secondary_score e novelty trazem os valores numéricos que compuseram a decisão. O campo rationale retorna a explicação passo a passo do racional — a base da trilha de auditoria de cada decisão.

Contas

Criar uma conta

Cria um novo tenant no plano Free e retorna a chave de API correspondente.

Contato

Enviar mensagem de contato

Usado pelo formulário de contato do site. Salva a mensagem no banco e dispara uma notificação por e-mail.

Assinaturas

Checkout e upgrade de plano

Gera uma sessão de checkout do Stripe para o plano informado (starter, growth, scale, private, secure, compliant, agent_safe, enterprise_secure ou private_full) e retorna a URL de pagamento para redirecionamento do cliente. Os planos anteriores (loja, pro, enterprise e enterprise_corporativo) continuam aceitos.

A ativação do novo plano acontece de forma assíncrona, via webhook do Stripe, após a confirmação do pagamento.

Assinaturas

Webhook do Stripe

Endpoint interno, configurado diretamente no painel do Stripe, que recebe eventos de checkout e assinatura. A requisição é validada pela assinatura enviada no cabeçalho Stripe-Signature; eventos de conclusão de checkout atualizam automaticamente o plano do tenant correspondente.

Autoatendimento

Painel do cliente

Toda conta tem acesso a um painel de gerenciamento em /dashboard, onde é possível acompanhar o uso do plano, consultar o histórico auditável de decisões e gerenciar a assinatura — sem precisar entrar em contato com o suporte. Basta acessar com a chave de API recebida no cadastro. O painel também funciona instalado como aplicativo (PWA) no celular.

Meu resultado: em /valor (botão “Ver meu resultado” no painel) você vê quanto o ANBD protegeu em R$, as decisões que aguardam a sua aprovação e pode aprovar ou recusar cada uma com um toque. Para o valor em R$ aparecer, envie o campo amount (valor do pedido) no /v1/decide.

Soluções e simulação: em /solucoes você ativa pacotes prontos de política (anti-chargeback, anti-fraude, reembolso, crédito B2B, atendimento), com prévia antes de aplicar e possibilidade de desfazer em POST /v1/me/policy/rollback. Também pode enviar um arquivo com até 500 pedidos antigos e ver o que o ANBD teria decidido, sem alterar nada na sua conta (POST /v1/me/simulate/historical).

Aprendizado: o ANBD aprende o padrão dos seus pedidos. No começo, quando ainda não conhece o padrão, ele pede a sua confirmação em quase tudo, e isso é esperado. Cada resultado informado (pela fila ou por POST /v1/me/webhook/inbound) o ensina. Em /solucoes você também pode importar pedidos antigos marcados como fraude ou normais para ele nascer com experiência; esse treino pode ser desfeito. O estado do aprendizado aparece em GET /v1/me/aprendizado.

Consultar comprador: com a rede de sinais ligada, POST /v1/me/trust-score (ou o cartão em /solucoes) informa se outras lojas já reportaram o comprador, com pontuação de 0 a 100 e recomendação (aprovar, analisar ou bloquear). A rede funciona na base da troca: para consultar, a sua loja também reporta fraudes confirmadas com POST /v1/network/report. Só um código irreversível dos dados é guardado, e você pode retirar um reporte com POST /v1/network/retract.

Webhooks nos dois sentidos: informe o resultado real de um pedido com POST /v1/me/webhook/inbound (decision_id e resultado: bom ou ruim) e reenvie uma notificação perdida com POST /v1/me/webhook/replay/{decision_id}.

Consultar uso e limite do plano

Retorna o plano atual, o limite de requisições/minuto, quantas requisições já foram feitas e a última atividade registrada.

Histórico de decisões

Lista as últimas decisões tomadas pelo motor para o tenant autenticado, com ação, nível de confiança e latência — base para auditoria interna. limit aceita até 100 (padrão 20).

Portal de cobrança

Gera um link temporário para o Portal de Cobrança do Stripe, onde o próprio cliente troca de plano, atualiza o cartão e baixa faturas. Disponível apenas após a primeira assinatura paga (campo has_billing em /v1/me/usage indica se já está liberado).

Painel do cliente

Webhooks de saída

Em vez de ficar consultando /v1/me/decisions repetidamente, seu sistema pode ser avisado automaticamente sempre que o motor decidir ESCALAR ou ABSTER — os dois casos em que, por definição, uma decisão humana ou um processo à parte é necessário.

Corpo: {"webhook_url": "https://seusite.com/anbd-webhook"}. A URL precisa ser HTTPS. A resposta traz um webhook_secret mostrado uma única vez — guarde-o, ele é usado para validar a assinatura de cada notificação recebida. Chamar este endpoint de novo substitui a URL e gera um novo segredo, invalidando o anterior.

Consulta se há um webhook configurado e qual URL está registrada (o segredo nunca é reexibido).

Remove o webhook configurado.

Cada notificação é uma requisição POST para sua URL, com o corpo em JSON (campos event, tenant_id, decision_id, action, confidence_level, confidence_score, novelty, timestamp) e um cabeçalho X-ANBD-Signature: sha256=<hmac> — o HMAC-SHA256 do corpo bruto usando seu webhook_secret. Valide essa assinatura antes de confiar no conteúdo. O envio roda em segundo plano com timeout curto: uma falha de entrega nunca afeta a resposta de /v1/decide, e não há reenvio automático em caso de falha ainda.

Segunda onda — 09/09/2026

Risk-Adaptive Decision Thresholds

O campo opcional risk_level em /v1/decide aceita "baixo", "medio" (padrão) ou "alto". Quanto maior o risco, maior a confiança exigida para o motor autorizar EXECUTAR automaticamente — um risco alto pode rebaixar uma decisão de EXECUTAR para REAVALIAR se a confiança não for suficiente para aquele nível de risco. ESCALAR e ABSTER nunca são rebaixados por esta camada.

Segunda onda — 09/09/2026

Decision Circuit Breaker

Camada automática de proteção, ativa por padrão. Monitora a taxa de ESCALAR/ABSTER de cada tenant numa janela recente de decisões (configurável via ANBD_CIRCUIT_BREAKER_WINDOW). Se a taxa ultrapassar o limite (ANBD_CIRCUIT_BREAKER_RATIO, padrão 60%), o breaker abre e força ESCALAR em toda decisão nova por um período de resfriamento (ANBD_CIRCUIT_BREAKER_COOLDOWN_SECONDS, padrão 120s), até o padrão normalizar.

Segunda onda — 09/09/2026

Policy Engine por tenant

Permite que cada tenant sobrescreva os limiares padrão do motor (threshold_baixa, threshold_alta, ambos de 0 a 100) e/ou force force_escalate_high_risk: true para que toda decisão com risk_level="alto" seja sempre escalada para um humano, independente da confiança calculada.

curl -X POST https://anbd-genesis-enterprise.onrender.com/v1/me/policy   -H "X-API-Key: SUA_CHAVE" -H "Content-Type: application/json"   -d '{"force_escalate_high_risk": true}'

Segunda onda — 09/09/2026

Decision Observability & Quality Monitoring

Métricas agregadas das últimas decisões deste tenant: distribuição por ação (decisoes_por_acao), confiança média, latência média, novidade média, estado atual do circuit breaker, e o snapshot de qualidade — média do reward_feedback recebido, com percentual de feedback positivo/negativo e um status geral (saudavel, atencao ou degradado).

Segunda onda — 09/09/2026

Decision Simulation Mode

Campo opcional simulate: true em /v1/decide. A decisão é calculada e retornada normalmente (a resposta traz "simulated": true), mas nenhum webhook é disparado — ideal para testar o comportamento do motor sem gerar efeitos colaterais reais em produção.

Prioridade 2

Aprendizado por resultado real, Agent-Safe e políticas versionadas

POST /v1/me/outcome agora também reforça (correct: true) ou enfraquece (correct: false) o padrão que atendeu a decisão; a resposta traz o campo aprendizado. Com drift ativo o aprendizado fica congelado. Desfaça com POST /v1/me/learning/rollback (um critério: learning_id, decision_id, last_n ou since); o histórico fica em GET /v1/me/learning.

Agent-Safe: envie amount e agent_id em /v1/decide. Na política (/v1/me/policy), human_approval_above transforma EXECUTAR em ESCALAR acima do valor, deny_above bloqueia (ABSTER) e allowed_agents libera só os agentes listados (os demais viram ESCALAR). Se a política tem limite de valor e amount não vem, o motor escala.

Versões: cada POST /v1/me/policy gera uma versão (GET /v1/me/policy/versions); POST /v1/me/policy/rollback com {"version": N} volta a ela criando uma nova versão. Explicação: GET /v1/me/decisions/{id}/explain mostra a ação do motor, a ação final, as etapas que a mudaram e o resultado real. O verificador independente e o modo borda estão no anbd_cli.py.

Segunda onda — 09/09/2026 · não ativo por padrão

Rust Acceleration & Event-Driven Architecture

Duas camadas têm apenas a interface de código pronta, desligadas por padrão (ANBD_RUST_ACCEL_ENABLED=false e ANBD_EVENT_DRIVEN_ENABLED=false): aceleração nativa via extensão Rust para operações vetoriais de alto volume, e processamento assíncrono via message broker (fila/streaming) em vez de HTTP síncrono. Ambas dependem de infraestrutura externa ainda não contratada — um toolchain Rust publicado como dependência do serviço, e um broker gerenciado (Redis, SQS ou similar), respectivamente. Sem essas peças, o sistema continua operando normalmente em Python puro e HTTP síncrono.

Governança · ativa

Governance Layer

Camada pós-decisão, aditiva e opt-in (ANBD_GOVERNANCE_ENABLED=true): policy-as-code, redação de PII e envelope de evidência com hash encadeado.

Terceira onda · 09/10/2026

Aprendizado com resultado real e auditoria verificável

Camadas opcionais, ligadas por configuração do ambiente e desativadas por padrão. Elas aprendem com o resultado real das decisões e só podem rebaixar uma ação (por exemplo, de EXECUTAR para REAVALIAR ou ESCALAR); nunca tornam o motor mais permissivo, a menos que isso seja habilitado explicitamente. Quando ativas, /v1/decide passa a devolver dois campos extras: calibrated_confidence (probabilidade calibrada, 0 a 1, ou null antes de haver resultados suficientes) e drift_alert.

Informar o resultado de uma decisão

Envie se a ação proposta estava correta (true: sem chargeback, humano de acordo) ou errada (false). Vale para decisões executadas e escaladas. Cada decision_id aceita um único resultado. O aprendizado de cada cliente é isolado: um cliente nunca afeta a calibração de outro.

Informe o resultado o quanto antes: o bandit aprende só com as 50.000 decisões mais recentes mantidas em memória pelo serviço. Um resultado informado muito depois (ou após um reinício do serviço) ainda calibra a confiança, mas já não alimenta o bandit.

422 se o decision_id for desconhecido ou já tiver resultado; 404 se as camadas de aprendizado estiverem desativadas. A calibração começa com pelo menos 40 resultados que incluam acertos e erros; o bandit só atua após 200 resultados. O estado do aprendizado (v7) aparece em GET /v1/me/observability.

Checkpoint de auditoria assinado

Devolve a raiz de uma árvore Merkle construída sobre os record_hash das decisões do dia (UTC), com a quantidade de registros, a verificação da cadeia de hashes (chain_ok) e uma assinatura Ed25519. Sem date, usa o dia atual. Guarde os checkpoints: eles são a prova de integridade de cada dia.

Prova de inclusão de uma decisão

Devolve o record_hash da decisão, o caminho Merkle (proof) e o checkpoint assinado do dia. Um terceiro confere sem ver o resto do histórico: (1) folha = SHA-256(0x00 + bytes do record_hash); (2) a cada passo, nó = SHA-256(0x01 + esquerda + direita), conforme o lado indicado ("L" ou "R"); (3) o resultado deve ser igual à merkle_root; (4) a assinatura vale sobre o JSON canônico do checkpoint sem o campo signature (chaves ordenadas, sem espaços, UTF-8).

Chave pública de verificação

Endpoint público com a chave Ed25519 usada para assinar os checkpoints. Cada checkpoint também traz a própria public_key, então os já emitidos continuam verificáveis mesmo depois de uma troca de chave.

Painel do cliente

Exportação de auditoria (CSV)

Baixa o histórico de decisões deste tenant em um arquivo .csv (colunas: decision_id, timestamp, action, confidence_level, confidence_score, novelty, latency_ms, rationale), pronto para abrir em Excel/Planilhas Google ou anexar a um relatório de auditoria/compliance. Parâmetro opcional ?limit= (padrão 1000, máximo 5000). Pensado para consultas pontuais — para consumo automatizado e de alto volume, use /v1/me/decisions (JSON, paginação por limit).

Painel do cliente

Dossiê de chargeback (a partir do plano Starter)

Gera o dossiê de evidências de uma decisão (justificativa, etapas e prova de integridade), imprimível e pronto para anexar na disputa do chargeback. Parâmetro opcional ?order_id= para identificar o pedido.

Disponível a partir do plano Starter (R$ 497/mês). O plano Free tem o motor de decisão e o histórico no painel, mas não gera o dossiê: a rota responde 403 com a mensagem de upgrade.

Como liberar, passo a passo:

1. Abra o painel e entre com a sua chave de API.
2. Em “Últimas decisões”, toque em Dossiê de evidências. No Free abre o aviso de upgrade.
3. Toque em Fazer upgrade para Starter e conclua o pagamento no Stripe.
4. Volte ao painel (a ativação do plano pode levar alguns instantes) e toque de novo em Dossiê de evidências.

Prefere pela API? Use POST /v1/checkout?plan=starter com a sua X-API-Key e abra o checkout_url retornado. Contas criadas pela Shopify são cobradas pela Shopify: altere o plano pela página do app no admin da loja.

Operação

Limites de requisição por plano

O limite é aplicado por chave de API. Requisições sem X-API-Key seguem o limite do plano Free.

Dossiê de chargeback: não está incluído no plano Free. Starter e planos acima (e os planos anteriores já assinados) geram o dossiê. Veja como liberar.

Add-ons avulsos, somados ao plano base: Genesis Guard + R$ 1.497, Genesis Compliance + R$ 1.997, Genesis for Agents + R$ 1.797 e Priority Support + R$ 997 por mês. Os planos anteriores (Loja, Pro, Enterprise e Enterprise Corporativo) continuam ativos, com os mesmos limites, para clientes já assinados.

Operação

Códigos de erro comuns

Integração

Exemplos completos

Python

cURL

Referência

Boas práticas de uso

• Trate 429 com backoff exponencial em vez de repetir a chamada imediatamente.
• Sempre registre decision_id e rationale junto ao seu próprio log — eles formam a trilha de auditoria da decisão.
• Use reward_feedback para informar ao motor o resultado real de uma decisão anterior e acelerar o aprendizado contínuo.
• Trate ESCALAR e ABSTER como sinais de design, não como falhas — são o motor reconhecendo os próprios limites.
• Armazene a api_key em um cofre de segredos; ela não pode ser recuperada caso perdida, apenas substituída.
• Para cargas sensíveis, avalie o endpoint cifrado ponta a ponta (envelope X25519 + AES-256-GCM) em vez do canal padrão.

Referência

Segurança e isolamento multi-tenant

O campo isolation_mode em GET /v1/me/usage indica o modo ativo do tenant: shared (banco compartilhado + RLS) ou dedicated (Database por Tenant).