Nexus Brasil API

Technical summary

NEXUS plugin that queries Brazilian public data through Brasil API without requiring an external key. It provides CEP with geolocation, CNPJ, banks, local CPF/CNPJ validation and address matching with a 24-hour cache and history; CEP and CNPJ artifacts also enrich the Intelligence Hub.

Executed scope

• plugin.json — v1.0.0, Data & Validation category, lucide building icon with icon_bg #059669, own icon.svg.
• Registrations: registerTab('brasil-api','Brasil API','building',tab.php,'Dados & Validação') and registerDoc('brasil-api','Brasil API','building',doc.md).
• 8 API actions (plugin.php, via PluginManager::registerApiAction) — brasilapi_stats|cep|cnpj|bank|banks|address_check|cpf_validate|history; cep/cnpj/bank accept task_id and force.
• brasilapi_cache table on load (brasilapi_install()): kind, query_key, status, payload_json, http_code, error, task_id, timestamps; UNIQUE kind+query_key; updated_at index.
• Local validation: brasilapi_cpf_valid() (DV, rejects repeats) and brasilapi_cnpj_valid() (weights 5-4-3-2/6-5-4-3-2) — no external call.
• HTTP: brasilapi_http_get() via cURL with timeouts, follow location, own UA and configurable SSL (SSL_VERIFY).
• Cache: get with 24h TTL (BRASILAPI_CACHE_TTL) + put with upsert; fallback recreates the table.
• Lookups: CEP v2 (/cep/v2/{cep}), CNPJ (/cnpj/v1/{cnpj}), COMPE bank (/banks/v1/{code}) and list (/banks/v1).
• brasilapi_check_address() — address × CEP match heuristic (score/hits/match + cep_data).
• brasilapi_validate_cpf() — local DV only (Brasil API does not query CPF).
• brasilapi_stats() and brasilapi_history() (paginated, limit ≤50).
• Intel Hub enricher: brasilapi_intel_enrich (cep/cnpj type, priority 55) with ok/error signals, summary and dedupe.
• Slash (fastr.json): /cep, /brasilcnpj (OpenCNPJ alternative), /banco.
• Alpine.js UI (tab.php, 251 lines): public API badge, stats, Query/Banks/CPF/History tabs, CEP/CNPJ/Address×CEP modes.

Stack and tools

• PHP 8 (strict_types, no framework) + MySQL 8 (brasilapi_cache table)
• cURL (12s timeout, configurable SSL) + public Brasil API (https://brasilapi.com.br/api, no key)
• Alpine.js + Tailwind CSS (tab.php)
• Intelligence Hub (cep/cnpj enricher) + Fast Responses (slash /cep, /brasilcnpj, /banco)

Operational tags

• Brasil API
• CEP
• CNPJ
• Banks
• CPF Validation
• Public Data
• NEXUS Plugin

Operational result

• CEP v2 with address + geolocation and CNPJ (Minha Receita source) with DV checked before the query — complementary source to OpenCNPJ.
• Banks by COMPE code (detail) and full list with count.
• Local CPF validation (check digits) with no external query — privacy respected.
• Address × CEP: match heuristic with score/hits — useful for registration checks.
• 24h local cache with upsert and optional NEXUS task association (task_id); paginated history and per-type/status stats.
• Intel Hub enricher (cep/cnpj, priority 55): CEPs/CNPJs cited in texts become signals with readable summary and cached flag.
• No API key — public Brasil API; force skips cache when needed.