CNPJ Alfanumérico (jul/2026): SDK assume CNPJ numérico e não suporta o novo formato

[andrenfe]

Resumo

A Receita Federal passa a emitir CNPJ Alfanumérico a partir de julho/2026. O SDK trata o CNPJ como valor numérico em validação, normalização e tipagem. Com isso, um CNPJ alfanumérico não pode ser representado, validado nem enviado/recebido pelo SDK no estado atual. Esta issue documenta o que muda e onde o SDK é impactado. As decisões técnicas de implementação ficam em aberto.

Contexto da mudança

• Base legal: IN RFB nº 2.229/2024; Nota Técnica COCAD/SUARA/RFB nº 49/2024.
• Formato (14 posições, máscara preservada ##.###.###/####-##):
  • Posições 1–12 (raiz + ordem/filial): passam a aceitar letras (A–Z) e dígitos (0–9).
  • Posições 13–14 (dígitos verificadores): permanecem numéricas.
• Cálculo do DV: módulo 11 em que o valor de cada caractere é o código ASCII decimal − 48 ('0'–'9' → 0–9; 'A'–'Z' → 17–42). É um algoritmo diferente do módulo 11 puramente numérico atual.
• Cronograma: homologação SEFAZ a partir de 06/04/2026; produção a partir de 06/07/2026.
• Coexistência: CNPJs numéricos existentes continuam válidos; CPF não muda (segue 11 dígitos numéricos).

Impacto no SDK (estado atual)

1. Validação de empresa força tipo numérico — src/core/resources/companies.ts

   • validateCNPJ(cnpj: number) recebe number; um CNPJ com letras não é representável como número JS. O cálculo do DV usa parseInt por caractere (somente numérico, sem ASCII−48).
   • validateCompanyData exige typeof federalTaxNumber === 'number' e comprimento 11/14 — um CNPJ alfanumérico sequer consegue ser submetido.

2. Normalização remove letras / validação exige 14 dígitos — src/core/resources/legal-entity-lookup.ts

   • normalizeFederalTaxNumber faz replace(/\D/g, ''), descartando letras → corrompe um CNPJ alfanumérico.
   • validateFederalTaxNumber exige exatamente 14 dígitos → rejeita um CNPJ alfanumérico válido. Esse valor normalizado também compõe as URLs de consulta (findBasicInfo, findStateTax, etc.).

3. Tipagem como number — src/core/types.ts

   • Company.federalTaxNumber: number e diversos outros campos federalTaxNumber?: number não conseguem representar letras (alguns campos já são string, então há inconsistência).

4. Tipos gerados — src/generated/** (ex.: index.ts, consulta-cnpj)

   • Vários federalTaxNumber?: number. Esses arquivos são gerados a partir de openapi/spec/*.yaml e não podem ser editados à mão → a raiz está nas specs OpenAPI.

5. Lookups por documento — src/core/resources/legal-people.ts e natural-people.ts

   • findByTaxNumber compara person.federalTaxNumber?.toString() === federalTaxNumber; comportamento depende da tipagem/normalização acima.

6. Testes/fixtures numéricos — tests/unit/companies.test.ts, tests/unit/legal-entity-lookup.test.ts, tests/setup.ts usam CNPJ numérico; não há cobertura para o formato alfanumérico nem para o novo DV.

Questões técnicas em aberto (a decidir)

• Tipo de federalTaxNumber: manter number, migrar para string, ou string | number? (impacto de breaking change em v4).
• Adotar validação do novo DV (módulo 11 ASCII−48) e como conviver com o módulo 11 numérico legado.
• Como preservar letras na normalização (hoje /\D/g) mantendo a remoção apenas de máscara (. / -).
• Garantir coexistência numérico (legado) + alfanumérico em todos os validadores.
• Alinhamento com a API NFE.io upstream: ela já aceita/retorna alfanumérico? O SDK deve espelhar o contrato da API — confirmar antes de definir tipos/validação.

Referências

• NFE.io — Release note: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/index.md
• NFE.io — Documentação técnica: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica/index.md
• Receita Federal — CNPJ Alfanumérico: https://www.gov.br/receitafederal/pt-br/acesso-a-informacao/acoes-e-programas/programas-e-atividades/cnpj-alfanumerico
• Receita Federal — Perguntas e respostas (PDF): https://www.gov.br/receitafederal/pt-br/centrais-de-conteudo/publicacoes/perguntas-e-respostas/cnpj/cnpj-alfanumerico.pdf