Filament Cnpj Field Laravel Package

Product Decisions This Supports

• Brazil-market feature scoping. If your roadmap includes Brazilian B2B customers, supplier onboarding, invoicing (NF-e), or KYC/AML flows, this package directly answers "how much work is a compliant CNPJ field?" — the answer narrows to configuration rather than custom validation, masking, and registry integration.
• Build vs. buy. The buildable surface here is small but fiddly: mask formatting, two-pass check-digit modulo-11 validation, and a third-party lookup dependency. That is typically 1–3 engineering days plus ongoing edge-case maintenance. Adopting a package converts a recurring maintenance line item into a dependency upgrade line item.
• Alphanumeric CNPJ readiness. Brazil's CNPJ format is transitioning to alphanumeric identifiers. A package that explicitly advertises alphanumeric mask support is a forward-compatibility signal — worth weighing against homegrown validators that may hardcode the legacy 14-digit numeric format and silently break.
• Data-quality and fraud-prevention tradeoff. Built-in Minha Receita lookup means users can autofill legal name, address, and status from the official registry, which reduces typo-driven support tickets and catches "this CNPJ doesn't exist" at entry rather than at invoice issuance. Deciding whether to enable lookup by default is a UX/product call: it adds a network dependency and a latency path to form submission.
• Vendor/ecosystem alignment. This is an optional add-on inside the Filament ecosystem rather than core Laravel. Its value is proportional to how much of your admin surface is already Filament.

When to Consider This Package

Consider adoption when:

• You are already on Filament v5 (or committing to it). This is an explicit hard dependency — on Filament v4 or plain Blade/Livewire forms, this package provides no usable surface.
• Your product collects Brazilian company identifiers from operators or end users: supplier registration, customer master data, partner onboarding, expense/AP workflows.
• You want registry enrichment (legal name, address, registration status) without building and rate-limiting your own client against the Receita Federal data pipeline.
• You need format-agnostic validation — numeric and alphanumeric — and would rather inherit that from a maintained dependency than own it.
• Your team is small or non-specialist in Brazilian tax rules; correctness here is not obvious and is easy to get wrong in ways that only surface at fiscal integration time.

Look elsewhere when:

• You are not on Filament, or your admin UI is a separate SPA — you'd be pulling in a whole UI framework's field abstraction for one input.
• You need offline or air-gapped operation, or cannot permit outbound calls to a third-party mirror of registry data. Lookup is delegated to jeffersongoncalves/laravel-cnpj; if that path isn't acceptable, you need a self-hosted registry data source and only the validation/mask half of this package is relevant.
• You require SLA-backed or commercial support. This is a community package in a single-maintainer namespace — treat it as a convenience, not infrastructure.
• Your CNPJ needs extend beyond form input — e.g. stored-format normalization, fiscal document generation, or batch backfill/validation of an existing customer table. This package is a form field, not a domain service; backfill and persistence concerns remain yours.

Adoption risk to price in: the lookup is a transitive dependency on a second single-maintainer package, and 3.0.0 is a fresh major release pinned to a framework major — expect the usual early-adopter churn.

How to Pitch It (Stakeholders)

For executives: We're evaluating a small open-source component that adds a properly validated Brazilian company-ID field to our admin interface, including an optional automatic company-details lookup from the official registry. The business case is narrow but concrete: it removes a manual data-entry and verification step from Brazilian onboarding, which today costs support time and produces invalid records that surface later as failed invoices. Cost is effectively zero in licence terms; the real consideration is that it only applies if we standardize our admin stack on Filament v5, and it carries single-maintainer dependency risk. Recommendation: adopt behind a feature flag for the Brazil onboarding flow, and keep our own validation of stored records so we are not solely dependent on the package for data integrity.

For engineering: One line in a Filament schema gives us masked input, modulo-11 check-digit validation across both legacy numeric and the incoming alphanumeric CNPJ format, and optional registry enrichment. It does not solve persistence, normalization, or bulk validation of historical records — those stay with us. Two dependencies to review: the field package itself and jeffersongoncalves/laravel-cnpj for lookup. Plan for a network failure path (lookup unavailable should degrade to accept-valid-CNPJ, not block submission), decide whether enrichment is opt-in per form, and confirm we're on Filament v5 before this enters the backlog — if we're not, the effort is a custom validator and this package is a non-starter for now.