@controlaltweb1/nfcom-node

@controlaltweb1/nfcom-node

Biblioteca Node.js para integração com o serviço de NFCom (Nota Fiscal de Comunicação) do Brasil.

Descrição

Esta biblioteca fornece uma interface completa para comunicação com os webservices da NFCom, permitindo:

• 🔐 Envio de NFCom - Emissão de notas fiscais de comunicação
• 🔄 Substituição - Emissão de NFCom de substituição (finNFCom = 3) com grupo gSub
• ❌ Cancelamento - Cancelamento de NFCom emitidas
• 🔍 Consultas - Consulta de situação e detalhes de NFCom
• 📊 Status do Serviço - Verificação do status dos servidores SEFAZ

Pré-requisitos

• Node.js 16+
• Certificado digital A1 (.pfx)
• Credenciais de acesso ao ambiente da NFCom

Instalação

npm install @controlaltweb1/nfcom-node

Uso Básico

1. Configuração Inicial

const fs = require('fs');
const { NFCom } = require('@controlaltweb1/nfcom-node');
const { extractFromPfx } = require('@controlaltweb1/nfcom-node/helpers');

// Extrair certificado
const { privateKey, base64Cert, pemCert } = extractFromPfx(
  fs.readFileSync('seu-certificado.pfx'),
  'sua-senha'
);

const nfCom = new NFCom();

2. Envio de NFCom

const dadosNFCom = {
  NFCom: {
    $: { xmlns: 'http://www.portalfiscal.inf.br/nfcom' },
    infNFCom: {
      $: { versao: '1.00', Id: '' },
      ide: {
        cUF: '35',
        tpAmb: '2',
        mod: '62',
        serie: '1',
        nNF: '1',
        cNF: '0000001',
        cDV: '0',
        dhEmi: '2025-09-18T14:30:00-03:00',
        tpEmis: '1',
        nSiteAutoriz: '0',
        cMunFG: '3557409',
        finNFCom: '0',
        tpFat: '0',
        verProc: '1',
        indCessaoMeiosRede: '1',
      },
      emit: {
        CNPJ: '46665188000198',
        IE: '582638383117',
        CRT: '3',
        xNome: 'Sua Empresa Ltda.',
        xFant: 'NOME FANTASIA',
        enderEmit: {
          xLgr: 'Av. Exemplo',
          nro: '123',
          xBairro: 'Centro',
          cMun: '3543402',
          xMun: 'Sua Cidade',
          CEP: '14025000',
          UF: 'SP',
          fone: '11999999999',
        },
      },
      // ... outros campos obrigatórios
    }
  }
};

const resultado = await nfCom.nfcomRecepcao(
  dadosNFCom,
  'homologacao', // ambiente
  privateKey,
  pemCert,
  base64Cert
);

console.log('XML Assinado:', resultado.signedXml);
console.log('Resposta SEFAZ:', resultado.sefazResponse);

3. Consulta de NFCom

const consulta = await nfCom.nfcomConsulta(
  'homologacao',
  '35250946665188000198620010000000011000000010', // chave NFCom
  privateKey,
  pemCert
);

console.log('Resultado da consulta:', consulta);

4. Status do Serviço

const status = await nfCom.nfcomStatusServico(
  'homologacao',
  privateKey,
  pemCert
);

console.log('Status do serviço:', status);

5. Cancelamento de NFCom

const eventoGeral = {
  eventoNFCom: {
    $: { xmlns: 'http://www.portalfiscal.inf.br/nfcom', versao: '1.00' },
    infEvento: {
      $: {},
      cOrgao: 35,
      tpAmb: 2,
      CNPJ: '46101424000143',
      chNFCom: '35250946665188000198620010000000011000000010',
      dhEvento: '2025-09-18T14:30:00-03:00',
      tpEvento: '110111',
      nSeqEvento: 1,
      detEvento: { $: { versaoEvento: '1.00' }, any: '' },
    },
  }
};

const cancelamento = {
  evCancNFCom: {
    $: { xmlns: 'http://www.portalfiscal.inf.br/nfcom' },
    descEvento: 'Cancelamento',
    nProt: '3525094666518800', // número do protocolo
    xJust: 'Justificativa do cancelamento',
  }
};

const resultadoCancelamento = await nfCom.nfcomRecepcaoEvento(
  eventoGeral,
  cancelamento,
  'cancelamento',
  'homologacao',
  privateKey,
  pemCert,
  base64Cert
);

6. NFCom de Substituição

Para emitir uma NFCom que substitui outra, use finNFCom: '3' e preencha o grupo gSub com a referência à NFCom original (ou à NF modelo 21/22) e o motivo da substituição. Nos itens (det) você pode informar chNFComAnt e nItemAnt para referenciar o item da nota substituída.

Motivos (motSub): 01 Erro de Preço | 02 Erro Cadastral | 03 Decisão Judicial | 04 Erro de Tributação | 05 Descontinuidade do Serviço

const dadosNFComSubstituicao = {
  NFCom: {
    $: { xmlns: 'http://www.portalfiscal.inf.br/nfcom' },
    infNFCom: {
      $: { versao: '1.00', Id: '' },
      ide: {
        // ... ide igual ao exemplo de envio
        finNFCom: '3', // NFCom de Substituição
      },
      // ... emit, dest, assinante
      gSub: {
        chNFCom: '35250946665188000198620010000000011000000010', // chave da NFCom original
        motSub: '01', // 01=Erro de Preço, 02=Erro Cadastral, 03=Decisão Judicial, 04=Erro de Tributação, 05=Descontinuidade do Serviço
      },
      // Ou, ao invés de chNFCom, referenciar NF modelo 21/22:
      // gSub: {
      //   gNF: { CNPJ: '...', mod: '21', serie: '001', nNF: '123456', CompetEmis: '202509' },
      //   motSub: '02',
      // },
      det: [
        {
          $: { nItem: '1', chNFComAnt: '35250946665188000198620010000000011000000010', nItemAnt: '1' },
          prod: { /* ... */ },
          imposto: { /* ... */ },
        },
      ],
      total: { /* ... */ },
    },
    infNFComSupl: { qrCodNFCom: '' },
  },
};

const resultado = await nfCom.nfcomRecepcao(
  dadosNFComSubstituicao,
  'homologacao',
  privateKey,
  pemCert,
  base64Cert
);

Ambientes

• Homologação: 'homologacao' - Para testes
• Produção: 'producao' - Ambiente real

Estrutura de Retorno

Envio e Cancelamento

{
  signedXml: string;      // XML assinado
  sefazResponse: string;  // Resposta da SEFAZ
}

Consulta e Status

Retorna o objeto parseado da resposta da SEFAZ.

Tratamento de Erros

try {
  const resultado = await nfCom.nfcomRecepcao(...);
} catch (error) {
  console.error('Erro na comunicação com SEFAZ:', error);
  
  if (error.response) {
    console.error('Resposta de erro:', error.response.data);
  }
}

Links Úteis

• Documentação Oficial NFCom
• Portal NFCom

Suporte

Em caso de problemas ou dúvidas, abra uma issue no repositório do projeto.

Licença

MIT