Nexus Brasil API

Resumo técnico

Plugin do NEXUS que consulta dados públicos brasileiros pela Brasil API sem exigir chave externa. Oferece CEP com geolocalização, CNPJ, bancos, validação local de CPF/CNPJ e conferência de endereço, com cache de 24 horas e histórico; artefatos de CEP e CNPJ também enriquecem a Intelligence Hub.

Escopo executado

• plugin.json — v1.0.0, categoria Dados & Validação, ícone lucide building com icon_bg #059669, icon.svg próprio.
• Registros: registerTab('brasil-api','Brasil API','building',tab.php,'Dados & Validação') e registerDoc('brasil-api','Brasil API','building',doc.md).
• 8 actions de API (plugin.php, via PluginManager::registerApiAction) — brasilapi_stats|cep|cnpj|bank|banks|address_check|cpf_validate|history; cep/cnpj/bank aceitam task_id e force.
• Tabela brasilapi_cache no load (brasilapi_install()): kind, query_key, status, payload_json, http_code, error, task_id, timestamps; UNIQUE kind+query_key; índice updated_at.
• Validação local: brasilapi_cpf_valid() (DV, rejeita repetidos) e brasilapi_cnpj_valid() (pesos 5-4-3-2/6-5-4-3-2) — sem consulta externa.
• HTTP: brasilapi_http_get() via cURL com timeout, follow location, UA próprio e SSL configurável (SSL_VERIFY).
• Cache: get com TTL 24h (BRASILAPI_CACHE_TTL) + put com upsert; fallback recria a tabela.
• Lookups: CEP v2 (/cep/v2/{cep}), CNPJ (/cnpj/v1/{cnpj}), banco COMPE (/banks/v1/{code}) e lista (/banks/v1).
• brasilapi_check_address() — heurística de match endereço × CEP (score/hits/match + cep_data).
• brasilapi_validate_cpf() — só DV local (Brasil API não consulta CPF).
• brasilapi_stats() e brasilapi_history() (paginado, limit ≤50).
• Enricher Intel Hub: brasilapi_intel_enrich (tipo cep/cnpj, prioridade 55) com signals ok/error, summary e dedupe.
• Slash (fastr.json): /cep, /brasilcnpj (alternativa ao OpenCNPJ), /banco.
• UI Alpine.js (tab.php, 251 linhas): badge API pública, stats, tabs Consulta/Bancos/CPF/Histórico, modos CEP/CNPJ/Endereço×CEP.

Stack e ferramentas

• PHP 8 (strict_types, sem framework) + MySQL 8 (tabela brasilapi_cache)
• cURL (timeout 12s, SSL configurável) + Brasil API pública (https://brasilapi.com.br/api, sem key)
• Alpine.js + Tailwind CSS (tab.php)
• Intelligence Hub (enricher cep/cnpj) + Fast Responses (slash /cep, /brasilcnpj, /banco)

Tags operacionais

• Brasil API
• CEP
• CNPJ
• Bancos
• Validação CPF
• Dados públicos
• Plugin NEXUS

Resultado operacional

• CEP v2 com endereço + geolocalização e CNPJ (fonte Minha Receita) com DV validado antes da consulta — fonte complementar ao OpenCNPJ.
• Bancos por código COMPE (detalhe) e lista completa com contagem.
• Validação local de CPF (dígitos verificadores) sem consulta externa — privacidade respeitada.
• Endereço × CEP: heurística de match com score/hits — útil para conferência de cadastros.
• Cache local 24h com upsert e associação opcional a tarefas NEXUS (task_id); histórico paginado e stats por tipo/status.
• Enricher Intel Hub (cep/cnpj, prioridade 55): CEPs/CNPJs citados em textos viram signals com summary legível e flag cached.
• Sem API key — Brasil API pública; force ignora cache quando preciso.