NEXUS OpenCNPJ Enrichment

Technical summary

NEXUS plugin that automatically enriches CNPJs detected in tasks and comments with official Receita Federal registration data via OpenCNPJ — company name, registration status, CNAE, capital and size. The Intelligence Hub enricher queries the keyless public API with an instant local cache; the tab offers manual lookup with masked or digits-only CNPJ and cache management.

Executed scope

• Registration: plugin.json v1.0.0, icon_bg #0284c7, lucide building icon and custom icon.svg (lens + cyan arc, no is_core — additional plugin); registerTab('opencnpj','OpenCNPJ','building',tab.php,'OSINT & Enrichment') and registerDoc('opencnpj','OpenCNPJ','building',doc.md); no dedicated modals and no cronjob (no periodic routine).
• opencnpj_enrichment table via opencnpj_install(): cnpj VARCHAR(14) PK, razao_social (NOT NULL), nome_fantasia, situacao_cadastral, cnae_principal, uf, municipio, capital_social, porte_empresa and created_at DATETIME (InnoDB, utf8mb4).
• Keyless public API via cURL (https://api.opencnpj.org/{14 digits}): NEXUS OpenCNPJ Integration (SITE_URL) User-Agent, 3s connect / 6s response timeouts, IPRESOLVE_V4 and configurable SSL_VERIFY via a Core constant; response validated (requires cnpj or razao_social in the JSON).
• CNPJ detection in text: masked format (XX.XXX.XXX/XXXX-XX) and 14 consecutive digits, deduplicated and length-validated before lookup.
• Instant local cache: opencnpj_query() serves from cache (source: cache) before the remote call (source: api) and persists the record — sub-ms hits on tasks.
• API with 3 actions: opencnpj_query (manual, cache → API), opencnpj_stats (cache total + last 20 consultations + api_online pulse testing CNPJ 00000000000191) and opencnpj_delete (removes one CNPJ from the local cache).
• Intelligence Hub enricher: nx_intel_register_enricher('opencnpj', ['cnpj'], 'opencnpj_intel_enrich', 47) — signals with ok/error/skipped status, Company Name · Status summary, severity 5 (active status) or 40 (inactive), formatted CNPJ artifact, respects the max_live_lookups budget (slice ≤ min(5, budget × 2)) and flags cached.
• Fast Responses: fastr.json manifest with /opencnpj (required CNPJ argument), action opencnpj_query — direct slash lookup.
• On demand: no cronjob.json (no periodic routine needed); no CLI.
• UI: Alpine.js tab (tab.php, 334 lines) with "API Online/Offline" badge, indicators (Cached Total, Local Speed < 1ms, Trusted Source — Receita Federal), manual lookup with a quick test (Petrobras 33.000.167/0001-01), result with status badge (emerald/rose), formatted CNPJ, CNAE, capital in BRL, location and size; "Cached Companies" table with search by name/trade name/CNPJ/city and confirmed deletion.
• Legacy: opencnpj_filter_task_read/opencnpj_filter_comment_read disabled (commented out in plugin.php) — they appended a "### 🏢 Dados Cadastrais Enriquecidos (OpenCNPJ)" markdown table; automatic enrichment moved to the Intelligence Hub (core/intel.php).

Stack and tools

• PHP 8 backend (no framework) + MySQL 8 (opencnpj_enrichment table)
• OpenCNPJ public API via cURL (api.opencnpj.org) — official Receita Federal data
• Alpine.js + Tailwind CSS (panel tab) + internal Plugin API (tabs/actions + fastr.json + Intel Hub)

Tags

OpenCNPJ, CNPJ, Receita Federal, OSINT, Enrichment, Intelligence Hub, NEXUS Plugin

Operational result

• Automatic CNPJ enrichment: tasks and comments containing CNPJs become Intelligence Hub signals with Receita Federal data.
• No API key: free public API — enable the plugin and it enriches; zero configuration.
• Flexible format: accepts masked CNPJ (XX.XXX.XXX/XXXX-XX) or plain 14 digits.
• Instant cache: hits respond in < 1ms with no external traffic — handy for lists repeating the same vendor.
• Contextual severity: 5 for active companies, 40 for inactive — flags delisted/dormant vendors.
• No routines: purely on-demand plugin — no cron or CLI.