ghinfe 0.6.0

package/src/nfe/mocks/sefaz-responses.js

@@ -0,0 +1,195 @@
+import { SEFAZ_STATUS } from '../../constants/sefaz.js';
+
+/**
+ * Respostas simuladas da SEFAZ para desenvolvimento e testes.
+ * Baseadas nos cStat reais do Manual de Orientação do Contribuinte.
+ */
+export const SEFAZ_MOCK_RESPONSES = {
+  autorizado: {
+    cStat: SEFAZ_STATUS.AUTORIZADO,
+    xMotivo: 'Autorizado o uso da NF-e',
+    nProt: '135260000000001',
+    dhRecbto: new Date().toISOString(),
+  },
+  loteRecebido: {
+    cStat: SEFAZ_STATUS.LOTE_RECEBIDO,
+    xMotivo: 'Lote recebido com sucesso',
+    nRec: '135260000000001',
+    tMed: '1',
+  },
+  rejeicaoDuplicidade: {
+    cStat: SEFAZ_STATUS.REJEICAO_DUPLICIDADE,
+    xMotivo: 'Rejeição: Duplicidade de NF-e',
+  },
+  rejeicaoSchema: {
+    cStat: SEFAZ_STATUS.REJEICAO_SCHEMA,
+    xMotivo: 'Rejeição: Falha no Schema XML da NFe',
+  },
+  rejeicaoCertificado: {
+    cStat: SEFAZ_STATUS.REJEICAO_CERTIFICADO,
+    xMotivo: 'Rejeição: Certificado Transmissor inválido',
+  },
+  servicoParalisado: {
+    cStat: SEFAZ_STATUS.SERVICO_PARALISADO,
+    xMotivo: 'Serviço Paralisado momentaneamente (curto prazo)',
+  },
+  eventoRegistrado: {
+    cStat: SEFAZ_STATUS.EVENTO_REGISTRADO,
+    xMotivo: 'Evento registrado e vinculado a NF-e',
+    nProt: '135260000000002',
+  },
+  eventoRejeitado: {
+    cStat: SEFAZ_STATUS.EVENTO_REJEICAO,
+    xMotivo: 'Rejeição: Chave de Acesso inexistente',
+  },
+  statusOk: {
+    cStat: '107',
+    xMotivo: 'Serviço em Operação',
+    tMed: '1',
+  },
+  statusParalisado: {
+    cStat: SEFAZ_STATUS.SERVICO_PARALISADO,
+    xMotivo: 'Serviço Paralisado momentaneamente (curto prazo)',
+    tMed: '5',
+  },
+};
+
+/**
+ * Gera XML de retorno de autorização simulado (protNFe).
+ * @param {string} chaveAcesso
+ * @param {{ cStat: string, xMotivo: string, nProt?: string }} resultado
+ * @returns {string}
+ */
+export function buildMockProtNFeXml(chaveAcesso, resultado) {
+  const nProt = resultado.nProt ?? '';
+  const dhRecbto = new Date().toISOString().replace('Z', '-03:00');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<retEnviNFe xmlns="http://www.portalfiscal.inf.br/nfe" versao="4.00">
+  <tpAmb>2</tpAmb>
+  <verAplic>MOCK_GHINFE_1.0</verAplic>
+  <cStat>${resultado.cStat}</cStat>
+  <xMotivo>${resultado.xMotivo}</xMotivo>
+  <cUF>35</cUF>
+  <dhRecbto>${dhRecbto}</dhRecbto>
+  ${
+    resultado.cStat === SEFAZ_STATUS.AUTORIZADO
+      ? `<protNFe versao="4.00">
+    <infProt>
+      <tpAmb>2</tpAmb>
+      <verAplic>MOCK_GHINFE_1.0</verAplic>
+      <chNFe>${chaveAcesso}</chNFe>
+      <dhRecbto>${dhRecbto}</dhRecbto>
+      <nProt>${nProt}</nProt>
+      <digVal>mock-digest-value</digVal>
+      <cStat>${resultado.cStat}</cStat>
+      <xMotivo>${resultado.xMotivo}</xMotivo>
+    </infProt>
+  </protNFe>`
+      : ''
+  }
+</retEnviNFe>`;
+}
+
+/**
+ * Gera envelope SOAP de retorno simulado.
+ * @param {string} innerXml
+ * @returns {string}
+ */
+export function wrapSoapResponse(innerXml) {
+  return `<?xml version="1.0" encoding="utf-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <nfeResultMsg xmlns="http://www.portalfiscal.inf.br/nfe/wsdl/NFeAutorizacao4">
+      ${innerXml}
+    </nfeResultMsg>
+  </soap:Body>
+</soap:Envelope>`;
+}
+
+/**
+ * Gera XML de retorno de evento simulado (retEnvEvento).
+ * @param {string} chaveAcesso
+ * @param {string} tpEvento
+ * @param {{ cStat: string, xMotivo: string, nProt?: string }} resultado
+ * @returns {string}
+ */
+export function buildMockRetEnvEventoXml(chaveAcesso, tpEvento, resultado) {
+  const dhReg = new Date().toISOString().replace('Z', '-03:00');
+  const loteOk = resultado.cStat === SEFAZ_STATUS.EVENTO_REGISTRADO;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<retEnvEvento xmlns="http://www.portalfiscal.inf.br/nfe" versao="1.00">
+  <idLote>1</idLote>
+  <tpAmb>2</tpAmb>
+  <verAplic>MOCK_GHINFE_1.0</verAplic>
+  <cStat>${loteOk ? SEFAZ_STATUS.EVENTO_LOTE_PROCESSADO : '104'}</cStat>
+  <xMotivo>${loteOk ? 'Lote de evento processado' : resultado.xMotivo}</xMotivo>
+  ${
+    loteOk
+      ? `<retEvento versao="1.00">
+    <infEvento>
+      <tpAmb>2</tpAmb>
+      <verAplic>MOCK_GHINFE_1.0</verAplic>
+      <cOrgao>35</cOrgao>
+      <cStat>${resultado.cStat}</cStat>
+      <xMotivo>${resultado.xMotivo}</xMotivo>
+      <chNFe>${chaveAcesso}</chNFe>
+      <tpEvento>${tpEvento}</tpEvento>
+      <nSeqEvento>1</nSeqEvento>
+      <dhRegEvento>${dhReg}</dhRegEvento>
+      <nProt>${resultado.nProt ?? '135260000000002'}</nProt>
+    </infEvento>
+  </retEvento>`
+      : ''
+  }
+</retEnvEvento>`;
+}
+
+/**
+ * @param {string} innerXml
+ * @returns {string}
+ */
+export function wrapSoapEventoResponse(innerXml) {
+  return `<?xml version="1.0" encoding="utf-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <nfeResultMsg xmlns="http://www.portalfiscal.inf.br/nfe/wsdl/NFeRecepcaoEvento4">
+      ${innerXml}
+    </nfeResultMsg>
+  </soap:Body>
+</soap:Envelope>`;
+}
+
+/**
+ * XML de retorno de status do serviço (retConsStatServ).
+ * @param {{ cStat: string, xMotivo: string, tMed?: string }} resultado
+ * @param {string} [cUF]
+ */
+export function buildMockRetConsStatServXml(resultado, cUF = '35') {
+  const dh = new Date().toISOString().replace('Z', '-03:00');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<retConsStatServ xmlns="http://www.portalfiscal.inf.br/nfe" versao="4.00">
+  <tpAmb>2</tpAmb>
+  <verAplic>MOCK_GHINFE_1.0</verAplic>
+  <cStat>${resultado.cStat}</cStat>
+  <xMotivo>${resultado.xMotivo}</xMotivo>
+  <cUF>${cUF}</cUF>
+  <dhRecbto>${dh}</dhRecbto>
+  <tMed>${resultado.tMed ?? '1'}</tMed>
+</retConsStatServ>`;
+}
+
+/**
+ * @param {string} innerXml
+ */
+export function wrapSoapStatusResponse(innerXml) {
+  return `<?xml version="1.0" encoding="utf-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <nfeResultMsg xmlns="http://www.portalfiscal.inf.br/nfe/wsdl/NFeStatusServico4">
+      ${innerXml}
+    </nfeResultMsg>
+  </soap:Body>
+</soap:Envelope>`;
+}

package/src/nfe/services/NFeEventoService.js

@@ -0,0 +1,95 @@
+import { NFeEventoXmlBuilder } from '../builders/NFeEventoXmlBuilder.js';
+import { NFeSignService } from './NFeSignService.js';
+import { NFeSoapService } from './NFeSoapService.js';
+import { NFE_EVENTOS } from '../types/NFeEvento.js';
+
+/**
+ * Serviço de eventos NF-e: cancelamento, carta de correção, etc.
+ */
+export class NFeEventoService {
+  /**
+   * @param {ConstructorParameters<typeof NFeSoapService>[0]} [soapOptions]
+   */
+  constructor(soapOptions = {}) {
+    this.builder = new NFeEventoXmlBuilder();
+    this.signService = new NFeSignService();
+    this.soapService = new NFeSoapService(soapOptions);
+  }
+
+  /**
+   * @param {import('../types/NFeEvento.js').NFeCancelamento} dados
+   */
+  gerarXmlCancelamento(dados) {
+    return this.builder.buildCancelamento(dados);
+  }
+
+  /**
+   * @param {import('../types/NFeEvento.js').NFeCartaCorrecao} dados
+   */
+  gerarXmlCartaCorrecao(dados) {
+    return this.builder.buildCartaCorrecao(dados);
+  }
+
+  /**
+   * Cancela NF-e autorizada (evento 110111).
+   * @param {import('../types/NFeEvento.js').NFeCancelamento} dados
+   * @param {{ pfx: Buffer|string, senha: string }} certificado
+   */
+  async cancelar(dados, certificado) {
+    const xml = this.gerarXmlCancelamento(dados);
+    const xmlAssinado = this.signService.assinarEvento(xml, certificado.pfx, certificado.senha);
+    const retorno = await this.soapService.enviarEvento(
+      xmlAssinado,
+      dados.chaveAcesso,
+      NFE_EVENTOS.CANCELAMENTO,
+      dados.idLote
+    );
+
+    return { tipo: 'cancelamento', xmlGerado: xml, xmlAssinado, retorno };
+  }
+
+  /**
+   * Registra Carta de Correção Eletrônica (evento 110110).
+   * @param {import('../types/NFeEvento.js').NFeCartaCorrecao} dados
+   * @param {{ pfx: Buffer|string, senha: string }} certificado
+   */
+  async cartaCorrecao(dados, certificado) {
+    const xml = this.gerarXmlCartaCorrecao(dados);
+    const xmlAssinado = this.signService.assinarEvento(xml, certificado.pfx, certificado.senha);
+    const retorno = await this.soapService.enviarEvento(
+      xmlAssinado,
+      dados.chaveAcesso,
+      NFE_EVENTOS.CARTA_CORRECAO,
+      dados.idLote
+    );
+
+    return { tipo: 'carta_correcao', xmlGerado: xml, xmlAssinado, retorno };
+  }
+
+  /**
+   * Envia evento já assinado (mock ou produção).
+   * @param {string} xmlAssinado
+   * @param {string} chaveAcesso
+   * @param {string} tpEvento
+   */
+  async enviar(xmlAssinado, chaveAcesso, tpEvento) {
+    return this.soapService.enviarEvento(xmlAssinado, chaveAcesso, tpEvento);
+  }
+
+  /**
+   * Payload para persistência de evento no banco.
+   * @param {Awaited<ReturnType<NFeEventoService['cancelar']>>} resultado
+   */
+  toPersistencePayload(resultado) {
+    return {
+      chave_acesso: resultado.retorno.chaveAcesso ?? null,
+      tipo_evento: resultado.tipo,
+      xml_evento: resultado.xmlAssinado,
+      xml_retorno: resultado.retorno.xmlRetorno,
+      protocolo: resultado.retorno.protocolo,
+      status: resultado.retorno.cStat,
+      motivo: resultado.retorno.xMotivo,
+      registrado_em: new Date(),
+    };
+  }
+}

package/src/nfe/services/NFeService.js

@@ -0,0 +1,196 @@
+import { NFeXmlService } from './NFeXmlService.js';
+import { NFeSignService } from './NFeSignService.js';
+import { NFeSoapService } from './NFeSoapService.js';
+import { NFeEventoService } from './NFeEventoService.js';
+import { GhinfeError } from '../../errors/GhinfeError.js';
+import { gerarChaveAcesso, validarChaveAcesso } from '../../utils/chave.utils.js';
+import { SefazEndpointResolver } from '../../sefaz/SefazEndpointResolver.js';
+
+/**
+ * @param {{
+ *   mock?: boolean,
+ *   uf?: string,
+ *   ambiente?: number,
+ *   sefazEndpoint?: string,
+ *   sefazEventoEndpoint?: string,
+ *   mockScenario?: string,
+ *   mockEventoScenario?: string,
+ * }} options
+ */
+function buildSoapOptions(options) {
+  if (options.mock ?? true) {
+    return {
+      mock: true,
+      endpoint: options.sefazEndpoint,
+      eventoEndpoint: options.sefazEventoEndpoint,
+      mockScenario: options.mockScenario,
+      mockEventoScenario: options.mockEventoScenario,
+    };
+  }
+
+  if (options.sefazEndpoint) {
+    return {
+      mock: false,
+      endpoint: options.sefazEndpoint,
+      eventoEndpoint: options.sefazEventoEndpoint,
+    };
+  }
+
+  if (options.uf) {
+    const urls = SefazEndpointResolver.paraNFe(options.uf, options.ambiente ?? 2);
+    return { mock: false, endpoint: urls.endpoint, eventoEndpoint: urls.eventoEndpoint };
+  }
+
+  return { mock: true };
+}
+
+/**
+ * Orquestrador principal da NF-e — une geração, assinatura e envio.
+ */
+export class NFeService {
+  /**
+   * @param {{
+   *   mock?: boolean,
+   *   uf?: string,
+   *   ambiente?: number,
+   *   sefazEndpoint?: string,
+   *   sefazEventoEndpoint?: string,
+   *   mockScenario?: string,
+   *   mockEventoScenario?: string,
+   *   validarXsd?: boolean,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.options = options;
+    const soapOptions = buildSoapOptions(options);
+
+    this.xmlService = new NFeXmlService({ validarXsd: options.validarXsd });
+    this.signService = new NFeSignService();
+    this.soapService = new NFeSoapService(soapOptions);
+    this.eventoService = new NFeEventoService(soapOptions);
+  }
+
+  /** Resolve endpoints SEFAZ para a UF do documento. */
+  configurarUf(uf, ambiente = 2) {
+    const urls = SefazEndpointResolver.paraNFe(uf, ambiente);
+    this.soapService.endpoint = urls.endpoint;
+    this.soapService.eventoEndpoint = urls.eventoEndpoint;
+    this.soapService.mock = false;
+    this.eventoService.soapService.endpoint = urls.endpoint;
+    this.eventoService.soapService.eventoEndpoint = urls.eventoEndpoint;
+    this.eventoService.soapService.mock = false;
+    return urls;
+  }
+
+  /** @param {Parameters<typeof gerarChaveAcesso>[0]} params */
+  gerarChaveAcesso(params) {
+    return gerarChaveAcesso(params);
+  }
+
+  /** @param {import('../types/NFeDocument.js').NFeDocument} documento */
+  resolverDocumento(documento) {
+    if (documento.chaveAcesso) {
+      if (!validarChaveAcesso(documento.chaveAcesso)) {
+        throw new GhinfeError('chaveAcesso com dígito verificador inválido', 'CHAVE_DV_INVALIDO');
+      }
+      return documento;
+    }
+
+    const chaveAcesso = gerarChaveAcesso({
+      uf: documento.ide.uf,
+      cnpj: documento.emitente.cnpj,
+      modelo: '55',
+      serie: documento.ide.serie ?? 1,
+      numero: documento.ide.numero,
+      tipoEmissao: documento.ide.tipoEmissao ?? 1,
+    });
+
+    return { ...documento, chaveAcesso };
+  }
+
+  async emitir(documento, certificado, idLote) {
+    const doc = this.resolverDocumento(documento);
+
+    if (!this.soapService.mock && this.options.uf === undefined && !this.options.sefazEndpoint) {
+      this.configurarUf(doc.ide.uf, doc.ambiente ?? 2);
+    }
+
+    const xml = this.xmlService.gerarXml(doc);
+    const xmlAssinado = this.signService.assinar(xml, certificado.pfx, certificado.senha);
+    const retorno = await this.soapService.autorizar(xmlAssinado, doc.chaveAcesso, idLote);
+
+    return { chaveAcesso: doc.chaveAcesso, xmlGerado: xml, xmlAssinado, retorno };
+  }
+
+  gerarXml(documento, options = {}) {
+    const doc = this.resolverDocumento(documento);
+    return this.xmlService.gerarXml(doc, options);
+  }
+
+  gerarXmlAssinado(documento, certificado) {
+    const doc = this.resolverDocumento(documento);
+    const xml = this.xmlService.gerarXml(doc);
+    return this.signService.assinar(xml, certificado.pfx, certificado.senha);
+  }
+
+  async enviar(xmlAssinado, chaveAcesso) {
+    return this.soapService.autorizar(xmlAssinado, chaveAcesso);
+  }
+
+  validarXsd(xml, options = {}) {
+    return this.xmlService.validarXml(xml, options);
+  }
+
+  async cancelar(dados, certificado) {
+    return this.eventoService.cancelar(dados, certificado);
+  }
+
+  async cartaCorrecao(dados, certificado) {
+    return this.eventoService.cartaCorrecao(dados, certificado);
+  }
+
+  gerarXmlCancelamento(dados) {
+    return this.eventoService.gerarXmlCancelamento(dados);
+  }
+
+  gerarXmlCartaCorrecao(dados) {
+    return this.eventoService.gerarXmlCartaCorrecao(dados);
+  }
+
+  async enviarEventoMock(xmlEvento, chaveAcesso, tpEvento) {
+    return this.eventoService.enviar(xmlEvento, chaveAcesso, tpEvento);
+  }
+
+  /**
+   * Consulta status do webservice SEFAZ (NfeStatusServico4).
+   * @param {string} [uf]
+   * @param {number} [ambiente]
+   */
+  async consultarStatus(uf, ambiente) {
+    const ufConsulta = uf ?? this.options.uf;
+    if (!ufConsulta) {
+      throw new GhinfeError('UF é obrigatória para consultar status SEFAZ', 'STATUS_UF_REQUIRED');
+    }
+    return this.soapService.consultarStatus(ufConsulta, ambiente ?? this.options.ambiente ?? 2);
+  }
+
+  toPersistencePayload(resultado) {
+    if (!resultado.retorno.autorizado) {
+      throw new GhinfeError('Não é possível persistir NF-e não autorizada', 'NFE_NOT_AUTHORIZED', resultado.retorno);
+    }
+
+    return {
+      chave_acesso: resultado.chaveAcesso,
+      xml_nfe: resultado.xmlAssinado,
+      xml_protocolo: resultado.retorno.xmlProtocolo,
+      protocolo: resultado.retorno.protocolo,
+      status: resultado.retorno.cStat,
+      motivo: resultado.retorno.xMotivo,
+      autorizado_em: new Date(),
+    };
+  }
+
+  toEventoPersistencePayload(resultado) {
+    return this.eventoService.toPersistencePayload(resultado);
+  }
+}

package/src/nfe/services/NFeSignService.js

@@ -0,0 +1,111 @@
+import { SignedXml } from 'xml-crypto';
+import { DOMParser } from '@xmldom/xmldom';
+import { loadPfxCertificate } from '../../utils/certificate.utils.js';
+import { GhinfeError } from '../../errors/GhinfeError.js';
+
+/**
+ * Serviço de assinatura digital XML-DSig para NF-e (certificado A1 .pfx).
+ * Assina o elemento infNFe com algoritmo exigido pela SEFAZ.
+ */
+export class NFeSignService {
+  /**
+   * Assina o XML da NF-e usando certificado A1.
+   * @param {string} xmlNFe XML da NF-e sem assinatura
+   * @param {Buffer|string} pfxBuffer Conteúdo do arquivo .pfx
+   * @param {string} pfxPassword Senha do certificado
+   * @returns {string} XML assinado (NFe + Signature)
+   */
+  assinar(xmlNFe, pfxBuffer, pfxPassword) {
+    return this.#assinarElemento(xmlNFe, 'infNFe', pfxBuffer, pfxPassword);
+  }
+
+  /**
+   * Assina XML de evento NF-e (cancelamento, CC-e, etc.).
+   * @param {string} xmlEvento
+   * @param {Buffer|string} pfxBuffer
+   * @param {string} pfxPassword
+   * @returns {string}
+   */
+  assinarEvento(xmlEvento, pfxBuffer, pfxPassword) {
+    return this.#assinarElemento(xmlEvento, 'infEvento', pfxBuffer, pfxPassword);
+  }
+
+  /**
+   * Assina XML de RPS/NFS-e (elemento InfRps — ABRASF e derivados).
+   * @param {string} xmlRps
+   * @param {Buffer|string} pfxBuffer
+   * @param {string} pfxPassword
+   * @returns {string}
+   */
+  assinarRps(xmlRps, pfxBuffer, pfxPassword) {
+    let tag = 'InfRps';
+    if (xmlRps.includes('InfDeclaracaoPrestacaoServico')) tag = 'InfDeclaracaoPrestacaoServico';
+    else if (xmlRps.includes('<infRps') || xmlRps.includes('infRps ')) tag = 'infRps';
+    else if (xmlRps.includes('<InfRps') || xmlRps.includes('InfRps ')) tag = 'InfRps';
+    return this.#assinarElemento(xmlRps, tag, pfxBuffer, pfxPassword);
+  }
+
+  /**
+   * @param {string} xml
+   * @param {string} tagName
+   * @param {Buffer|string} pfxBuffer
+   * @param {string} pfxPassword
+   */
+  #assinarElemento(xml, tagName, pfxBuffer, pfxPassword) {
+    const { privateKeyPem, certificatePem } = loadPfxCertificate(pfxBuffer, pfxPassword);
+
+    const doc = new DOMParser().parseFromString(xml, 'text/xml');
+    const elemento = doc.getElementsByTagName(tagName)[0];
+
+    if (!elemento) {
+      throw new GhinfeError(`Elemento ${tagName} não encontrado no XML`, `SIGN_${tagName}_NOT_FOUND`);
+    }
+
+    const id = elemento.getAttribute('Id');
+    if (!id) {
+      throw new GhinfeError(`Atributo Id do ${tagName} é obrigatório para assinatura`, 'SIGN_MISSING_ID');
+    }
+
+    const signedXml = new SignedXml({
+      privateKey: privateKeyPem,
+      publicCert: certificatePem,
+      signatureAlgorithm: 'http://www.w3.org/2000/09/xmldsig#rsa-sha1',
+      canonicalizationAlgorithm: 'http://www.w3.org/TR/2001/REC-xml-c14n-20010315',
+    });
+
+    signedXml.addReference({
+      xpath: `//*[local-name()='${tagName}']`,
+      transforms: [
+        'http://www.w3.org/2000/09/xmldsig#enveloped-signature',
+        'http://www.w3.org/TR/2001/REC-xml-c14n-20010315',
+      ],
+      digestAlgorithm: 'http://www.w3.org/2000/09/xmldsig#sha1',
+      uri: `#${id}`,
+    });
+
+    signedXml.computeSignature(xml, {
+      location: { reference: `//*[local-name()='${tagName}']`, action: 'after' },
+    });
+
+    return signedXml.getSignedXml();
+  }
+
+  /**
+   * Extrai informações do certificado para validação pré-envio.
+   * @param {Buffer|string} pfxBuffer
+   * @param {string} pfxPassword
+   */
+  obterInfoCertificado(pfxBuffer, pfxPassword) {
+    const { certificate } = loadPfxCertificate(pfxBuffer, pfxPassword);
+    const subject = certificate.subject.attributes
+      .map((attr) => `${attr.shortName}=${attr.value}`)
+      .join(', ');
+
+    return {
+      subject,
+      validoDe: certificate.validity.notBefore,
+      validoAte: certificate.validity.notAfter,
+      serialNumber: certificate.serialNumber,
+    };
+  }
+}