Skip to content

Release v6.0.2 — CNPJ alfanumérico (primeira parte), manifestação 210200 e gate de tipos - #59

Merged
andrenfe merged 6 commits into
masterfrom
fix/v6.0.2
Nov 19, 2026
Merged

andrenfe merged 6 commits into
masterfrom
fix/v6.0.2

Conversation

@andrenfe

Copy link
Copy Markdown
Member

O que é

Patch. O SDK para de recusar no cliente o que a API aceita em CNPJ, CPF e chave de acesso. É a
primeira parte da #36 (CNPJ alfanumérico, IN RFB 2.229/2024). A segunda parte, o acesso à
família v3 da API, a única que aceita CNPJ alfanumérico, vem numa minor.

Entram também uma correção de documentação perigosa na manifestação do destinatário, com uma
mudança de tipo aditiva, e o conserto do gate test:types.

Nada novo é exportado. A única mudança de tipo é aditiva: ManifestEventType ganha o
210200. Evidência versionada em tests/fixtures/live-contracts/alphanumeric-tax-ids.json, com
dados sintéticos.

⚠️ Publicação: o merge não publica

O publish.yml dispara só em release: created e em workflow_dispatch. Push, PR e merge na
master rodam só o CI. A 6.0.2 vai para o npm quando alguém criar a release v6.0.2 no
GitHub
(ver "Depois do merge").

O npm run release publica direto da máquina local, sem passar pelo portão do workflow. Não
usar.

CNPJ, CPF e chave de acesso

Uma regra única (src/core/utils/tax-id.ts, interno) passa a valer em todos os recursos:

  • a normalização tira ., /, - e espaços e passa para maiúsculas, sem perder letras;
  • CNPJ: ^[0-9A-Z]{12}[0-9]{2}$, com DV por módulo 11 sobre o valor ASCII − 48 de cada
    caractere. Para dígitos, o cálculo é o de sempre;
  • chave de acesso: ^\d{6}[0-9A-Z]{12}\d{26}$. Só o CNPJ do emitente, nas posições 7 a 18, tem
    letra.

companies aceita CNPJ ou CPF que começa com zero. Como number, 01234567999885 vira
1234567999885, e o SDK recusava esse número pelo tamanho. Medido em 18/11, com escrita
autorizada e CNPJ sintético:

  • POST /v1/companies com o número curto respondeu 201, e a API gravou as 14 posições;
  • o PUT com o objeto lido respondeu 200.

Agora o SDK completa com zeros e confere o DV, e findByTaxNumber compara pelo valor. Um teste
de integração novo repete o ciclo pelo SDK, com opt-in de escrita.

A chave de acesso com letras deixa de ser recusada no cliente. inboundProductInvoices,
productInvoiceQuery, consumerInvoiceQuery e transportationInvoices aceitam a chave e a
enviam em maiúsculas. Cada rota da API decide se atende (medido em 18/11):

  • as rotas /inbound/productinvoices/… aceitam a chave;
  • as rotas /inbound/{chave}… e a consulta de NF-e ainda respondem 400, e o SDK repassa a
    mensagem como ValidationError.

A consulta de CNPJ deixa de arrancar as letras. O replace(/\D/g, '') transformava um CNPJ
alfanumérico em 9 dígitos. Agora o CNPJ chega à API, que responde 400 com "Utilize a v3", e o
SDK repassa a mensagem.

legalPeople e naturalPeople: findByTaxNumber compara pelo valor. Um registro que a API
devolve como número sem o zero à esquerda passa a ser achado.

CNPJ de exemplo. O 12345678000190 dos exemplos tinha DV inválido. README, docs/, skill,
exemplos, JSDoc e testes passam a usar 11222333999952, um CNPJ sintético: o DV é válido, e a
consulta de CNPJ responde 404.

Mudanças de comportamento

  • A consulta de CNPJ confere o DV no cliente. Um DV inválido lança ValidationError sem
    requisição. Antes, o 400 da API já virava ValidationError.
  • A consulta de CNPJ recusa texto fora da máscara: 'CNPJ 11.222.333/9999-52' passava.
  • Mensagens de erro novas, listadas no CHANGELOG, para quem compara texto.

Manifestação: 210220 é Desconhecimento, não Confirmação

