Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
O formato é baseado em Keep a Changelog, e este projeto adere ao Versionamento Semântico.
6.0.2 - 2026-11-18
CNPJ alfanumérico (IN RFB 2.229/2024), primeira parte: o SDK para de recusar no cliente o que a API aceita. Uma regra só passa a valer para CNPJ, CPF e chave de acesso em todos os recursos. O acesso à família v3 da API, a única que aceita CNPJ alfanumérico, vem numa minor. Evidência em
tests/fixtures/live-contracts/alphanumeric-tax-ids.json.Manifestação do destinatário: o
210220é Desconhecimento da Operação, não Confirmação. A documentação errava o código. A Confirmação é o210200, que o tipoManifestEventTypepassa a aceitar.Nada novo é exportado. A única mudança de tipo é aditiva:
ManifestEventTypeganha o210200.
-
companiesaceita CNPJ ou CPF que começa com zero. Comonumber, o documento perde o zero:01234567999885vira1234567999885.create,updateefindByTaxNumberrecusavam esse número pelo tamanho. A API completa os zeros. Medido em 2026-11-18, com escrita autorizada:POST /v1/companiescom o número curto respondeu201;- a v3 devolveu o CNPJ gravado com as 14 posições;
- o
PUTcom o objeto lido respondeu200.
Agora o SDK completa com zeros e confere os dígitos verificadores, e
findByTaxNumbercompara pelo valor. Em JavaScript sem tipos, uma string só de dígitos (14 para CNPJ, 11 para CPF) também é aceita, como na API. O tipo continuanumber. -
A chave de acesso de emitente com CNPJ alfanumérico deixa de ser recusada no cliente. Com CNPJ alfanumérico, as posições 7 a 18 da chave têm letras.
inboundProductInvoices,productInvoiceQuery,consumerInvoiceQueryetransportationInvoicesexigiam 44 dígitos. Agora aceitam letras nessas posições e enviam a chave em maiúsculas. Cada rota da API decide se atende (medido em 2026-11-18):- as rotas
/inbound/productinvoices/…aceitam a chave; - as rotas
/inbound/{chave}…e a consulta de NF-e ainda respondem400, e o SDK repassa a mensagem comoValidationError.
- as rotas
-
A consulta de CNPJ deixa de arrancar as letras.
legalEntityLookupfaziareplace(/\D/g, ''): um CNPJ alfanumérico virava 9 dígitos, e o erro dizia "got 9 digit(s)". Agora a normalização tira só.,/,-e espaços e converte letras para maiúsculas. O CNPJ alfanumérico chega à API, que responde400com "CNPJ alfanumérico não é suportado nesta versão. Utilize a v3.". O SDK lançaValidationErrorcom essa mensagem. -
legalPeople.findByTaxNumberenaturalPeople.findByTaxNumbercomparam pelo valor. Um registro que a API devolve como número sem o zero à esquerda passa a ser achado pela string com o zero, com ou sem máscara. -
ManifestEventTypeaceita o210200, a Confirmação da Operação. O tipo tinha só210210,210220e210240: em TypeScript, confirmar uma operação não compilava sem forçar o tipo, e a documentação mandava usar o210220, que é Desconhecimento (veja Documentação). Agora o tipo tem os quatro códigos que a plataforma declara para a rota de manifestação:210200 | 210210 | 210220 | 210240. A mudança é aditiva: o código que compilava continua compilando, e o padrão continua210210. O SDK só repassa o código à API.
- A consulta de CNPJ confere os dígitos verificadores no cliente. Um DV inválido lança
ValidationErrorsem requisição. Antes, a API respondia400, que já viravaValidationError. O cálculo é o módulo 11 com o valor ASCII − 48 de cada caractere: para dígitos, dá o resultado de sempre, e as 26 letras valem. - A consulta de CNPJ recusa texto fora da máscara.
'CNPJ 11.222.333/9999-52'passava, porque o\Ddescartava tudo o que não era dígito. Agora falha no cliente. - Mensagens de erro novas, para quem compara texto:
- chave de acesso:
Expected 44 characters: digits only, except positions 7 to 18, which hold the issuer CNPJ and may contain letters (alphanumeric CNPJ).; - CNPJ fora do formato:
Expected 14 characters after removing punctuation: 12 letters or digits followed by 2 check digits …; - CNPJ com DV inválido:
The CNPJ check digits do not match.; companiescom CNPJ alfanumérico:Alphanumeric CNPJ is not accepted by the v1 companies API. The v3 companies API accepts it.;companiescom documento inválido:Invalid federalTaxNumber: … Expected a valid CNPJ (14 digits) or CPF (11 digits); a number that lost its leading zeros is accepted.;companies.findByTaxNumber:Tax number must be a non-negative integer with up to 14 digits (CNPJ or CPF).
- chave de acesso:
- O código
210220da manifestação é Desconhecimento da Operação, não Confirmação. O JSDoc deManifestEventTypee deinboundProductInvoices.manifest, o README,docs/API.md, a skill e o exemploexamples/inbound-product-invoices.jschamavam o210220de "Confirmação da Operação". Isso está errado: enviá-lo registra na SEFAZ, em nome do destinatário, uma declaração formal de que a operação não é reconhecida, visível para o emissor e para o fisco. Um cliente quase o enviou seguindo a documentação.- O texto agora traz os quatro códigos e o aviso.
- A Confirmação da Operação é
210200. O README,docs/API.md, o JSDoc e a skill mostram como enviá-la, e o tipo passa a aceitar o código (veja Corrigido). - Segundo a documentação da plataforma, a rota de manifestação responde
400para210240, porque o evento exige justificativa. Os exemplos que manifestavam210220e210240saíram. - Nada muda em tempo de execução.
- Exemplos com CNPJ inválido. O CNPJ de exemplo
12345678000190tem DV inválido, e a API sempre o recusou. Com esta versão, a consulta de CNPJ também o recusa no cliente. Ele aparecia no README, noMIGRATION.md, emdocs/API.md, nos exemplos, no JSDoc, na skill e nos testes, em consultas de CNPJ, emcompanies.create, em pessoas e no comprador de NF-e. Agora esses exemplos usam11222333999952, um CNPJ sintético: o DV é válido, e a consulta de CNPJ não o encontra na Receita. Ocompanies.createdo README passou a usarnumber. - Formato do CNPJ nas páginas. As páginas de consulta de CNPJ, de empresas e de NF-e de entrada explicam o formato com letras, a normalização e que o CNPJ alfanumérico exige a API v3. A página de NF-e de entrada lista quais métodos já aceitam a chave com letras.
- Skill publicada (
skills/nfeio-node-sdk/).- A skill registra a regra da 6.0.2: zero à esquerda, chave de acesso com letras e quais rotas a aceitam, e CNPJ alfanumérico só na família v3 da API.
- A seção de consulta de CNPJ trazia opções que não existem (
includePartners,includeActivities). As opções reais sãoupdateAddresseupdateCityCode. - Ela também trazia campos com nome ou tipo errado. O certo é
federalTaxNumbercomonumber, e nãostring, maisopenedOn,shareCapital,economicActivitieselegalNature. - O padrão "Address from CEP" desestruturava
{ addresses }, maslookupByPostalCodedevolve umAddress.
- As páginas de
docs/que o portal espelha foram conferidas contra o código. Havia assinaturas e retornos de antes da 6.0.0 nas páginas de NF-e, NFS-e, inscrição estadual, consulta de CNPJ e pessoas, e emdownloads.md, que ainda prometia "Buffer sempre" e "ZIP por empresa". Também foram corrigidos exemplos que não compilavam em modo estrito.docs/API.md,docs/EXTENDING.mdedocs/EXTENSIBILITY_SUMMARY.mdsão da v3 e ganharam aviso de legado no topo, sem reescrever o conteúdo. - Frontmatter de máquina nas páginas de
docs/. Cada página traztagseintegration: [sdk], que o portal de documentação usa como facetas de busca.
- Sai o arquivo
VERSIONda raiz. Ele estava parado em4.0.0desde a v4, e nada o lia: nem o build, nem os testes, nem o workflow de publicação, nem o pacote publicado. A versão tem uma fonte só, opackage.json;src/version.tsé gerado dele, etests/unit/version.test.tsfalha se as duas divergirem. npm run test:typespassa a conferir os tipos. O comando rodavitest --typecheck, que só confere os arquivos do programa do TypeScript. Otsconfig.jsoninclui sósrc/, então os arquivostests/types/*.test-d.tsficavam de fora e nenhum erro de tipo aparecia: a asserção falsaexpectTypeOf<1>().toEqualTypeOf<2>()passava. O CI e o workflow de publicação rodam esse comando. Agora ovitest.config.tsaponta o typecheck para otsconfig.test-types.json, que inclui os testes de tipo. Os quatro guardas de tipo que já existiam passam sem mudança.
6.0.1 - 2026-10-16
Patch de contrato e de documentação. Dois bugs de código, provados por sonda ao vivo contra a API real (2026-10-14 a 10-16), e uma rodada de correções na documentação, que ensinava métodos sem caminho de sucesso e uma regra de chaves imprecisa. Nenhuma assinatura pública muda. Evidência versionada em
tests/fixtures/live-contracts/.
-
Quatro métodos da distribuição de NF-e chamavam uma rota que não existe.
inboundProductInvoices.getProductInvoiceDetails,getProductInvoiceEventDetails,getJsonereprocessWebhookmontavam/inbound/productinvoice/(singular). A plataforma serve só o plural,/inbound/productinvoices/. Medido em 2026-10-14: o singular responde404de corpo vazio mesmo sem credencial, igual a um path inventado; o plural responde401sem credencial, e200com ela nos dois métodos de leitura sondados (getProductInvoiceDetailsegetJson). A spec localconsulta-nfe-distribuicao-v1.yamlainda diz singular; a spec atualizada da plataforma já traz o plural. Cinco testes unitários afirmavam o path errado e foram corrigidos junto.O bug era latente. Em 30 dias de log de gateway (2026-09-14 a 10-14), o plural teve 28.543 respostas
200e o singular, 9 respostas404, nenhuma com User-Agent do SDK. Evidência eminbound-distribution-routes.json. -
municipalTaxes,stateTaxesenotificationsdevolviam o envelope no lugar da entidade. A API responde{ "municipalTax": {…} },{ "stateTax": {…} }e{ "notification": {…} }, e o SDK repassava o corpo tipado como a entidade:resultado.ideraundefined, sem erro de compilação. Agoracreate,retrieveeupdatedemunicipalTaxesestateTaxes, enotifications.retrieve, devolvem a entidade.O envelope foi medido no
retrievedos três em 2026-10-15. Ocreatee oupdatenão foram sondados, porque exigiriam escrever num registro real; seguem a spec, que declara o mesmo envelope. O desembrulho é defensivo: se a API responder a entidade direta, ela chega intacta.Migração: quem contornava o bug lendo
(resultado as any).municipalTax(ou.stateTax,.notification) passa a receberundefinednessa leitura. Use o resultado direto. Código que precisa rodar nas duas versões pode ler(resultado as any).municipalTax ?? resultado.Evidência em
response-envelopes.json, que registra também três casos em que o SDK já estava certo e a spec erra:legalPeople.list,naturalPeople.retrieveeaddresses.lookupByPostalCode.
-
municipalTaxes.updateé um PUT que substitui a inscrição, e nada avisava. Pela documentação da plataforma, omitirtaxNumberapaga o número da inscrição, e omitirenvironmentvolta paraDevelopment.rpsNumberelastRpsSentsão a exceção: omitidos, preservam o contador de RPS; enviados, sobrescrevem o contador, inclusive para trás. O JSDoc,docs/recursos/municipal-taxes.mde a skill agora mostram o roteiro: ler comretrieve, alterar e reenviar sem os dois campos do contador. O SDK não sondou isso, porque exigiria escrever sobre uma inscrição real. -
A documentação ensinava como funcionais métodos que só respondem
404.municipalTaxes.getSeries()/updatePrefecture()econsumerInvoiceQuery.retrieve()/downloadXml()estão@deprecateddesde a 6.0.0, porque a plataforma não serve as rotas. Mesmo assim,docs/recursos/, o README,docs/API.md, a skill e os exemplos ainda os mostravam como caminho de uso; agora aparecem como descontinuados. O exemplo de webhook por empresa do README passou ao webhook de conta (createAccountWebhook), e a seção v2 → v3 doMIGRATION.mdganhou o aviso de que os métodos por empresa estão descontinuados.tests/unit/docs-drift.test.tspassa a falhar quando um documento cita, sem aviso por perto, um método@deprecatedpor rota não servida. O conjunto sai do código, não de uma lista mantida à mão: entram os métodos com@deprecated, inclusive no nível da classe, menos as depreciações funcionais declaradas com motivo (companies.list,webhooks.getAvailableEvents). -
Links quebrados (issue #47). O README apontava para
docs/MIGRATION-TO-GENERATED-TYPES.md, e a entrada 3.0 deste CHANGELOG paraRELEASE_NOTES_v3.md; nenhum dos dois existe, e ambos passam aoMIGRATION.md.docs/API.mdedocs/EXTENDING.mdlinkavam arquivos fora dedocs/(../src/core/types.ts,../CONTRIBUTING.md,../LICENSE), que quebram no portal, ondedocs/é espelhado sozinho; passam a URLs absolutas do repositório. Odocs-drift.test.tsagora confere os links relativos de README,MIGRATION.md, CHANGELOG,docs/**eskills/**: o arquivo precisa existir e, emdocs/**, o link não pode sair dedocs/. -
Arquivo de licença (issue #47). O repositório nunca teve um: o MIT existia só no campo
licensedopackage.json, e a API do GitHub reportava o repositório como sem licença. Entra oLICENSEcom o texto MIT e a linhaCopyright (c) 2026 NFE.IO HUB SERVICOS DE TECNOLOGIA LTDA. O README, os cabeçalhos desrc/e o banner do bundle citam o mesmo titular. O banner usa/*! … */, que os minificadores preservam quando a aplicação re-empacota o SDK. A licença cobre o SDK; o uso da API segue o contrato da conta.tests/unit/license.test.tscompara o SPDX declarado com o texto do arquivo e confere o arquivo no tarball. -
A skill publicada ensinava assinaturas de antes da 6.0.0. Comparada ao código, ela tinha 32 métodos com parâmetro, retorno ou nome errado, quase todos de quebras da 6.0.0 que não chegaram a ela:
- downloads de
productInvoices,consumerInvoices,inboundProductInvoicesetransportationInvoicesdescritos comoBufferou string, quando devolvem um recurso com URI; productInvoices.sendCorrectionLetter,disableedisableRange; ocancel, os downloads e ogetStatusde NFS-e; as leituras de NFC-e com umenvironmentque não existe mais;transportationInvoices.retrieveEvent, que não existe: o método égetEvent.
Também estavam errados o CRUD de webhook por empresa, que aparecia como funcional numa tabela, o pitfall de chaves, que dizia que o cálculo de tributos usa a chave de dados, e o tipo
NfeStateTax. Tudo foi conferido contra o código: os usos que a skill ensina agora compilam em modo estrito, e os que ela ensinava antes não compilam. Entraram também as notas desta release (distribuição no plural, envelopes). - downloads de
A regra de chaves da 6.0.0 vale por rota, não por host. A entrada 6.0.0 diz que as
duas chaves "são complementares, e cada uma responde 403 no território da outra". Isso
generalizava uma sonda de 2026-09-01 que só testou rotas de documento fiscal em
api.nfse.io. A matriz foi refeita em 2026-10-14 sobre 16 rotas:
- a chave de dados é recusada (
403) nas rotas de documento fiscal: tax-codes, NF-e, NFC-e, distribuição, NFS-e v1 e, medido em 2026-10-16, o cálculo de tributos; - a chave principal é recusada (
403) nos hosts de consulta medidos: CNPJ, CEP e NF-e por chave de acesso; - na leitura, as rotas de cadastro da conta aceitam as duas: empresas (lista na v1, item e lista na v2), inscrições municipais e estaduais, certificados, e webhooks nos dois hosts. A escrita com a chave de dados não foi testada.
O SDK não tinha bug: ele envia a chave principal a todo recurso de api.nfe.io e
api.nfse.io, e ela funciona em todas essas rotas. A aceitação da chave de dados no cadastro
não é contrato documentado, e o SDK não depende dela. README, MIGRATION.md,
docs/multi-host-routing.md, a skill e os JSDoc agora descrevem a regra por rota.
Evidência em api-key-route-matrix.json. O fixture de 2026-09-01 continua como registro
histórico, com supersededBy apontando para o novo, e a entrada 6.0.0 abaixo não foi
reescrita.
- O
package-lock.jsonestava na 5.2.0, porque a 6.0.0 só atualizou opackage.json. Agora acompanha a versão, etests/unit/version.test.tsfalha se os dois divergirem. - O cabeçalho de
src/index.tsainda dizia@version 5.1.0. A tag saiu, porque a versão vive só emsrc/version.ts, e oversion.test.tspassa a recusar@version X.Y.Zemsrc/. A varredura de literais continua ignorando comentários, que citam versões antigas como histórico. - Os testes de integração de
companiesque criam, alteram ou apagam empresas passam a exigirNFE_ALLOW_ACCOUNT_WRITES=true. Fora da CI, onpm testroda também a integração sempre que há chave no.env, e cada rodada deixava sete empresas na conta: ocompanies.removeresponde com sucesso, mas a empresa continua lá, com statusInactive(medido em 2026-10-16). Sem a variável, rodam só o404de empresa inexistente e a recusa de corpo inválido, que não gravam nada. Ligue a variável só com uma conta descartável.
6.0.0 - 2026-09-03
Major de correção de contrato. Nada aqui é funcionalidade nova: são bugs provados por sonda ao vivo contra a API real (2026-09-01 a 09-03), a maioria em métodos que nunca puderam funcionar. Em nenhum deles a especificação era a culpada — o SDK é que estava errado. Evidência versionada em
tests/fixtures/live-contracts/.É major porque nove pontos da superfície pública mudam de tipo ou de assinatura. Na prática, quase ninguém precisa mexer: as quebras são em superfícies que já estavam quebradas — métodos que só lançavam 404, retornos que vinham
undefined, tipos que mentiam sobre o que continham. O roteiro está noMIGRATION.md.Como esta rodada foi conduzida, porque explica o volume: contrato de API se decide na OpenAPI e em sonda contra a API real, nunca por inferência. Dois métodos que o diagnóstico anterior dava como quebrados não estavam — a amostra é que era a exceção.
-
Toda requisição do SDK mentia sobre quem era.
src/core/http/client.tsfixavapackageVersion = '3.0.0'com um// TODO: Read from package.json, e o User-Agent saía como@nfe-io/sdk@3.0.0— nome de pacote que não existe (o publicado énfe-io) e versão três majors atrás. Medido nos logs de gateway, 30 dias:93.995 requisições | 23 variantes de User-Agent | 5 majors de Node | 1 única versão de SDK reportadaAs 23 variantes diferem só no Node e na plataforma. O User-Agent é o único sinal de adoção que a plataforma tem, e não trazia informação nenhuma sobre a versão. A partir desta release dá para medir quem migrou.
O valor também divergia em quatro lugares:
3.0.0no User-Agent,5.1.0emPACKAGE_VERSIONe emVERSION,5.2.0nopackage.json. EPACKAGE_NAME— constante pública — dizia@nfe-io/sdk.Agora há fonte única:
src/version.ts, gerado dopackage.jsonporscripts/generate-version.ts(ligado aonpm run generate). Nenhum literal de versão sobrou emsrc/, etests/unit/version.test.tsfalha se algum voltar — a geração é a conveniência, o teste é a garantia.Nove exemplos de JSDoc mandavam
import { NfeClient } from '@nfe-io/sdk'. Corrigidos; a skill publicada não precisa mais avisar que o JSDoc mente. -
A documentação ensinava o wiring de credencial que a API recusa.
docs/multi-host-routing.mddizia queproductInvoices,productInvoicesRtc,stateTaxes,municipalTaxes,certificates,transportationInvoiceseinboundProductInvoicesusavam a chave de dados emapi.nfse.io. É host fiscal: responde403à chave de dados. Era o mesmo defeito corrigido no roteamento interno emb50bb74, ainda ensinado como se fosse o certo — quem seguisse a tabela reintroduzia o bug na própria aplicação. A tabela também omitiataxCalculatione o lado v2 decompanies.A nota de fallback deixou de sugerir que as chaves são alternativas: elas são complementares, e cada uma responde
403no território da outra. -
Dois exemplos copiáveis não compilavam. O README documentava
addresses.lookupByTerm()eaddresses.search(), removidos na v5. A skill publicada chamavauploadCertificate(companyId, certBuffer, 'password'), mas a assinatura recebe um objeto. Ambos corrigidos, etests/unit/docs-drift.test.tspassa a falhar quando qualquer documento cita método que não existe no código — README,docs/e a skill.A verificação casa nome de método, não assinatura: conferir assinatura exigiria compilar cada exemplo. Mesmo assim pega os dois casos desta rodada.
A skill também recebeu as correções de contrato de 01–02/09: rotas não servidas (
consumerInvoiceQuery,municipalTaxes.getSeries/updatePrefecture), oinvoiceIdobrigatório nos downloads de NFS-e, e o envelope real do status de certificado. -
Um teste existente travava o bug no lugar.
tests/unit/http-client.test.tsafirmava que o User-Agent continha@nfe-io/sdk— quem consertasse o nome quebrava a suíte. Corrigido para afirmar o nome real.
Sete métodos públicos foram diagnosticados como quebrados em julho. Reprovando um a um com sonda ao vivo, dois não estavam — o diagnóstico anterior generalizou a partir de uma amostra. A correção do registro está junto das correções de código.
-
healthCheck()respondiaerrorsempre. EnviavapageCount: 1, eGET /v1/companies?pageCount=1responde400 "pageCount must be between 1 and 50"— o limite inferior do servidor está um a mais do que a própria mensagem diz. Agora omite o parâmetro (a rota sem query responde200), em vez de carregar um número mágico contornando defeito alheio. O off-by-one vai para o time de API. -
companies.getCertificateStatus()lia uma forma que a API nunca devolveu. Esperava{hasCertificate, expiresOn, isValid}; a resposta é{certificates: [{providerType, resolution, taxPayerId, thumbprint, taxId, subject, validUntil, modifiedOn, status}]}. Nenhum dos três campos existe, então o retorno era{hasCertificate: undefined}e os derivados nunca eram calculados. Isso derrubava em cascatacheckCertificateExpiration(),getCompaniesWithCertificates()egetCompaniesWithExpiringCertificates()— quatro métodos públicos.O resumo mantém
expiresOnem vez de renomear paravalidUntil: é o mesmo nome que a API usa quando o certificado vem embutido na empresa. Os itens crus ficam expostos emcertificates, para quem precisa dethumbprintousubject.Empresa sem certificado responde
200comcertificates: [], não404. -
As duas varreduras de certificado por conta deixaram de fazer N+1.
getCompaniesWithCertificates()egetCompaniesWithExpiringCertificates()chamavamgetCertificateStatus()uma vez por empresa, em série. Enquanto o método estava quebrado isso era invisível; consertado, uma conta com 500 empresas faria 500 requisições sequenciais por chamada.A sonda dispensou o pool de concorrência:
GET /v1/companiesjá devolvecertificateem todo item ({thumbprint, modifiedOn, expiresOn, status}). As duas passam a ler daí. Medido: as duas varreduras juntas, sobre a conta inteira, em 9,8s. -
⚠️ BREAKING —serviceInvoices.downloadPdf()/downloadXml()exigem oinvoiceId. O parâmetro era opcional e a documentação prometia um ZIP com todas as notas. A rota não existe:/serviceinvoices/pdfresponde404 "service invoice with id (pdf) was not found", porque o servidor casa a rota/{id}e lêpdfcomo identificador. Não está na specnf-servico-v1nem na documentação da plataforma. Nota de migração emMIGRATION.md. -
O erro da API parava de chegar ao chamador.
extractErrorMessagesó liamessage/error/detail/details. A plataforma usa quatro envelopes:envelope onde "pageCount must be between 1 and 50"string JSON crua {"code":40001,"message":"..."}campo message{"errors":[{"message":"access key is not valid"}]}hosts de consulta {"title":"...","errors":{"file":["The File field is required."]}}ProblemDetails/ModelState Nos dois últimos a mensagem era descartada e o chamador recebia
HTTP 400 error— literalmente o status que ele já tinha. Foi assim queThe File field is required.ficou invisível enquanto o upload de certificado não funcionava. -
Acceptdos downloads por chave de acesso.productInvoiceQuery.downloadPdf/Xmlmandavam só o tipo binário; no caminho de erro o servidor não tem formatter para PDF e responde406com corpo vazio. ComAccept: application/pdf, application/json;q=0.9o caminho feliz não muda (mesmo status, mesmocontent-type, mesmos bytes) e o erro chega legível.Correção de registro: esses métodos não estavam quebrados. O
406medido em julho veio de uma chave de acesso inexistente; com chave real a resposta sempre foi200com%PDF-1.4.
Quatro métodos apontam para rotas declaradas na OpenAPI que não são roteadas em
produção: municipalTaxes.getSeries(), municipalTaxes.updatePrefecture(),
consumerInvoiceQuery.retrieve() e consumerInvoiceQuery.downloadXml().
A distinção foi feita comparando com um path inventado no mesmo host — 404 de corpo
vazio, sem content-type, byte a byte igual — e confirmada de forma independente: rota
servida responde 401 sem credencial; estas respondem 404 sem credencial, ou seja, o
middleware de autenticação nem chega a rodar. Noventa dias de log de gateway não têm um
único 200 em consumerinvoices/coupon.
Os métodos continuam emitindo a requisição — só o 404 passa a explicar que a rota não é
servida, preservando a classe do erro. Se a rota subir, o 200 passa intacto.
legalPeople e naturalPeople nunca estiveram quebrados. Os 14 métodos foram
registrados como "400 em toda chamada"; a sonda tinha usado a empresa do .env, cujo id
tem 32 caracteres. A rota valida o company_id como ObjectId de 24 hexadecimais. Sobre
50 empresas da mesma conta: 30 com id de 24 hex respondem 200, 19 com id de 32
caracteres respondem 400 "company id is not valid". Um id de 24 hex sintético responde
404 "Company not found." — o validador de formato passa e a busca é que falha.
É limite do servidor: não há conversão possível entre os formatos, e validar localmente só antecipa a mesma recusa com mensagem pior. Documentado no JSDoc dos dois recursos, com teste de integração afirmando as duas metades. Pendência aberta com o time de API.
-
O portão de publicação passou a poder reprovar.
.github/workflows/publish.ymlmarcava o passo de testes comcontinue-on-error: true, e um bloco logo abaixo justificava por escrito: "expected for integration tests without API credentials".A justificativa era falsa. Sem credencial a suíte dá 41 passed | 4 skipped, exit 0 — os testes de integração pulam, não falham; o guard
shouldRunIntegrationTests()cuida disso desde sempre. Ou seja: ocontinue-on-errorprotegia contra um modo de falha inexistente e, em troca, deixava passar todos os reais. Os três bugs de contrato corrigidos nesta mesma versão saíram por esse portão.Agora
publish.ymlroda testes,lint,typechecketest:typesantes do build, e qualquer um deles reprova a publicação. Otest:typestambém entrou noci.yml: eram 18 assertions — incluindo os guards de alinhamento de contrato — que nunca executavam. -
A suíte de integração voltou a ser executável.
dotenvera devDependency e nada carregava o.env, entãoNFE_API_KEYchegava vazia e a integração pulava sempre, inclusive na máquina de quem tinha credencial. Com o.envcarregado emtests/setup.ts, a execução local passou de 742 para 779 testes — 37 que nunca haviam rodado.Três assertions de
errors.integration.test.tsafirmavamArray.isArray(companies)contra umListResponse({ data, page }), e uma quarta liacompanies.length(undefined). Eram de antes da migração paraListResponsee nunca falharam porque nunca rodaram. Corrigidas.O guard não mudou: em CI a integração continua pulando sem
RUN_INTEGRATION_TESTS=true. Credencial de conta compartilhada não vai para runner. -
validate:specpassa a detectar drift entre cópias da mesma seção. 30 dos 131 endpoints das specs são declarados em mais de um arquivo (companies, certificates, statetaxes, webhooks) e as cópias divergem — algo que oSOURCES.jsonnão pegava, porque ele compara repo × docs e este drift é entre specs do mesmo lado.O
SOURCES.jsonganhousharedSections, declarando a fonte canônica de cada grupo, e ovalidate:specagora compara as cópias contra ela campo a campo, classificando emtype-mismatcheenum-mismatch(falham o build),enum-subset(aviso, a cópia está atrasada) e presença de campo (informativo). Diferença de prosa ou de forma ($ref× inline) não conta.As 116 divergências existentes entram como baseline declarada, cada uma com motivo e referência à pendência upstream — e uma entrada que deixe de reproduzir é reportada como obsoleta, para a baseline não virar tapete. O que falha o build é drift novo.
O
discoverSpecs()do validador também passou a aceitar.json:contribuintes-v2.json— canônica das seções de companies — nunca tinha sido validado.Sem efeito em runtime, tipos gerados ou API pública:
dist/index.d.tssai byte-idêntico.
-
Credencial errada em nove recursos fiscais. As duas chaves da plataforma são complementares, não intercambiáveis — cada uma responde
403nos hosts da outra família. O cliente HTTP deapi.nfse.ioresolvia a chave de dados num host fiscal, afetandoproductInvoices,productInvoicesRtc,transportationInvoices,inboundProductInvoices,municipalTaxes,certificates,stateTaxes,taxCalculatione o lado v2 decompanies.Esses recursos só funcionavam por acidente: quem configurava apenas
apiKeycaía no fallbackdataApiKey → apiKeye nunca via o problema. Quem configuravadataApiKey— o que a documentação recomenda para consultas — tomava403.Como migrar: se você usa
dataApiKey, nada a fazer — os nove recursos passam a funcionar. Se você configurava somentedataApiKeye acessava algum deles, agora é preciso informar tambémapiKey: o acesso lançaConfigurationErrorna hora, em vez de falhar com403na chamada.O mapa de qual chave vale em qual host está documentado em
NfeConfig.apiKey/NfeConfig.dataApiKey. -
NFC-e: parâmetros da spec não expostos e contrato de download divergente.
cancel()aceitareason(query definida pela spec) e devolveConsumerInvoiceCancellationResponseem vez da nota.getItems()/getEvents()aceitam paginação cursor (limit/startingAfter) e devolvem envelopes próprios, comhasMore. O de eventos deixa de reusar o tipo do recurso de produto, que tem outra forma.downloadPdf()aceitaforce. Os três downloads passam a devolverConsumerInvoiceFileResource({ uri }) em vez deBuffer: a API devolve JSON com URL e ignora o headerAccept. O retorno anterior já era este objeto se passando porBuffer— nenhum chamador correto quebra.retrieve(),getItems()egetEvents()param de enviarenvironment, que a spec não define nessas rotas.
Como migrar: baixe a URL devolvida pelos downloads.
const res = await nfe.consumerInvoices.downloadPdf(companyId, invoiceId); const bytes = await fetch(res.uri!).then((r) => r.arrayBuffer());
Atenção: o envelope da NFC-e usa
uri; o das rotas de entrada usapublicTemporaryUri. São tipos distintos de propósito.list()continua exigindoenvironment: a API responde400 environment has to be production or testsem ele. A spec marca o parâmetro como opcional e está errada. -
Downloads de documentos de entrada (CT-e e NF-e Distribuição) devolviam objeto tipado como texto. As rotas
/inbound/{chave}/xml,/pdfe/inbound/{chave}/events/{evento}/xmlrespondem com{ publicTemporaryUri }— uma URL pré-assinada e temporária. Binário nunca trafega nessas rotas e o headerAcceptnão altera a resposta.Os cinco métodos (
inboundProductInvoices.getXml,.getPdf,.getEventXml,transportationInvoices.downloadXml,.downloadEventXml) passam a devolver o novo tipoInboundFileResourceem vez destring.Como migrar: baixe a URL devolvida.
const res = await nfe.inboundProductInvoices.getPdf(companyId, accessKey); const bytes = await fetch(res.publicTemporaryUri!).then((r) => r.arrayBuffer());
Nenhum chamador correto quebra: o retorno anterior já era este objeto se passando por
string. O envelope é diferente do de NFC-e/NF-e produto, que usauri— por isso o tipo é separado deNfeFileResource. -
companies.uploadCertificate()nunca funcionou. O campo multipart era enviado comocertificate; a API faz binding defilee respondia400 {"errors":{"file":["The File field is required."]}}— ou seja, o método não tinha como completar. A assinatura pública não mudou.
5.2.0 - 2026-07-13
Correção do contrato de paginação de
companiescontra a API real, provado por sonda ao vivo (2026-07-13, duas contas). O request deGET /companiesé 1-based — a API rejeitapageIndex: 0com"pageIndex must be greater or equal to 1"— igual ao deserviceInvoices(rejeição depageIndex: 0reconfirmada ao vivo), não o oposto como se supunha.
companies.listAll()ecompanies.listIterator()falhavam na primeira chamada, por dois motivos independentes: (1) iniciavam a paginação empageIndex = 0, que a API rejeita — agora iniciam em1; (2) pediampageCount: 100, mas a API limitaGET /companiesa 50 itens por página (sonda ao vivo: aceita 2–50; rejeita 1, apesar da mensagem"between 1 and 50", e rejeita ≥51) — agora pedem50. Consertados transitivamente os quatro métodos que dependem delistAll():findByTaxNumber,findByName,getCompaniesWithCertificatesegetCompaniesWithExpiringCertificates.companies.list()ecoavapageCount: 100como default nopageda resposta; o default real da API é 10 itens quandopageCounté omitido.⚠️ JSDoc decompanies.update()era ativamente enganoso: dizia "only fields to update" (semântica PATCH), mas a API faz PUT (substituição total) — update parcial seguindo o docblock resulta em 400 ou em campos zerados silenciosamente. O JSDoc agora documenta o replace integral com exemplo read-modify-write. As assinaturas frouxas (Partial<Company>/Omit<Company>) foram mantidas por compat; o aperto para os schemas estritos fica para a próxima major (política de versionamento) ou para a migração de CRUD v2.- JSDoc de
companies.create()documenta os obrigatórios reais do corpo (name,federalTaxNumber,taxRegime,address) e queemailnão faz parte dele; exemplo corrigido (o anterior compilava e falhava com 400). - Vitest coletava os testes 5× através dos symlinks
client-php/client-ruby(que apontam de volta para este repo), causando flakes por corrida no.test-tempcompartilhado e inflando a suíte (3710 → 698 testes reais). Oincludeagora é restrito atests/**.
companies.list()(API v1, paginação offset): a API v1 de companies está sendo descontinuada. UselistV2()(cursor, v2) para listagem paginada, oulistAll()/listIterator()para varredura completa. O método continua funcionando (e corrigido — ver acima) durante a convivência. Nota:listAll()/listIterator()permanecem no transporte v1 nesta release porque a enumeração completa via v2 falha de forma determinística em contas com certos registros (HTTP 500 server-side em qualquer janela que os contenha — bug reportado ao backend em 2026-07-14), e porque as projeções v1/v2 divergem de campos. A troca de transporte fica para quando o backend corrigir o 500.- JSDoc de
companies.listeserviceInvoices.list,docs/API.mdeREADMEexemplificavampageIndex: 0— todos corrigidos para a convenção 1-based. PaginationOptions.pageIndexePageInfo.pageIndexdocumentados como 1-based (a primeira página é 1).- Specs OpenAPI (
nf-servico-v1.yaml):pageIndexagora declaraminimum: 1em/v1/companiese na listagem de notas de serviço;pageCountde/v1/companiesdeclaramaximum: 50.
⚠️ Nota de migração:companies.list()deixou de subtrair 1 da resposta.list({ pageIndex: 1 }).page.pageIndexagora retorna1(antes retornava0). A convenção do SDK passa a ser 1-based nos dois lados (request e response), fiel ao fio da API. Se seu código liapage.pageIndexassumindo base 0 (ex.:pageIndex + 1para exibir o número da página), remova o ajuste.
companies.listV2()— listagem pela API v2 (api.nfse.io/v2/companies, contribuintes-v2), cursor-based:{ limit (1–50, default 10), startingAfter, endingBefore }→{ data, hasMore }(contrato provado ao vivo em 2026-07-14). Os itens seguem a projeção v2 (CompanyResourceItem) — shape diferente doCompanyv1 (sem campos de configuração NFS-e; comstateTaxes,municipalTaxes,type,version).limitfora de 1–50 é rejeitado client-side (a API aceitarialimit: 0devolvendo página vazia). Tipos novos:CompanyV2ListOptions,CompanyV2ListResponse.- Testes de contrato de paginação: mock espelha a rejeição da API a
pageIndex: 0e trava a regressão —listAll/listIteratorsão testados iniciando em 1 e incrementando 1 → 2; suite equivalente para o contrato cursor dolistV2. - Teste de alinhamento de tipos para os corpos de escrita de companies
(
tests/types/company-write-alignment.test-d.ts): pina os obrigatórios deCreateCompanyResourceItem/UpdateCompanyResourceItem(mesmo conjunto — evidência da semântica PUT) e a ausência deemailno corpo; um sync de spec que mude o contrato quebra onpm run test:typesem vez de driftar.
5.1.0 - 2026-07-03
Correção do contrato de webhooks contra a API real, provado por sonda ao vivo (2026-07-02/03, três contas). O contrato correto sempre esteve nos specs oficiais (
openapi/spec/nf-servico-v1.yamle equivalentes) — o recurso manuscrito havia divergido deles.
createAccountWebhookfuncionava 0% das vezes: a API exige o request envelopado em{ "webHook": {...} }(sem ele responde400 "missing required properties including: 'webHook'") e devolve a resposta também envelopada. O SDK agora envelopa o request (create/update) e desembrulha as respostas (create/retrieve/update), com fallback defensivo para corpo cru.listAccountWebhooks/retrieveAccountWebhook/updateAccountWebhookagora tipados com o shape real do recurso (verAccountWebhookabaixo).
- Tipo
AccountWebhookcom o shape real da API:uri,contentType,secret(32–64 caracteres, ecoado no create e omitido nas leituras),filters,insecureSsl,headers,properties,status,createdOn,modifiedOn. Nota: o spec declaracontentType/statuscomo enums inteiros, mas a API serializa strings ("json","Active") — o tipo segue o fio real. - Tipo
WebhookEventType(união aberta) com os 46 event types reais deGET /v2/webhooks/eventTypes(service_invoice.issued_successfully, etc.). - Teste de alinhamento (
tests/types/account-webhook-alignment.test-d.ts) amarrando oAccountWebhookao schema gerado do spec oficial — um sync de spec que mude o contrato de webhooks quebra onpm run test:typesem vez de driftar. - JSDoc do
createAccountWebhookdocumenta a verificação de URI na criação (a NFE.io faz um ping e exige resposta 2xx). - JSDoc do
updateAccountWebhookdocumenta que oPUTé substituição integral (confirmado ao vivo em 2026-07-03): campos omitidos voltam ao padrão — update semstatusdesativa o webhook. Envie o objeto completo (parta do retrieve).
- Métodos company-scoped de webhooks (
list,create,retrieve,update,delete,testsobre/v1/companies/{id}/webhooks): a rota retorna 404 na API atual (confirmado em três contas, 2026-07-02/03). Use os equivalentes account-scoped. O comportamento não mudou; remoção fica para a próxima major. - Tipos
WebhookeWebhookEvent: shapes que a API real rejeita. UseAccountWebhookeWebhookEventType.
5.0.0 - 2026-06-30
Primeira release de funcionalidades desde a v3 — a v4 foi apenas o bump de runtime (Node 22), sem mudanças de API. A v5 reúne os novos recursos (RTC, NFC-e, inscrições municipais, certificados, notificações, webhooks de conta) e correções de contrato descobertas testando contra a API ao vivo. Guia: MIGRATION.md.
Todas as quebras são em superfícies que já estavam quebradas (métodos que só lançavam
404, retornos que vinham undefined); nenhum código correto deixa de funcionar, mas
usuários TypeScript devem revisar estes pontos no upgrade:
addresses.lookupByPostalCode()agora retorna umAddress(antes retornava o envelope cru tipado como{ addresses: Address[] }). Acesse os campos direto:address.streetem vez deresult.addresses[0].street.addresses.search()eaddresses.lookupByTerm()removidos — os endpoints não existem no host real (404). UselookupByPostalCode(). O tipoAddressSearchOptionsfoi removido eAddressLookupResponseagora descreve o envelope{ address: Address }.serviceInvoices.cancel()agora retornaCancelInvoiceResponse(união discriminada{ status: 'async', response } | { status: 'immediate', invoice }), pois o cancelamento é assíncrono. Antes retornava um stub tipado comoServiceInvoiceData. UsecancelAndWait()para bloquear até concluir.CertificateValidator.validate()não retorna maismetadatafabricada (subject/ issuer/validade falsos). O pré-flight local é só de formato; os dados do certificado são verificados no servidor durante o upload.
companies.exists(companyId): checagem de existência viaHEAD /v2/companies/{id}(api.nfse.io; 404 →false). HTTP client ganhou o verbohead.nfe.notifications(NotificationsResource, api.nfe.io):list/retrieve/delete/sendEmailde notificações da empresa.serviceInvoices.retrieveByExternalId(companyId, externalId): busca por id externo (idempotência/reconciliação).stateTaxes.switchAuthorizer(companyId, stateTaxId, data?): troca de autorizador NF-e (POST .../switch-authorizer).
nfe.certificates(CertificatesResource, api.nfse.io):list,getByThumbprint/deleteByThumbprint(v2) e variantes v1 (getByThumbprintV1/deleteByThumbprintV1). Cobre o gap da consulta/remoção de certificado por thumbprint. Complementa ocompanies.uploadCertificatelegado (host api.nfe.io) — recurso dedicado por estar em host diferente (contribuintes-v2 @ api.nfse.io).
nfe.consumerInvoices(ConsumerInvoicesResource, api.nfse.io): ciclo de vida da NFC-e company-scoped —create(webhook-driven, sem polling),list,retrieve,cancel,getItems,getEvents,downloadPdf/downloadXml/downloadRejectionXml, edisable(inutilização). Distinto doconsumerInvoiceQuery(consulta de cupom, somente leitura). Tipos:ConsumerInvoiceData,ConsumerInvoice,ConsumerInvoiceDisablementData.
nfe.municipalTaxes(MunicipalTaxesResource, api.nfse.io): CRUD de inscrições municipais — pré-requisito para emissão de NFS-e —, espelhandostateTaxes. IncluiupdatePrefecture(HTTP PATCH.../updateprefecture) egetSeries(.../series/{serie}). Tipos:MunicipalTax,CreateMunicipalTaxData,UpdateMunicipalTaxData.- HTTP client ganhou o verbo
patch(mesma cadeia de retry/timeout/erro dos demais).
WebhooksResourceganhou operações de conta (/v2/webhooks, semcompanyId):listAccountWebhooks,createAccountWebhook,retrieveAccountWebhook,updateAccountWebhook,deleteAccountWebhook,pingAccountWebhook, edeleteAllAccountWebhooks(método distinto e marcado como destrutivo). Os métodos company-scoped existentes seguem inalterados.fetchEventTypes(): lista de tipos de evento ao vivo (GET /v2/webhooks/eventTypes), com retorno em união aberta.getAvailableEvents()(lista hardcoded) foi marcado@deprecated.
- Spec
contribuintes-v2(Empresas, OpenAPI 3.x) adotada na geração — destrava tipos reais de empresa/certificado/endereço. Companyenriquecido de forma aditiva (minor, sem quebra): mantém os campos atuais e o índice[key: string]: unknown, e adiciona os campos documentados do spec (address,taxRegime,tradeName,stateTaxes, …) como opcionais — melhora o autocomplete sem apertar o tipo nem o input docreate().- Novos tipos exportados (opt-in, estritos):
CompanyResourceItem,CompanyResourceV1,CreateCompanyResourceItem,UpdateCompanyResourceItem,CertificateMetadataResource,CompanyAddress. - Guard de regressão de tipo executável:
npm run test:types(vitest typecheck) garante que leituras de campo arbitrário continuam compilando e quefederalTaxNumberseguenumber.
nfe.serviceInvoicesRtc: emissão de NFS-e no leiaute RTC (grupoibsCbs), comcreate/createAndWait(polling) edownloadCancellationXml(XML do evento de cancelamento — Ambiente Nacional). Mesmo endpoint da emissão atual; RTC é selecionado pelo payload. Tipo de request:NFSeRtcRequest(schemaNFSeRequest).nfe.productInvoicesRtc: emissão de NF-e/NFC-e no leiaute RTC (IBS estadual/municipal, CBS, IS),createwebhook-driven (não faz polling), espelhandoproductInvoices. Tipo de request:ProductInvoiceRtcRequest(schemaProductInvoiceRequest).- Recursos de emissão existentes (
serviceInvoices/productInvoices) permanecem inalterados; RTC é opt-in. Proveniência das specs registrada emopenapi/spec/SOURCES.json(NT_2025.002_v1.30). - Pipeline de geração agora descobre specs
.jsone falha em skip inesperado (allowlist dos 5 Swagger 2.0 legados).
- CertificateValidator:
validate()deixou de fabricar metadata (subject/issuer/validade falsos) e de reportar validade de 1 ano para qualquer arquivo bem-formado. Agora é um pré-flight só de formato (buffer, senha presente, magic bytes PKCS#12); subject/issuer/validade e a senha são verificados no servidor durante o upload.metadatapassa a ser ausente no pré-flight local. updateConfig(): agora invalida todos os resources e HTTP clients em cache (viaresetCaches()). Antes, resetava apenas ~10 —productInvoices,stateTaxes,taxCalculation,taxCodes, lookups e os clients de query/legalEntity/naturalPerson permaneciam com a configuração antiga apósupdateConfig.- README: exemplo de webhook corrigido para o header
x-hub-signature(HMAC-SHA1), alinhado ao fix de verificação de assinatura; antes referenciavax-nfe-signature. addresses.lookupByPostalCode(): passou a desempacotar o envelope{ address }da API e retornar um únicoAddress. Antes retornava o envelope cru tipado como{ addresses: Address[] }— quem seguia o JSDoc (result.addresses[0].street) recebiaundefined. Verificado contra a API ao vivo (address.api.nfe.io/v2).addresses.search()eaddresses.lookupByTerm()removidos: os endpoints que chamavam (/v2/addressese/v2/addresses/{term}) respondem 404 no host real — os métodos só lançavamNotFoundError. Como nunca funcionaram, a remoção não quebra nenhum consumidor real. O tipoAddressSearchOptionsfoi removido eAddressLookupResponseagora descreve o envelope real ({ address: Address }). Se o backend confirmar um endpoint de busca, ele volta como change separada com contrato verificado.serviceInvoices.cancel(): o cancelamento de NFS-e é assíncrono (HTTP202+Location). Antes,cancel()retornava o stub de polling{ code, status, location }tipado comoServiceInvoiceData(entãocancelled.id/flowStatusvinhamundefined). Agora retorna uma união discriminadaCancelInvoiceResponse({ status: 'async', response }ou{ status: 'immediate', invoice }), espelhandocreate(). Novo métodocancelAndWait()faz polling até o cancelamento concluir (espelhacreateAndWait). Verificado contra a API ao vivo. Tipos exportados:CreateInvoiceResponse,CancelInvoiceResponse.
taxCodes.*: passou a usar a chave principal (apiKey) contraapi.nfse.io. Antes estava ligado ao cliente CT-e (chave de dados), o que retornava 403 em setups comdataApiKeyseparada. Os 4 endpoints (/tax-codes/*) agora respondem 200.consumerInvoices.list(): agora exigeenvironment(Production/Test), obrigatório pela API — antes a chamada saía sem o parâmetro e retornava 400. Também passou a usar a chave principal (antes 403 com chave de dados separada). Os métodos de leitura (retrieve/getItems/getEvents/downloads) aceitamenvironmentopcional.webhooksde conta: os métodos de conta (listAccountWebhooks,createAccountWebhook,fetchEventTypes, etc.) montavam o caminho/v1/v2/webhooks(duplo prefixo de versão) → 404. Agora usam um cliente dedicado emapi.nfe.io/v2. Além disso,listAccountWebhooksdesempacota o envelope{ webHooks }para{ data }efetchEventTypesextrai os ids de{ eventTypes }.
4.0.0 - 2026-06-12
O único requisito novo é Node.js >= 22 (Node 18 e 20 atingiram fim de vida em abr/2025 e abr/2026). Não há nenhuma mudança de API — todo código escrito para a v3 funciona sem alterações. Quem ainda precisa de Node 18/20 deve permanecer no nfe-io@^3.2. Veja MIGRATION.md.
Zeradas todas as vulnerabilidades reportadas pelo Dependabot e pelo Code Scanning (CodeQL). Nenhuma afetava o pacote publicado (zero dependências de runtime) — todas estavam em ferramentas de build/teste e CI. Rastreamento completo em #31.
- vitest (crítica, GHSA-5xrq-8626-4rwp): leitura/execução arbitrária de arquivos com o servidor do Vitest UI ativo — resolvida pelo upgrade para vitest 4
- esbuild (baixa, GHSA-g7r4-m6w7-qqqr): leitura arbitrária de arquivos no dev server em Windows — eliminada da árvore pela migração tsup → tsdown; o esbuild residual (via tsx) já usa a versão corrigida 0.28.1
- CodeQL (7 alertas, via #32): permissions mínimas do
GITHUB_TOKENno CI, remoção do script mortoscripts/download-openapi.tse remoção do código legado v2 (lib/) - Resultado:
npm auditreporta 0 vulnerabilidades e security tab zerada
- Build: tsup → tsdown (Rolldown/Rust) — mesmo output dual ESM/CJS + declarações de tipos, target
node22 - Testes: vitest 3.2.4 → 4.1.8 (+
@vitest/ui,@vitest/coverage-v8) - CI: matriz de testes Node 22/24 (antes 18/20/22); actions atualizadas para majors compatíveis com Node 24 (
checkout@v6,setup-node@v6,upload-artifact@v7,github-script@v9,codecov@v7) — runners do GitHub passam a executar actions em Node 24 a partir de 16/06/2026 - Tipos:
@types/node^20 → ^22 - vitest.config.ts: corrigida opção inexistente
testMatch→include; thresholds de coverage no formato achatado do vitest
- Skill renomeada de
nfeio-sdkparanfeio-node-sdk— fixa a convenção cross-SDK (<org>-<linguagem>-sdk) antes da publicação no skills.sh - Corrigido o path do bloco
agents.skillsnopackage.json, que apontava para diretório inexistente (./skills/nfe-io-sdk) - Requisito documentado na skill atualizado para Node.js 22+
3.2.1 - 2026-06-11
WebhooksResource.validateSignature() foi reescrita para corresponder ao esquema real usado pela NFE.io em produção. Todas as versões anteriores rejeitavam silenciosamente qualquer assinatura legítima — verificado por sondagem ao vivo contra api.nfse.io.
O que estava errado:
- Documentação e exemplos referenciavam
X-NFE-Signature— o header correto éX-Hub-Signature. - O método computava HMAC-SHA256 — a NFE.io usa HMAC-SHA1.
- O hex era comparado case-sensitive — a NFE.io envia em MAIÚSCULAS.
- O prefixo
sha1=enviado no header não era removido antes da comparação. - O
require('crypto')em runtime falhava (não funciona em ESM nem CJS de módulo), fazendo o método retornarfalsepara tudo.
O que mudou na API:
validateSignature(payload, signature, secret)agora aceitapayloadcomoBuffer | string(era sóstring) esignaturecomostring | string[] | undefined(era sóstring).- A comparação é case-insensitive sobre o hex, com tratamento explícito do prefixo
sha1=. - O método nunca lança exceção — todo erro/entrada malformada retorna
false.
Migração: use express.raw() (ou equivalente) para passar req.body como Buffer direto. JSON.stringify(req.body) NÃO funciona porque a ordem das propriedades e os espaços diferem dos bytes que a NFE.io assinou. Exemplo completo no docs/API.md e em examples/real-world-webhooks.js.
Cabeçalhos úteis que a NFE.io também envia (agora documentados): X-Hook-Id (UUID por entrega, ideal para idempotência), X-Hook-Attempts (contador de retries), Content-MD5 (MD5 base64 do body).
3.2.0 - 2026-04-25
Atualização de dependências de desenvolvimento para resolver vulnerabilidades reportadas pelo npm audit. Nenhuma alteração no comportamento em runtime — todas as vulnerabilidades estavam em ferramentas de build/teste, não distribuídas no pacote publicado.
- Resolvidas 14 vulnerabilidades (7 high, 7 moderate) em devDependencies:
undici(alto): GHSA-g9mf-h72j-4rw9, GHSA-2mjp-6q6p-2qxm, GHSA-vrm6-8vpv-qv8q, GHSA-v9p9-hfj2-hcw8, GHSA-4992-7rv2-5pvq (viaopenapi-typescript)minimatch(alto): GHSA-3ppc-4f35-3m26, GHSA-7r86-cg39-jmmj, GHSA-23c5-xmqv-rm74 (via@typescript-eslint)esbuild(moderado): GHSA-67mh-4wv8-2f99 (viavitest)
- Resultado:
npm auditagora reporta 0 vulnerabilidades
@typescript-eslint/eslint-plugin:^6.21.0→^8.59.0@typescript-eslint/parser:^6.21.0→^8.59.0vitest:^1.6.1→^3.2.4@vitest/coverage-v8:^1.6.1→^3.2.4@vitest/ui:^1.6.1→^3.2.4openapi-typescript:^6.7.0→^7.13.0
Nota: Vitest foi atualizado para 3.2.4 (não 4.x) para manter compatibilidade com Node 18 — vitest 4 depende do
rolldown, que requer Node 20+. O esbuild patcheado já está disponível na linha 3.x via Vite.
Adaptação do script scripts/generate-types.ts para a nova API do openapi-typescript v7:
- Migração para nova assinatura:
openapiTS()agora retorna AST e usaastToString()para conversão - Input convertido para
URLviapathToFileURL(exigência do v7) - Opção
immutableTypesrenomeada paraimmutable; opçãoexportTyperemovida (agora é padrão) - Adicionada configuração Redocly (
createConfig) para tolerar specs legados que falhariam na validação estrita do v7
Ajustes em testes (nenhum teste foi adicionado/removido):
- 30 chamadas em testes de integração migradas da assinatura
it(name, fn, opts)para a novait(name, opts, fn)(compatível com vitest 3.x e futura migração para 4.x) - Mock de
FormDataemtests/unit/companies.test.tsajustado para usarfunctionao invés de arrow function (boa prática de mock de construtor) - 606 testes passando, 47 skipped (mesma cobertura de antes), validados em Node 18, 20 e 22
openapi/spec/nf-servico-v1.yaml:operationIddo endpointGET /v1/companies/{company_id}/serviceinvoices/external/{id}renomeado deServiceInvoices_idGetparaServiceInvoices_externalIdGet. Resolve duplicata real no spec —openapi-typescriptv6 silenciosamente fundia as duas operações distintas em uma só. Esta mudança é apenas em metadata de geração de código, não afeta o comportamento da API.
Usuários que referenciam tipos gerados internos (ex.: operations["ServiceInvoices_idGet"] em src/generated/) podem precisar de pequenos ajustes:
- Para o endpoint
/serviceinvoices/external/{id}: usaroperations["ServiceInvoices_externalIdGet"](anteriormente fundido comServiceInvoices_idGet) - A maioria dos consumidores que usa apenas
NfeCliente seus métodos públicos não é afetada
3.1.0 - 2026-02-22
Esta release representa uma expansão significativa do SDK, transformando-o de uma solução focada em NFS-e para uma plataforma completa de gestão de documentos fiscais eletrônicos brasileiros.
- Consulta via Distribuição DFe: Acesso a CT-e recebidos automaticamente
- Habilitação/Desabilitação: Ativar ou desativar busca automática de CT-e para empresas
- Configuração de NSU: Iniciar busca a partir de NSU específico ou data
- Download de XML: Baixar XML do CT-e e eventos associados
- Consulta por Chave: Buscar CT-e específico por chave de acesso (44 dígitos)
- Eventos: Consultar e baixar XML de eventos do CT-e
Exemplos: examples/transportation-invoices.js
- Consulta de NF-e Recebidas: Acesso a NF-e via Distribuição DFe
- Manifestação Automática: Configurar manifestação automática (Ciência, Confirmação, etc.)
- Múltiplos Ambientes: Suporte a Produção e Homologação SEFAZ
- Download de XML Completo: Baixar XML completo da NF-e
- Consulta Detalhada: Buscar por chave de acesso com informações completas
- Gestão de Configuração: Ativar/desativar busca automática por empresa
Exemplos: examples/inbound-product-invoices.js
- Busca Detalhada: Consultar NF-e emitida por chave de acesso (44 dígitos)
- Informações Completas: Emitente, destinatário, itens, impostos, transporte, pagamento
- Eventos Associados: Consultar cancelamento, carta de correção, etc.
- Validação: Verificar situação da NF-e na SEFAZ
Exemplos: examples/product-invoice-query.js
- Consulta por Chave: Buscar cupom fiscal SAT por chave de acesso
- Informações de Venda: Emitente, comprador, itens, pagamento
- Impostos Detalhados: ICMS, PIS/PASEP, COFINS, ISSQN por item
- Validação de Status: Verificar status do cupom fiscal
Exemplos: examples/consumer-invoice-query.js
- Informações Básicas: Razão social, nome fantasia, regime tributário, porte, status
- Inscrições Estaduais por Estado: Consultar IE específica de qualquer estado
- IE para Nota Fiscal: Obter IE válida para emissão de NF-e/NFS-e
- Dados Cadastrais Completos: Endereço, telefone, atividades econômicas, sócios
- Validação de CNPJ: Verificar se CNPJ está ativo e regular
Exemplos: examples/cnpj-lookup.js
- Validação de CPF: Verificar situação cadastral na Receita Federal
- Status Detalhado: Regular, Pendente de Regularização, Cancelado, Suspenso, etc.
- Integração com Cadastro: Validar CPF antes de criar pessoa física
Exemplos: examples/cpf-lookup.js
- Criação de NF-e: Emitir Nota Fiscal Eletrônica de Produto
- Cancelamento: Cancelar NF-e com justificativa
- Carta de Correção: Enviar eventos de correção
- Download de Documentos: Baixar PDF e XML da NF-e
- Consulta de Status: Verificar situação da NF-e
- Gestão de Eventos: Consultar todos os eventos associados
Exemplos: examples/product-invoices.js
- Cálculo Automático: ICMS, IPI, PIS, COFINS, Imposto de Importação
- Múltiplos Itens: Calcular impostos para vários produtos em uma requisição
- Regimes Tributários: Suporte a Simples Nacional, Lucro Real, Lucro Presumido
- Origem e Destino: Cálculo considerando estados de origem e destino
- Detalhamento por Item: Impostos calculados individualmente para cada item
Exemplos: examples/tax-calculation.js
- Lista de CFOP: Códigos Fiscais de Operações e Prestações
- Lista de NCM: Nomenclatura Comum do Mercosul
- Origens de Mercadoria: Códigos de origem (0-8)
- Exportação para CSV: Exportar listas completas
API: Métodos listCfop(), listNcm(), listOrigins()
- Lista por Estado: Obter todas as IE de uma empresa em um estado específico
- Busca por CNPJ e Estado: Consultar IE específica
- Validação: Verificar IE ativas e válidas
Exemplos: examples/state-taxes.js
- Novo parâmetro
dataApiKey: UnificaaddressApiKeyecteApiKeyem uma única chave - Múltiplos Hosts de API: Suporte a 4 hosts diferentes (api.nfe.io, api.nfse.io, address.api.nfe.io, nfe.api.nfe.io)
- Fallback Automático:
dataApiKeyfaz fallback paraapiKeyse não especificado
- Multi-API Support: HTTP clients especializados para cada API externa
- Lazy Loading: Clientes HTTP criados apenas quando necessários
- Configuração Flexível: Base URLs configuráveis por tipo de API
- 227+ Novos Tipos: Tipos completos para todos os 10 novos recursos
- Enums Abrangentes: Estados brasileiros, status de documentos, métodos de pagamento, regimes tributários
- Exportações Públicas: Todos os tipos disponíveis para consumo externo
- README.md: Adicionadas seções completas para todos os 10 novos recursos (+411 linhas)
- API.md: Documentação detalhada de cada método novo (+1,212 linhas)
- Exemplos Práticos: 9 novos arquivos de exemplo com casos de uso reais
- JSDoc Completo: Documentação inline em todos os métodos públicos
- 11 Novos Arquivos de Teste: Cobertura completa dos novos recursos (+3,882 linhas)
- Testes Unitários: Validação de parâmetros, tratamento de erros, mocks de API
- Integração Multi-API: Testes para diferentes hosts e configurações
- Validação de Tipos: Testes de TypeScript para garantir type-safety
- CI/CD: Adicionados triggers para branches
bugfix/*echore/* - .gitignore: Corrigida entrada do diretório
client-python - .gitignore: Removidos arquivos de teste obsoletos
- OpenAPI Specs: Renomeado
cpf-api.yamlparaconsulta-cpf.yamlpara consistência - Generated Files: Atualizados timestamps de regeneração dos tipos OpenAPI
- Documentação: Corrigidos headers de seção para NF-e de Produto e NF-e de Entrada
addressApiKey→ usedataApiKeycteApiKey→ usedataApiKey
Nota: Os parâmetros antigos ainda funcionam, mas é recomendado migrar para dataApiKey para unificar a configuração.
// ❌ Antes (ainda funciona, mas deprecado)
const nfe = new NfeClient({
apiKey: 'sua-chave-principal',
addressApiKey: 'chave-consultas',
cteApiKey: 'chave-consultas'
});
// ✅ Agora (recomendado)
const nfe = new NfeClient({
apiKey: 'sua-chave-principal',
dataApiKey: 'chave-consultas' // Unificado
});- Arquivos Modificados: 58 arquivos
- Linhas Adicionadas: +14,176
- Linhas Removidas: -102
- Crescimento de Recursos: 5 → 15 (+200%)
- Novos Tipos Exportados: +227 tipos
- Commits: 17 commits
- Período de Desenvolvimento: 16/02/2026 - 22/02/2026
- ✅ Service Invoices - NFS-e (Notas Fiscais de Serviço)
- ✅ Companies - Gestão de Empresas
- ✅ Legal People - Pessoas Jurídicas (Tomadores/Prestadores)
- ✅ Natural People - Pessoas Físicas
- ✅ Webhooks - Notificações de Eventos
- ✅ Addresses - Consulta de CEP
- ✅ Transportation Invoices - CT-e (Transporte) 🆕
- ✅ Inbound Product Invoices - NF-e de Entrada 🆕
- ✅ Product Invoice Query - Consulta NF-e 🆕
- ✅ Consumer Invoice Query - Consulta CFe-SAT 🆕
- ✅ Legal Entity Lookup - Consulta CNPJ 🆕
- ✅ Natural Person Lookup - Consulta CPF 🆕
- ✅ Product Invoices - NF-e de Produto 🆕
- ✅ Tax Calculation - Cálculo de Impostos 🆕
- ✅ Tax Codes - Códigos Auxiliares 🆕
- ✅ State Taxes - Inscrições Estaduais 🆕
3.0.2 - 2026-01-19
- Build: Corrigido warning do tsup sobre ordem do campo
typesno package.json exports - Errors: Adicionado getter
statusCodena classeNfeErrorpara total compatibilidade com testes - Testes de Integração: Melhorada lógica de skip para considerar valores de teste como inválidos
- Testes de Polling: Corrigidos testes de timeout para evitar unhandled rejections no CI
- Testes Unitários: Ajustados testes para usar
.catch()e prevenir erros assíncronos não tratados - CI/CD: Resolvidos 2 erros de unhandled rejection que causavam falha no GitHub Actions
- Configuração: Removido
prepublishOnlycom testes do package.json para evitar falhas por warnings de teste - Testes: Melhorada limpeza de timers falsos no afterEach dos testes de polling
- Qualidade: 100% dos testes passando (281 passed, 37 skipped) sem erros assíncronos
3.0.1 - 2026-01-18
- Testes: Adicionada propriedade
statuscomo alias decodeemNfeErrorpara compatibilidade - Service Invoices: Corrigida extração de path do location header para preservar prefixo
/v1 - Service Invoices: Corrigido
getStatuspara identificar corretamente status de falha como terminal - Testes de Integração: Agora são pulados gracefully quando
NFE_API_KEYnão está definida - Testes Unitários: Corrigidas múltiplas assertions e timeouts
- Mensagens de Erro: Melhoradas mensagens de erro para respostas async sem Location header
- Melhorada documentação de extração de path do location header
3.0.0 - 2026-01-18
Reescrita completa do SDK NFE.io - SDK TypeScript moderno com zero dependências em runtime e API async/await limpa e intuitiva.
- 🎯 TypeScript Nativo - Segurança de tipos completa com IntelliSense rico
- 🚀 Zero Dependências em Runtime - Usa Fetch API nativa do Node.js 18+
- ⚡ API Moderna Async/Await - Sem callbacks, código mais limpo e legível
- 🔄 Retry Automático - Lógica de retry inteligente com exponential backoff
- 📦 Suporte Dual ESM/CommonJS - Funciona com ambos os sistemas de módulos
- 🧪 Bem Testado - Mais de 80 testes com 88% de cobertura de código
- 📖 Documentação Completa - JSDoc em todas as APIs públicas com exemplos
- NfeClient - Cliente principal com configuração flexível
- Suporte a ambientes
productionedevelopment - Configuração de timeout personalizável
- Retry configurável com exponential backoff
- Suporte a variáveis de ambiente (
NFE_API_KEY) - Método
updateConfig()para configuração dinâmica - Método
getConfig()para consultar configuração atual - Método
pollUntilComplete()para polling automático genérico - Método estático
isEnvironmentSupported()para validação
- Suporte a ambientes
- ✅
create()- Criar nota fiscal com suporte a resposta 202 (processamento assíncrono) - ✅
createAndWait()- NOVO! Criar e aguardar processamento automaticamente - ✅
list()- Listar notas fiscais com paginação manual - ✅
retrieve()- Buscar nota fiscal específica por ID - ✅
cancel()- Cancelar nota fiscal emitida - ✅
sendEmail()- Enviar nota fiscal por email - ✅
downloadPdf()- Download do PDF da nota fiscal - ✅
downloadXml()- Download do XML da nota fiscal
- ✅
create()- Criar nova empresa - ✅
list()- Listar empresas cadastradas - ✅
retrieve()- Buscar empresa específica por ID - ✅
update()- Atualizar dados da empresa - ✅
uploadCertificate()- Upload de certificado digital A1 com suporte a FormData
- ✅
create()- Criar pessoa jurídica - ✅
list()- Listar pessoas jurídicas (scoped por company_id) - ✅
retrieve()- Buscar pessoa jurídica específica - ✅
update()- Atualizar dados da pessoa jurídica - ✅
delete()- Deletar pessoa jurídica - ✅
findByTaxNumber()- NOVO! Buscar pessoa jurídica por CNPJ - ✅
createBatch()- NOVO! Criar múltiplas pessoas jurídicas em lote
- ✅
create()- Criar pessoa física - ✅
list()- Listar pessoas físicas (scoped por company_id) - ✅
retrieve()- Buscar pessoa física específica - ✅
update()- Atualizar dados da pessoa física - ✅
delete()- Deletar pessoa física - ✅
findByTaxNumber()- NOVO! Buscar pessoa física por CPF - ✅
createBatch()- NOVO! Criar múltiplas pessoas físicas em lote
- ✅
create()- Criar webhook - ✅
list()- Listar webhooks configurados - ✅
retrieve()- Buscar webhook específico - ✅
update()- Atualizar configuração do webhook - ✅
delete()- Deletar webhook - ✅
validateSignature()- NOVO! Validar assinatura de segurança do webhook
Hierarquia completa de erros tipados para melhor tratamento:
NfeError- Classe base de erro com estrutura consistenteAuthenticationError- Erro de autenticação (401)ValidationError- Erro de validação com detalhes dos campos (400, 422)NotFoundError- Recurso não encontrado (404)RateLimitError- Limite de taxa atingido (429) comretryAfterServerError- Erro no servidor (5xx)ConnectionError- Erro de conexão de redeTimeoutError- Timeout na requisiçãoConfigurationError- Erro de configuração do clientePollingTimeoutError- Timeout no polling de processamento assíncronoErrorFactory- Factory inteligente para criar erros apropriados
Todos os erros incluem:
message- Mensagem descritivastatusCode- Código HTTPrequestId- ID da requisição para suportedetails- Detalhes adicionaisfields- (ValidationError) Campos com erro
- Fetch API nativa do Node.js 18+
- Retry automático com exponential backoff e jitter
- Suporte a timeout configurável
- Tratamento inteligente de status HTTP (202, 204, 4xx, 5xx)
- Headers customizados por requisição
- Gestão automática de autenticação (Basic Auth)
- Tipos TypeScript para todas as entidades da API
- Tipos de requisição e resposta
- Tipos de configuração
- Tipos de opções de polling
- Tipos de retry config
- Exports públicos bem definidos
- 80+ testes automatizados
- 88% de cobertura de código
- Testes unitários para toda lógica de negócio
- Testes de integração com mocks da API
- 32 testes de tratamento de erros
- 55 testes de operações CRUD de recursos
- 13 testes de configuração do cliente
- Factories de mock para todos os tipos de recursos
- README.md - Guia de início rápido atualizado
- MIGRATION.md - Guia detalhado de migração v2 → v3 (677 linhas)
- API.md - Referência completa da API (1842 linhas)
- CONTRIBUTING.md - Guidelines para contribuição
- CHANGELOG.md - Histórico de mudanças (este arquivo)
- RELEASE_NOTES_v3.md - Release notes completo em português
- JSDoc completo em todas as APIs públicas
- 10+ exemplos práticos em
examples/
Novos exemplos prontos para uso na pasta examples/:
basic-usage-esm.js- Uso básico com ESMbasic-usage-cjs.cjs- Uso básico com CommonJSbasic-usage.ts- Uso básico com TypeScriptservice-invoice-complete.js- Fluxo completo de emissão de nota fiscalreal-world-invoice.js- Exemplo real de emissão de notareal-world-list-invoices.js- Listagem com paginaçãoreal-world-manage-people.js- Gestão de pessoas (legal e natural)real-world-webhooks.js- Configuração e validação de webhooksall-resources-demo.js- Demonstração de todos os recursosjsdoc-intellisense-demo.ts- Demonstração do IntelliSensesetup.js- Script de configuração interativatest-connection.js- Script de teste de conexão
Scripts NPM para exemplos:
npm run examples:setup # Configurar credenciais
npm run examples:test # Testar conexão
npm run examples # Executar todos exemplos- IntelliSense Rico - Autocompletar completo com documentação inline
- Type Safety - Validação de tipos em tempo de desenvolvimento
- Mensagens de Erro Descritivas - Erros com contexto completo
- Validação de Ambiente - Método
isEnvironmentSupported() - Configuração Flexível - Múltiplas opções de configuração
- Exports Organizados - Exports públicos bem definidos
- Node.js: Aumentado de >= 12.0.0 para >= 18.0.0 (necessário para Fetch API nativo)
- TypeScript: Recomendado >= 5.0 para aproveitar tipos completos
Antes (v2):
var nfe = require('nfe-io')('api-key');Agora (v3):
// CommonJS
const { NfeClient } = require('nfe-io');
const nfe = new NfeClient({ apiKey: 'api-key' });
// ESM
import { NfeClient } from 'nfe-io';
const nfe = new NfeClient({ apiKey: 'api-key' });Antes (v2):
nfe.serviceInvoices.create('company-id', data, function(err, invoice) {
if (err) return console.error(err);
console.log(invoice);
});Agora (v3 - Async/Await):
try {
const invoice = await nfe.serviceInvoices.create('company-id', data);
console.log(invoice);
} catch (error) {
console.error(error);
}Antes (v2):
if (err.type === 'AuthenticationError') {
// tratar erro
}Agora (v3 - Classes de Erro):
import { AuthenticationError } from 'nfe-io';
if (error instanceof AuthenticationError) {
// tratar erro
}Antes (v2):
var nfe = require('nfe-io')('api-key');
nfe.setTimeout(60000);Agora (v3):
const nfe = new NfeClient({
apiKey: 'api-key',
timeout: 60000,
environment: 'production',
retryConfig: {
maxRetries: 3,
baseDelay: 1000
}
});
// Ou atualizar dinamicamente
nfe.updateConfig({ timeout: 90000 });Todos os métodos mantêm a mesma assinatura básica, mas agora retornam Promises:
| Recurso | Método | v2 | v3 | Mudanças |
|---|---|---|---|---|
| ServiceInvoices | create() |
✅ | ✅ | Agora async/await |
| ServiceInvoices | createAndWait() |
❌ | ✅ | NOVO! Polling automático |
| ServiceInvoices | list() |
✅ | ✅ | Agora async/await |
| ServiceInvoices | retrieve() |
✅ | ✅ | Agora async/await |
| ServiceInvoices | cancel() |
✅ | ✅ | Agora async/await |
| ServiceInvoices | sendEmail() |
✅ | ✅ | Agora async/await |
| ServiceInvoices | downloadPdf() |
✅ | ✅ | Retorna Buffer |
| ServiceInvoices | downloadXml() |
✅ | ✅ | Retorna string |
| Companies | uploadCertificate() |
✅ | ✅ | Suporte FormData melhorado |
| LegalPeople | findByTaxNumber() |
❌ | ✅ | NOVO! |
| LegalPeople | createBatch() |
❌ | ✅ | NOVO! |
| NaturalPeople | findByTaxNumber() |
❌ | ✅ | NOVO! |
| NaturalPeople | createBatch() |
❌ | ✅ | NOVO! |
| Webhooks | validateSignature() |
❌ | ✅ | NOVO! |
- when@3.1.0 - Substituído por promises nativas do JavaScript
- Todas as dependências em runtime - Agora zero dependencies
- Suporte a callbacks - Removido em favor de async/await
- API de promises via when.js - Substituído por promises nativas
- Suporte ao Node.js < 18 - Requer Node.js 18+ para Fetch API nativo
- Retry logic agora trata corretamente erros 4xx (não retenta)
- Tipos TypeScript completos para todas as respostas da API
- Mensagens de erro mais descritivas com contexto da requisição
- Race conditions no processamento assíncrono de notas fiscais
- Validação de configuração mais robusta
- Tratamento adequado de status HTTP 202 (accepted)
- Tratamento adequado de status HTTP 204 (no content)
- Atualizado para TypeScript 5.3+ (última versão estável)
- Zero dependências em runtime = superfície de ataque reduzida
- Nenhuma dependência com vulnerabilidades conhecidas (CVE)
- Validação de entrada via tipos TypeScript
- Suporte a validação de assinatura de webhooks
- ~30% mais rápido que v2 em operações comuns
- Tamanho do bundle reduzido de ~50KB para ~30KB
- Zero overhead de dependências externas
- Fetch API nativo otimizado
Para migrar da v2 para v3, consulte:
- Guia completo: MIGRATION.md
- Release notes: Guia de migração v2 → v3
Checklist rápido:
- ✅ Atualizar Node.js para >= 18.0.0
- ✅ Instalar versão 3:
npm install nfe-io@3 - ✅ Atualizar imports/requires
- ✅ Converter callbacks para async/await
- ✅ Atualizar tratamento de erros para classes
- ✅ Testar completamente sua aplicação
2.0.0 - Versão Legada (Anterior)
SDK JavaScript legado com API baseada em callbacks.
- Companies CRUD
- ServiceInvoices operations
- LegalPeople CRUD
- NaturalPeople CRUD
- Webhooks CRUD
- API dual Promise + callback via biblioteca
when
- Dependências desatualizadas (
when@3.1.0) - API baseada em callbacks (menos intuitiva)
- Sem suporte a TypeScript
- Sem mecanismo de retry integrado
- Polling manual necessário para operações assíncronas
- Sem testes automatizados
- 📧 Email: suporte@nfe.io
- 📖 Documentação: https://nfe.io/docs/
- 🐛 Issues: https://github.com/nfe/client-nodejs/issues
- 💬 Discussões: https://github.com/nfe/client-nodejs/discussions