SDK oficial da NFE.io para Node.js (TypeScript, zero dependências) para emitir NFS-e — nota fiscal de serviço eletrônica — e consultar CNPJ e CEP via API. Documentos fiscais do Brasil com async/await nativo.
Repo nfe/client-nodejs, read from GitHub 1 min ago. nfe has not joined Take My Repo.
nfe/client-nodejs is a public repo on GitHub by nfe. SDK oficial da NFE.io para Node.js (TypeScript, zero dependências) para emitir NFS-e — nota fiscal de serviço eletrônica — e consultar CNPJ e CEP via API. Documentos fiscais do Brasil com async/await nativo. It declares the MIT license on GitHub. It is written mainly in TypeScript, has 146 stars and last changed on 2026-11-19. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
SDK Oficial NFE.io para Node.js 22+ - SDK TypeScript moderno para emissão de notas fiscais de serviço eletrônicas (NFS-e).
✨ Versão 6 - TypeScript nativo, zero dependências em runtime e API moderna async/await. Major de correção de contrato: nove pontos da superfície pública mudaram de tipo ou assinatura, todos em métodos que já não funcionavam. Veja a migração v5 → v6.
Requisitos:
npm install nfe-io
ou
yarn add nfe-io
ou
pnpm add nfe-io
# 1. Clone e instale git clone https://github.com/nfe/client-nodejs.git cd client-nodejs npm install # 2. Configure suas credenciais (interativo) npm run examples:setup # 3. Teste a conexão npm run examples:test # 4. Execute os exemplos npm run examples
npm install nfe-io
import { NfeClient } from 'nfe-io'; // Inicializar o cliente const nfe = new NfeClient({ apiKey: 'sua-chave-api', environment: 'production' // ou 'development' }); // Criar uma empresa const empresa = await nfe.companies.create({ federalTaxNumber: 11222333999952, name: 'Minha Empresa Ltda', email: 'empresa@exemplo.com.br', taxRegime: 1, // Simples Nacional address: { country: 'BRA', postalCode: '01310-100', street: 'Av. Paulista', number: '1578', city: { code: '3550308', name: 'São Paulo' }, state: 'SP' } }); // Emitir uma nota fiscal de serviço const notaFiscal = await nfe.serviceInvoices.create(empresa.id, { cityServiceCode: '01234', description: 'Serviços de desenvolvimento web', servicesAmount: 1000.00, borrower: { type: 'LegalEntity', federalTaxNumber: 11222333999952, name: 'Empresa Cliente', email: 'cliente@exemplo.com.br', address: { country: 'BRA', postalCode: '01310-100', street: 'Av. Paulista', number: '1000', city: { code: '3550308', name: 'São Paulo' }, state: 'SP' } } }); console.log(`Nota fiscal criada: ${notaFiscal.number}`);
const { NfeClient } = require('nfe-io'); const nfe = new NfeClient({ apiKey: process.env.NFE_API_KEY, environment: 'production' }); // Mesma API que ESM
Este repositório embarca uma skill que ensina agentes de código (Claude Code, Cursor, etc.) a usar o SDK corretamente. Instale com:
npx skills add nfe/client-nodejs
O SDK fornece os seguintes recursos:
nfe.serviceInvoices)Gerenciar NFS-e (Nota Fiscal de Serviço Eletrônica):
// ⭐ RECOMENDADO: Criar e aguardar conclusão (lida com processamento assíncrono) const notaFiscal = await nfe.serviceInvoices.createAndWait(empresaId, { borrower: { federalTaxNumber: 12345678901, name: 'João da Silva', email: 'joao@example.com', }, cityServiceCode: '10677', description: 'Serviços de consultoria', servicesAmount: 1500.00, }, { pollingInterval: 2000, // Verificar a cada 2 segundos maxWaitTime: 60000, // Aguardar até 60 segundos }); console.log(`✅ Nota fiscal emitida: ${notaFiscal.number}`); // Criar nota fiscal manualmente (retorna 201 imediato ou 202 async) const result = await nfe.serviceInvoices.create(empresaId, dadosNota); // Verificar se é síncrono (201) ou assíncrono (202) if ('id' in result) { // Síncrono - nota emitida imediatamente console.log('Nota emitida:', result.number); } else { // Assíncrono - requer polling console.log('Processando:', result.flowStatus); // Use createAndWait() ou pollUntilComplete() em vez disso } // Listar notas fiscais com filtros const notas = await nfe.serviceInvoices.list(empresaId, { pageCount: 50, pageIndex: 1, // paginação é 1-based (primeira página = 1) searchPeriod: { startDate: '2024-01-01', endDate: '2024-01-31', }, }); // Buscar nota fiscal específica const nota = await nfe.serviceInvoices.retrieve(empresaId, notaFiscalId); // Verificar status de processamento const status = await nfe.serviceInvoices.getStatus(empresaId, notaFiscalId); console.log(`Status: ${status.status}, Completo: ${status.isComplete}`); // Cancelar nota fiscal const notaCancelada = await nfe.serviceInvoices.cancel(empresaId, notaFiscalId); // Enviar nota fiscal por email await nfe.serviceInvoices.sendEmail(empresaId, notaFiscalId, { emails: ['cliente@example.com', 'financeiro@example.com'], }); // Baixar PDF const pdfBuffer = await nfe.serviceInvoices.downloadPdf(empresaId, notaFiscalId); fs.writeFileSync('nota.pdf', pdfBuffer); // Baixar XML const xmlBuffer = await nfe.serviceInvoices.downloadXml(empresaId, notaFiscalId); fs.writeFileSync('nota.xml', xmlBuffer); // Criar múltiplas notas em lote (batch) const notasData = [/* ... array de dados de notas ... */]; const notas = await nfe.serviceInvoices.createBatch(empresaId, notasData, { waitForComplete: true, // Aguardar todas completarem maxConcurrent: 5, // Processar 5 por vez }); console.log(`✅ ${notas.length} notas fiscais criadas em lote`);
Recursos Avançados:
createAndWait() lida automaticamente com processamento assíncronocreateBatch() cria múltiplas notas com controle de concorrênciagetStatus() verifica se nota completou processamentonfe.companies)Gerenciar empresas na sua conta:
// Criar empresa (a API exige name, federalTaxNumber, taxRegime e address) const empresa = await nfe.companies.create({ name: 'Nome da Empresa', federalTaxNumber: 11222333999952, taxRegime: 'SimplesNacional', address: { state: 'SP', city: { code: '3550308', name: 'São Paulo' }, district: 'Centro', street: 'Rua Exemplo', number: '100', postalCode: '01001000', country: 'BRA', }, }); // Listar empresas — v2, cursor-based (recomendado; a API v1 está sendo descontinuada) const pagina = await nfe.companies.listV2({ limit: 50 }); // próxima página: listV2({ limit: 50, startingAfter: <id do último item> }) // Listar todas as empresas (varredura completa com paginação automática) const empresas = await nfe.companies.listAll(); // Buscar empresa específica const empresa = await nfe.companies.retrieve(empresaId); // Atualizar empresa — ATENÇÃO: é PUT (substituição total), não update parcial. // Envie o objeto completo (read-modify-write); campos omitidos são zerados. const atual = await nfe.companies.retrieve(empresaId); const atualizada = await nfe.companies.update(empresaId, { ...atual, tradeName: 'Novo Nome Fantasia', }); // Upload de certificado digital await nfe.companies.uploadCertificate(empresaId, { file: certificadoBuffer, password: 'senha-certificado' });
nfe.legalPeople)Gerenciar pessoas jurídicas (empresas/negócios):
// Criar pessoa jurídica const pessoa = await nfe.legalPeople.create(empresaId, { federalTaxNumber: '11222333999952', name: 'Nome da Empresa', email: 'empresa@exemplo.com.br', address: { /* ... */ } }); // Listar todas as pessoas jurídicas const pessoas = await nfe.legalPeople.list(empresaId); // Buscar por CNPJ const pessoa = await nfe.legalPeople.findByTaxNumber(empresaId, '11222333999952');
nfe.naturalPeople)Gerenciar pessoas físicas (indivíduos):
// Criar pessoa física const pessoa = await nfe.naturalPeople.create(empresaId, { federalTaxNumber: 12345678901, name: 'João da Silva', email: 'joao@exemplo.com.br', address: { /* ... */ } }); // Buscar por CPF const pessoa = await nfe.naturalPeople.findByTaxNumber(empresaId, '12345678901');
nfe.webhooks)Gerenciar configurações de webhook. Webhooks são gerenciados por conta
(/v2/webhooks) — os métodos por empresa estão deprecated (a rota retorna 404):
// Criar webhook — a URI precisa responder 2xx já na criação (ping de verificação) const webhook = await nfe.webhooks.createAccountWebhook({ uri: 'https://meuapp.com.br/webhooks/nfe', contentType: 'json', secret: 'um-segredo-de-32-a-64-caracteres-aqui', filters: ['service_invoice.issued_successfully', 'service_invoice.cancelled_successfully'] }); // Listar webhooks da conta const webhooks = await nfe.webhooks.listAccountWebhooks(); // Atualizar webhook await nfe.webhooks.updateAccountWebhook(webhookId, { filters: ['service_invoice.issued_successfully'] }); // Validar assinatura do webhook const ehValido = nfe.webhooks.validateSignature( payload, assinatura, segredo );
nfe.addresses)Consultar endereço brasileiro por CEP:
const endereco = await nfe.addresses.lookupByPostalCode('01310-100'); console.log(endereco.street); // 'Avenida Paulista' console.log(endereco.city.name); // 'São Paulo' console.log(endereco.state); // 'SP'
Busca por termo não existe.
lookupByTerm()esearch()foram removidos na v5: as rotas/v2/addressese/v2/addresses/{termo}respondem404no host real, então os métodos só lançavamNotFoundError. Consulta por CEP é a única disponível. Detalhes emMIGRATION.md.
Nota: A API de Endereços usa um host separado (
address.api.nfe.io) e a chave de dados. As duas chaves são complementares — a principal responde403aqui. O SDK aplica fallback dedataApiKeyparaapiKeycomo conveniência de quem tem uma chave só com os dois escopos; ver roteamento multi-host.
nfe.transportationInvoices)Consultar CT-e (Conhecimento de Transporte Eletrônico) via Distribuição DFe:
// Ativar busca automática de CT-e para uma empresa const settings = await nfe.transportationInvoices.enable('empresa-id'); console.log('Status:', settings.status); console.log('Iniciando do NSU:', settings.startFromNsu); // Ativar a partir de um NSU específico const settings = await nfe.transportationInvoices.enable('empresa-id', { startFromNsu: 12345 }); // Ativar a partir de uma data específica const settings = await nfe.transportationInvoices.enable('empresa-id', { startFromDate: '2024-01-01T00:00:00Z' }); // Verificar configurações atuais const config = await nfe.transportationInvoices.getSettings('empresa-id'); console.log('Busca ativa:', config.status); // Desativar busca automática await nfe.transportationInvoices.disable('empresa-id'); // Consultar CT-e por chave de acesso (44 dígitos) const cte = await nfe.transportationInvoices.retrieve( 'empresa-id', '35240112345678000190570010000001231234567890' ); console.log('Remetente:', cte.nameSender); console.log('Valor:', cte.totalInvoiceAmount); console.log('Emissão:', cte.issuedOn); // Baixar XML do CT-e const xml = await nfe.transportationInvoices.downloadXml( 'empresa-id', '35240112345678000190570010000001231234567890' ); fs.writeFileSync('cte.xml', xml); // Consultar evento do CT-e const evento = await nfe.transportationInvoices.getEvent( 'empresa-id', '35240112345678000190570010000001231234567890', 'chave-evento' ); // Baixar XML do evento const eventoXml = await nfe.transportationInvoices.downloadEventXml( 'empresa-id', '35240112345678000190570010000001231234567890', 'chave-evento' );
Nota: A API de CT-e usa um host separado (
api.nfse.io). Você pode configurar uma chave API específica comdataApiKey, ou o SDK usaráapiKeycomo fallback.
Pré-requisitos:
nfe.inboundProductInvoices)Consultar NF-e (Nota Fiscal Eletrônica de Produto) recebidas via Distribuição NF-e:
// Ativar busca automática de NF-e para uma empresa const settings = await nfe.inboundProductInvoices.enableAutoFetch('empresa-id', { environmentSEFAZ: 'Production', webhookVersion: '2', }); console.log('Status:', settings.status); // Ativar a partir de um NSU específico const settings = await nfe.inboundProductInvoices.enableAutoFetch('empresa-id', { startFromNsu: '999999', environmentSEFAZ: 'Production', }); // Verificar configurações atuais const config = await nfe.inboundProductInvoices.getSettings('empresa-id'); console.log('Busca ativa:', config.status); // Desativar busca automática await nfe.inboundProductInvoices.disableAutoFetch('empresa-id'); // Consultar NF-e por chave de acesso - formato webhook v2 (recomendado) const nfe_doc = await nfe.inboundProductInvoices.getProductInvoiceDetails( 'empresa-id', '35240112345678000190550010000001231234567890' ); console.log('Emissor:', nfe_doc.issuer?.name); console.log('Valor:', nfe_doc.totalInvoiceAmount); // Baixar XML da NF-e const xml = await nfe.inboundProductInvoices.getXml( 'empresa-id', '35240112345678000190550010000001231234567890' ); fs.writeFileSync('nfe.xml', xml); // Baixar PDF (DANFE) const pdf = await nfe.inboundProductInvoices.getPdf( 'empresa-id', '35240112345678000190550010000001231234567890' ); // Enviar manifestação (Ciência da Operação por padrão) await nfe.inboundProductInvoices.manifest( 'empresa-id', '35240112345678000190550010000001231234567890' ); // Confirmar a operação: a Confirmação da Operação é 210200 (o 210220 é Desconhecimento) await nfe.inboundProductInvoices.manifest( 'empresa-id', '35240112345678000190550010000001231234567890', 210200 ); // Consultar evento da NF-e const evento = await nfe.inboundProductInvoices.getEventDetails( 'empresa-id', '35240112345678000190550010000001231234567890', 'chave-evento' ); // Baixar XML do evento const eventoXml = await nfe.inboundProductInvoices.getEventXml( 'empresa-id', '35240112345678000190550010000001231234567890', 'chave-evento' ); // Reprocessar webhook await nfe.inboundProductInvoices.reprocessWebhook('empresa-id', '35240...');
Nota: A API de NF-e Distribuição usa um host separado (
api.nfse.io). Você pode configurar uma chave API específica comdataApiKey, ou o SDK usaráapiKeycomo fallback.
Pré-requisitos:
Tipos de Manifestação:
| Código | Evento |
|---|---|
210200 |
Confirmação da Operação |
210210 |
Ciência da Operação (padrão) |
210220 |
Desconhecimento da Operação |
210240 |
Operação não Realizada |
⚠️
210220é Desconhecimento da Operação, não Confirmação. Enviá-lo por engano 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. Até a 6.0.1, este README o chamava de Confirmação, o que estava errado. A Confirmação da Operação é210200, que o tipoManifestEventTypeaceita desde a 6.0.2. Segundo a documentação da plataforma, a rota de manifestação responde400para210240, porque o evento exige justificativa e a rota não tem corpo para enviá-la.
nfe.productInvoices)Ciclo completo de gestão de NF-e (Nota Fiscal Eletrônica de Produto) — emissão, listagem, consulta, cancelamento, carta de correção (CC-e), inutilização e download de arquivos (PDF/XML):
// Emitir NF-e (assíncrono — retorna 202) const result = await nfe.productInvoices.create('empresa-id', { operationNature: 'Venda de mercadoria', operationType: 'Outgoing', buyer: { name: 'Empresa LTDA', federalTaxNumber: 11222333999952 }, items: [{ code: 'PROD-001', description: 'Produto X', quantity: 1, unitAmount: 100 }], payment: [{ paymentDetail: [{ method: 'Cash', amount: 100 }] }], }); // Listar NF-e (environment é obrigatório) const invoices = await nfe.productInvoices.list('empresa-id', { environment: 'Production', limit: 10, }); // Consultar NF-e por ID const invoice = await nfe.productInvoices.retrieve('empresa-id', 'invoice-id'); // Cancelar NF-e (assíncrono) await nfe.productInvoices.cancel('empresa-id', 'invoice-id', 'Motivo do cancelamento'); // Download de PDF e XML const pdf = await nfe.productInvoices.downloadPdf('empresa-id', 'invoice-id'); const xml = await nfe.productInvoices.downloadXml('empresa-id', 'invoice-id'); // Carta de correção (CC-e) — razão de 15 a 1.000 caracteres await nfe.productInvoices.sendCorrectionLetter('empresa-id', 'invoice-id', 'Correcao do endereco do destinatario conforme novo cadastro'); // Inutilizar faixa de numeração await nfe.productInvoices.disableRange('empresa-id', { environment: 'Production', serie: 1, state: 'SP', beginNumber: 100, lastNumber: 110, });
Nota: Operações de emissão, cancelamento, CC-e e inutilização são assíncronas — retornam 202/204. Conclusão é notificada via webhooks.
nfe.stateTaxes)CRUD de inscrições estaduais (IE) — configuração necessária para emissão de NF-e de produto:
// Listar inscrições estaduais const taxes = await nfe.stateTaxes.list('empresa-id'); // Criar inscrição estadual const tax = await nfe.stateTaxes.create('empresa-id', { taxNumber: '123456789', serie: 1, number: 1, code: 'sP', environmentType: 'production', type: 'nFe', }); // Consultar, atualizar e excluir const retrieved = await nfe.stateTaxes.retrieve('empresa-id', 'state-tax-id'); await nfe.stateTaxes.update('empresa-id', 'state-tax-id', { serie: 2 }); await nfe.stateTaxes.delete('empresa-id', 'state-tax-id');
Nota: Usa o host
api.nfse.io. ConfiguredataApiKeypara chave separada, ou o SDK usaráapiKeycomo fallback.
nfe.productInvoiceQuery)Consultar NF-e (Nota Fiscal Eletrônica de Produto) diretamente na SEFAZ por chave de acesso. Recurso somente leitura sem necessidade de escopo de empresa:
// Consultar dados completos da NF-e const invoice = await nfe.productInvoiceQuery.retrieve( '35240112345678000190550010000001231234567890' ); console.log('Status:', invoice.currentStatus); console.log('Emissor:', invoice.issuer?.name); console.log('Valor:', invoice.totals?.icms?.invoiceAmount); // Baixar DANFE (PDF) const pdf = await nfe.productInvoiceQuery.downloadPdf( '35240112345678000190550010000001231234567890' ); fs.writeFileSync('danfe.pdf', pdf); // Baixar XML da NF-e const xml = await nfe.productInvoiceQuery.downloadXml( '35240112345678000190550010000001231234567890' ); fs.writeFileSync('nfe.xml', xml); // Listar eventos fiscais (cancelamentos, correções, manifestações) const result = await nfe.productInvoiceQuery.listEvents( '35240112345678000190550010000001231234567890' ); for (const event of result.events ?? []) { console.log(event.description, event.authorizedOn); }
Nota: A API de Consulta NF-e usa um host separado (
nfe.api.nfe.io). Você pode configurar uma chave API específica comdataApiKey, ou o SDK usaráapiKeycomo fallback.
nfe.consumerInvoiceQuery) — descontinuado⚠️ Descontinuado: a plataforma não serve estas rotas.
/v1/consumerinvoices/coupon/{chave}e.xmlestão declaradas na OpenAPI, mas respondem404igual ao de um caminho inexistente, inclusive sem credencial (medido em 2026-09-02). Os métodosretrieve()edownloadXml()estão marcados@deprecated: continuam emitindo a requisição, e o404vem com essa explicação. Não há substituto na API hoje.
nfe.legalEntityLookup)Consultar dados cadastrais de empresas brasileiras (CNPJ) na Receita Federal e nas SEFAZs estaduais:
// Consulta básica por CNPJ (aceita com ou sem pontuação) const result = await nfe.legalEntityLookup.getBasicInfo('11.222.333/9999-52'); console.log('Razão Social:', result.legalEntity?.name); console.log('Nome Fantasia:', result.legalEntity?.tradeName); console.log('Status:', result.legalEntity?.status); // 'Active' console.log('Porte:', result.legalEntity?.size); // 'ME', 'EPP', etc. console.log('Cidade:', result.legalEntity?.address?.city?.name); // Consulta com opções const result = await nfe.legalEntityLookup.getBasicInfo('11222333999952', { updateAddress: false, // Não atualizar endereço via Correios updateCityCode: true, // Atualizar código IBGE da cidade }); // Consultar Inscrição Estadual (IE) por estado const ieSP = await nfe.legalEntityLookup.getStateTaxInfo('SP', '11222333999952'); for (const tax of ieSP.legalEntity?.stateTaxes ?? []) { console.log(`IE: ${tax.taxNumber} - Status: ${tax.status}`); console.log(` NFe: ${tax.nfe?.status}, CTe: ${tax.cte?.status}`); } // Avaliar IE para emissão de nota fiscal const invoice = await nfe.legalEntityLookup.getStateTaxForInvoice('MG', '11222333999952'); for (const tax of invoice.legalEntity?.stateTaxes ?? []) { if (tax.status === 'Abled') { console.log(`Pode emitir com IE: ${tax.taxNumber}`); } } // Obter melhor IE sugerida para emissão const sugestao = await nfe.legalEntityLookup.getSuggestedStateTaxForInvoice('SP', '11222333999952'); const melhorIE = sugestao.legalEntity?.stateTaxes?.[0]; console.log('IE recomendada:', melhorIE?.taxNumber);
Nota: A API de Consulta CNPJ usa um host separado (
legalentity.api.nfe.io). Você pode configurar uma chave API específica comdataApiKey, ou o SDK usaráapiKeycomo fallback.
nfe.naturalPersonLookup)Consultar a situação cadastral de CPF (pessoa física) na Receita Federal:
// Consulta com CPF e data de nascimento const result = await nfe.naturalPersonLookup.getStatus('123.456.789-01', '1990-01-15'); console.log('Nome:', result.name); // 'JOÃO DA SILVA' console.log('Status:', result.status); // 'Regular' // Também aceita Date object const result = await nfe.naturalPersonLookup.getStatus('12345678901', new Date(1990, 0, 15)); console.log('Situação Cadastral:', result.status);
Nota: A API de Consulta CPF usa um host separado (
naturalperson.api.nfe.io). Você pode configurar uma chave API específica comdataApiKey, ou o SDK usaráapiKeycomo fallback.
nfe.taxCalculation)Calcular todos os tributos aplicáveis (ICMS, ICMS-ST, PIS, COFINS, IPI, II) para operações com produtos usando o Motor de Cálculo de Tributos:
// Calcular impostos de uma operação de venda const resultado = await nfe.taxCalculation.calculate('tenant-id', { operationType: 'Outgoing', issuer: { state: 'SP', taxRegime: 'RealProfit' }, recipient: { state: 'RJ' }, items: [{ id: 'item-1', operationCode: 121, origin: 'National', ncm: '61091000', quantity: 10, unitAmount: 100.00 }] }); for (const item of resultado.items ?? []) { console.log(`Item ${item.id}: CFOP ${item.cfop}`); console.log(` ICMS: CST=${item.icms?.cst}, valor=${item.icms?.vICMS}`); console.log(` PIS: CST=${item.pis?.cst}, valor=${item.pis?.vPIS}`); console.log(` COFINS: CST=${item.cofins?.cst}, valor=${item.cofins?.vCOFINS}`); }
Nota: A API de Cálculo de Impostos usa o host
api.nfse.io. ConfiguredataApiKeypara uma chave específica, ou o SDK usaráapiKeycomo fallback.
nfe.taxCodes)Consultar tabelas de referência necessárias para o cálculo de impostos:
// Listar códigos de operação (natureza de operação) const codigos = await nfe.taxCodes.listOperationCodes({ pageIndex: 1, pageCount: 20 }); for (const cod of codigos.items ?? []) { console.log(`${cod.code} - ${cod.description}`); } // Listar finalidades de aquisição const finalidades = await nfe.taxCodes.listAcquisitionPurposes(); // Listar perfis fiscais do emissor const perfisEmissor = await nfe.taxCodes.listIssuerTaxProfiles(); // Listar perfis fiscais do destinatário const perfisDestinatario = await nfe.taxCodes.listRecipientTaxProfiles();
Nota: Todas as listagens suportam paginação via
pageIndex(1-based) epageCount(padrão: 50).
const nfe = new NfeClient({ // Chave API principal do NFE.io (operações com documentos fiscais) apiKey: 'sua-chave-api', // Opcional: Chave API para serviços de consulta (Endereços, CT-e, CNPJ, CPF) // Se não fornecida, usa apiKey como fallback dataApiKey: 'sua-chave-data-api', // Opcional: Ambiente (padrão: 'production') environment: 'production', // ou 'sandbox' // Opcional: URL base customizada (sobrescreve environment) baseUrl: 'https://api-customizada.nfe.io/v1', // Opcional: Timeout de requisição em milissegundos (padrão: 30000) timeout: 60000, // Opcional: Configuração de retry retryConfig: { maxRetries: 3, baseDelay: 1000, maxDelay: 10000, backoffMultiplier: 2 } });
O SDK suporta as seguintes variáveis de ambiente:
| Variável | Descrição |
|---|---|
NFE_API_KEY |
Chave API principal (fallback para apiKey) |
NFE_DATA_API_KEY |
Chave API para serviços de consulta (fallback para dataApiKey) |
# Configurar via ambiente export NFE_API_KEY="sua-chave-api" export NFE_DATA_API_KEY="sua-chave-data" # Usar SDK sem passar chaves no código const nfe = new NfeClient({});
O SDK fornece classes de erro tipadas:
import { NfeError, AuthenticationError, ValidationError, NotFoundError, RateLimitError } from 'nfe-io'; try { const notaFiscal = await nfe.serviceInvoices.create(empresaId, dados); } catch (erro) { if (erro instanceof AuthenticationError) { console.error('Chave API inválida:', erro.message); } else if (erro instanceof ValidationError) { console.error('Dados inválidos:', erro.details); } else if (erro instanceof NotFoundError) { console.error('Recurso não encontrado:', erro.message); } else if (erro instanceof RateLimitError) { console.error('Limite de requisições excedido, tente novamente em:', erro.retryAfter); } else if (erro instanceof NfeError) { console.error('Erro da API:', erro.code, erro.message); } else { console.error('Erro inesperado:', erro); } }
Veja MIGRATION.md para um guia completo de migração.
Principais Mudanças:
// v2 (callbacks + promises) var nfe = require('nfe-io')('chave-api'); nfe.serviceInvoices.create('id-empresa', dados, function(err, notaFiscal) { if (err) return console.error(err); console.log(notaFiscal); }); // v3 (async/await + TypeScript) import { NfeClient } from 'nfe-io'; const nfe = new NfeClient({ apiKey: 'chave-api' }); try { const notaFiscal = await nfe.serviceInvoices.create('id-empresa', dados); console.log(notaFiscal); } catch (erro) { console.error(erro); }
O diretório examples/ contém exemplos completos que você pode executar com suas credenciais:
# Modo interativo com menu npm run examples # Ou diretamente node examples/run-examples.js
Exemplos disponíveis:
Veja examples/README.md para documentação completa.
import { NfeClient } from 'nfe-io'; const nfe = new NfeClient({ apiKey: process.env.NFE_API_KEY!, environment: 'production' }); async function emitirNotaFiscal() { // 1. Buscar ou criar empresa const empresas = await nfe.companies.list(); const empresa = empresas.data[0]; // 2. Criar nota fiscal com polling automático const notaFiscal = await nfe.serviceInvoices.createAndWait(empresa.id, { cityServiceCode: '01234', description: 'Consultoria em TI', servicesAmount: 5000.00, borrower: { type: 'LegalEntity', federalTaxNumber: 11222333999952, name: 'Cliente Exemplo Ltda', email: 'contato@cliente.com.br', address: { country: 'BRA', postalCode: '01310-100', street: 'Av. Paulista', number: '1000', city: { code: '3550308', name: 'São Paulo' }, state: 'SP' } } }, { maxAttempts: 30, intervalMs: 2000 }); console.log(`✅ Nota fiscal emitida: ${notaFiscal.number}`); // 3. Enviar por email await nfe.serviceInvoices.sendEmail(empresa.id, notaFiscal.id); console.log('📧 Email enviado'); // 4. Baixar PDF const pdf = await nfe.serviceInvoices.downloadPdf(empresa.id, notaFiscal.id); await fs.promises.writeFile(`nota-fiscal-${notaFiscal.number}.pdf`, pdf); console.log('💾 PDF salvo'); } emitirNotaFiscal().catch(console.error);
// Webhooks são por conta (/v2/webhooks), sem companyId. Na criação, a NFE.io faz um // ping na `uri`: o endpoint precisa estar no ar e responder 2xx. const webhook = await nfe.webhooks.createAccountWebhook({ uri: 'https://meuapp.com.br/api/webhooks/nfe', contentType: 'json', secret: process.env.WEBHOOK_SECRET!, // 32 a 64 caracteres filters: ['service_invoice.issued_successfully', 'service_invoice.cancelled_successfully'], }); // No endpoint, valide a assinatura sobre o corpo bruto (Buffer), não sobre o JSON parseado app.post('/api/webhooks/nfe', express.raw({ type: '*/*' }), (req, res) => { const ehValido = nfe.webhooks.validateSignature( req.body, // Buffer bruto req.headers['x-hub-signature'], // HMAC-SHA1 process.env.WEBHOOK_SECRET ); if (!ehValido) { return res.status(401).send('Assinatura inválida'); } const evento = JSON.parse(req.body.toString('utf8')); // ... processe o evento res.status(200).send('OK'); });
Os métodos de webhook por empresa (
webhooks.list/create/retrieve/update/delete/testcomcompanyId) estão descontinuados: a rota/v1/companies/{id}/webhooksresponde404. Use os métodos por conta acima. Lista de eventos ao vivo:nfe.webhooks.fetchEventTypes().
async function emitirNotasEmLote(empresaId: string, notasFiscais: DadosNota[]) { const resultados = await Promise.allSettled( notasFiscais.map(dados => nfe.serviceInvoices.createAndWait(empresaId, dados) ) ); const sucesso = resultados.filter(r => r.status === 'fulfilled'); const falha = resultados.filter(r => r.status === 'rejected'); console.log(`✅ ${sucesso.length} notas fiscais emitidas`); console.log(`❌ ${falha.length} notas fiscais falharam`); return { sucesso, falha }; }
Documentação completa da API disponível em:
# Executar todos os testes (unit + integration) npm test # Executar apenas testes unitários npm run test:unit # Executar apenas testes de integração (requer chave API) npm run test:integration # Executar com cobertura npm run test:coverage # Executar com UI npm run test:ui
Os testes de integração validam contra a API real do NFE.io:
# Definir sua chave API de desenvolvimento/teste export NFE_API_KEY="sua-chave-api-desenvolvimento" export NFE_TEST_ENVIRONMENT="development" export RUN_INTEGRATION_TESTS="true" # Executar testes de integração npm run test:integration
Veja tests/integration/README.md para documentação detalhada.
Nota: Testes de integração fazem chamadas reais à API e podem gerar custos dependendo do seu plano.
O SDK gera tipos TypeScript automaticamente a partir de especificações OpenAPI. As specs são mantidas manualmente em openapi/spec/:
# Validar todas as specs OpenAPI npm run validate:spec # Gerar tipos TypeScript a partir das specs npm run generate # Modo watch - regenerar automaticamente ao modificar specs npm run generate:watch
Localização das specs: openapi/spec/*.yaml
Tipos gerados: src/generated/*.ts
Configuração: openapi/generator-config.yaml
O processo de build valida automaticamente as specs e gera tipos antes da compilação:
npm run build
# → Executa: validate:spec → generate → typecheck → tsdownNota: Arquivos gerados não devem ser editados manualmente. Edite as specs OpenAPI e regenere.
Para orientações de migração, veja MIGRATION.md.
npm run typecheck
npm run build
Contribuições são bem-vindas! Por favor, veja CONTRIBUTING.md para orientações.
O código deste SDK é distribuído sob a licença MIT. Copyright (c) 2026 NFE.IO HUB SERVICOS DE TECNOLOGIA LTDA.
A licença cobre o SDK, não a API: o uso da API da NFE.io segue o contrato da sua conta (Termos de Serviço).
Feito com ❤️ pela equipe NFE.io
nfe/client-nodejs is a public repo on GitHub by nfe. SDK oficial da NFE.io para Node.js (TypeScript, zero dependências) para emitir NFS-e — nota fiscal de serviço eletrônica — e consultar CNPJ e CEP via API. Documentos fiscais do Brasil com async/await nativo.
It declares the MIT license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-19. GitHub counts 9 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Backend do Brasil.IO (para código dos scripts de coleta de dados, veja o link na página de cada dataset)
电子发票整理与报销准备工具:从邮箱批量收集 PDF/OFD/XML 发票,OCR 识别、分类归档并生成 Excel 汇总;提供 Windows/macOS 桌面版与 DSH 插件。
Flutter makes it easy and fast to build beautiful apps for mobile and beyond
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.
FastAPI framework, high performance, easy to learn, fast to code, ready for production
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/nfe/client-nodejsTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.