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 (pro, enterprise ou enterprise_corporativo) e retorna a URL de pagamento para redirecionamento do cliente.

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.

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.

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).

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.

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