O README, docs/API.md, o JSDoc, a skill e o exemplo chamavam o 210220 de "Confirmação da
Operação". Ele é Desconhecimento da Operação: enviá-lo registra na SEFAZ, em nome do
destinatário, que a operação não é reconhecida, de forma visível para o emissor e para o fisco.
Um cliente quase o enviou seguindo a documentação.

  • O texto traz os quatro códigos, um aviso e um exemplo de Confirmação.
  • ManifestEventType ganha o 210200, a Confirmação, que faltava. Em TypeScript, confirmar uma
    operação não compilava sem forçar o tipo. O tipo passa a ser o enum que a plataforma declara
    para a rota, e o padrão continua 210210.
  • Segundo a documentação da plataforma, a rota responde 400 para 210240, porque o evento
    exige justificativa. Os exemplos com 210220 e 210240 saíram.
  • Nada foi enviado ao vivo, porque manifestar registra um evento na SEFAZ. O teste unitário
    confere o tpEvent=210200 na URL, e um teste de tipo fixa os quatro códigos.

Manutenção

  • O npm run test:types não conferia nada. O vitest --typecheck usava o tsconfig.json,
    que só inclui src/, e os tests/types/*.test-d.ts ficavam de fora:
    expectTypeOf<1>().toEqualTypeOf<2>() passava. O CI e o publish.yml rodam esse comando.
    Agora o vitest.config.ts aponta o typecheck para o tsconfig.test-types.json. A asserção
    falsa falha, e os quatro testes de tipo antigos passam sem mudança.
  • Sai o arquivo VERSION da raiz. Ele estava parado em 4.0.0 e nada o lia. A versão vem do
    package.json, e o version.test.ts guarda a concordância com src/version.ts.
  • Referências internas fora do pacote. Onze pontos de versões anteriores (CHANGELOG, skill,
    JSDoc, comentários e uma página de docs/) citavam fontes internas. Agora citam a
    documentação da plataforma, sem mudar o sentido. O tarball da 6.0.2 sai limpo.

Commits

Cada commit é revisável sozinho, e todos passam em typecheck e na suíte unitária isoladamente.

commit o quê
a4968eb fix(tax-id) regra única de CNPJ, CPF e chave de acesso
b10517c fix(inbound) ManifestEventType com 210200; 210220 é Desconhecimento
ee88945 test(types) test:types passa a conferir os testes de tipo
c5358aa docs documentação da plataforma no lugar de referências internas
620b133 chore(release) v6.0.2
21c41c2 docs CNPJ de exemplo sintético, que não existe na Receita

Verificação

typecheck   limpo
lint        0 erros (32 avisos antigos de `any`; nenhum em linha alterada)
test:types  20/20; uma asserção falsa falha (exit 1), e o teste do ManifestEventType
            falha com o tipo antigo (TS2344)
unit        831 passed | 6 skipped (tests/unit, 47 arquivos)
por commit  typecheck + unit verdes em cada um dos 6; test:types a partir do 3º
integração  companies, CNPJ com zero à esquerda: passa com NFE_ALLOW_ACCOUNT_WRITES=true
            (1 empresa de teste, inativa depois do teste) e é pulado sem a variável
tarball     nfe-io@6.0.2, 19 arquivos: dist, README, CHANGELOG, MIGRATION, LICENSE e
            skills; nenhuma referência interna e nenhum CNPJ real de exemplo
build       ok
sondas      pelo SDK corrigido: a chave com letras chega à API (404 nas rotas
            productinvoices, 400 nas rotas raiz); o CNPJ alfanumérico recebe o 400
            "Utilize a v3" da API; um DV inválido falha no cliente

Depois do merge

  1. Criar a release v6.0.2 no GitHub sobre o commit de merge, que é o que dispara o
    publish.yml. A entrada do CHANGELOG está datada de 2026-11-18. Se o release sair em outro
    dia, ajustar antes.
  2. Comentar na CNPJ Alfanumérico (jul/2026): SDK assume CNPJ numérico e não suporta o novo formato #36 com o link do release. Este PR não usa palavra de fechamento: a CNPJ Alfanumérico (jul/2026): SDK assume CNPJ numérico e não suporta o novo formato #36 segue
    aberta até a minor da família v3.
  3. Re-sincronizar as páginas da biblioteca Node no portal de documentação.

Fora deste PR:

  • o acesso à família v3 (nfe.v3.*), que vem numa minor;
  • documentar o processamento assíncrono da manifestação e revisar o retorno de manifest; a
    rota manifestation-events fica para a 6.1.0.

…ceita

Uma regra unica de CNPJ, CPF e chave de acesso (src/core/utils/tax-id.ts,
interno) passa a valer em todos os recursos:

- companies.create, update e findByTaxNumber aceitam CNPJ ou CPF que
  perdeu o zero a esquerda como number. A API completa os zeros (medido
  em 2026-11-18 com escrita autorizada). CNPJ alfanumerico recebe um erro
  que aponta a API v3 de empresas.
- inboundProductInvoices, productInvoiceQuery, consumerInvoiceQuery e
  transportationInvoices aceitam letras nas posicoes 7 a 18 da chave
  (CNPJ alfanumerico do emitente) e enviam a chave em maiusculas. Cada
  rota da API decide se atende.
- legalEntityLookup mantem as letras, confere o DV no cliente (modulo 11
  com ASCII - 48) e recusa texto fora da mascara.
- legalPeople.findByTaxNumber e naturalPeople.findByTaxNumber comparam
  pelo valor.

Docs, exemplos e skill trocam o CNPJ de exemplo invalido 12345678000190
por 11222333000181 e explicam o formato com letras. A skill tambem corrige
as opcoes e os campos da consulta de CNPJ e o padrao de CEP.

Evidencia em tests/fixtures/live-contracts/alphanumeric-tax-ids.json.

Refs #36
A documentacao chamava o 210220 de Confirmacao da Operacao. O 210220 e
Desconhecimento da Operacao: envia-lo registra na SEFAZ, em nome do
destinatario, que a operacao nao e reconhecida. A Confirmacao e o 210200,
que faltava no tipo.

- ManifestEventType passa a ser 210200 | 210210 | 210220 | 210240, o enum
  que a plataforma declara para a rota de manifestacao. A mudanca e
  aditiva, e o padrao continua 210210.
- JSDoc, README, docs/API.md, skill e exemplo trazem os quatro codigos, o
  aviso e um exemplo de Confirmacao com 210200. Saem os exemplos com
  210220 e 210240 (a rota responde 400 para 210240).
- Teste unitario de manifest com tpEvent=210200 e teste de tipo em
  tests/types/manifest-event-type.test-d.ts.
O vitest --typecheck so confere os arquivos do programa do TypeScript, e o
tsconfig.json inclui so src/. Os tests/types/*.test-d.ts ficavam de fora e
nenhum erro de tipo aparecia: expectTypeOf<1>().toEqualTypeOf<2>() passava.
O CI e o publish.yml rodam esse comando.

O vitest.config.ts aponta typecheck.tsconfig para o tsconfig.test-types.json
(novo), que inclui os testes de tipo. A assercao falsa agora falha, e os
cinco arquivos de tipo passam sem mudanca.
Onze pontos de versoes anteriores citavam fontes internas: o CHANGELOG, a
skill, JSDoc, comentarios em src/ e docs/recursos/municipal-taxes.md.
Passam a citar a documentacao da plataforma, sem mudar o sentido. O pacote
publicado deixa de levar essas referencias (conferido com npm pack).
Versao 6.0.2 no package.json e no package-lock.json; src/version.ts
regenerado. Entrada 6.0.2 no CHANGELOG: CNPJ alfanumerico, primeira parte
(zero a esquerda, chave de acesso com letras e consulta de CNPJ, com as
mensagens de erro novas); manifestacao (210220 e Desconhecimento, e
ManifestEventType ganha o 210200); o gate test:types; e o que ja estava
em [Nao lancado] (paginas conferidas e frontmatter de maquina). Links de
comparacao para v6.0.2.

Sai o arquivo VERSION da raiz: parado em 4.0.0 e sem leitor. A versao vem
do package.json, e tests/unit/version.test.ts guarda a concordancia.
O CNPJ de exemplo 11222333000181 existe na Receita e esta ativo. Os
exemplos de consulta devolviam dados reais, e o companies.create do README
cadastraria esse CNPJ. README, MIGRATION, docs/, skill, exemplos, JSDoc, a
mensagem de erro do CNPJ fora do formato e os testes passam a usar
11222333999952 (11.222.333/9999-52): o DV e valido, e a consulta de CNPJ
responde 404 (conferido em 2026-11-18).

Os dados das escritas de teste (TEST_COMPANY_DATA da integracao e
test-company.json) tambem saem do CNPJ real.
@github-actions

Copy link
Copy Markdown

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

  • calculo-impostos-v1.yaml - 27.90 KB, 853 lines
  • consulta-cnpj.yaml - 34.28 KB, 1128 lines
  • consulta-cpf.yaml - 3.39 KB, 83 lines
  • consulta-cte-v2.yaml - 18.33 KB, 578 lines
  • consulta-endereco.yaml - 11.17 KB, 343 lines
  • consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
  • consulta-nf.yaml - 137.87 KB, 3119 lines
  • consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
  • nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
  • nf-produto-v2.yaml - 309.41 KB, 8204 lines
  • nf-servico-v1.yaml - 257.67 KB, 6255 lines
  • nfeio.yaml - 15.86 KB, 630 lines
  • product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
  • service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

@andrenfe
andrenfe merged commit 5965080 into master Nov 19, 2026
8 checks passed
@andrenfe
andrenfe deleted the fix/v6.0.2 branch November 19, 2026 00:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant