ghinfe 0.6.0

package/src/nfse/services/NFSeService.js

@@ -0,0 +1,191 @@
+import { NFSeXmlBuilder } from '../builders/NFSeXmlBuilder.js';
+import { NFSeEventoXmlBuilder } from '../builders/NFSeEventoXmlBuilder.js';
+import { NFSeSoapService } from './NFSeSoapService.js';
+import { NFeSignService } from '../../nfe/services/NFeSignService.js';
+import { NFSeMunicipioResolver } from '../NFSeMunicipioResolver.js';
+import { NFSE_LAYOUTS } from '../constants/municipios.js';
+import { GhinfeError } from '../../errors/GhinfeError.js';
+
+/**
+ * Orquestrador NFS-e — emissão, cancelamento e substituição.
+ */
+export class NFSeService {
+  /**
+   * @param {{
+   *   mock?: boolean,
+   *   endpoint?: string,
+   *   mockScenario?: string,
+   *   layout?: string,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.builder = new NFSeXmlBuilder();
+    this.eventoBuilder = new NFSeEventoXmlBuilder();
+    this.signService = new NFeSignService();
+    this.soapService = new NFSeSoapService(options);
+  }
+
+  /** @param {import('../types/NFSeDocument.js').NFSeDocumento} documento */
+  resolverLayout(documento) {
+    if (this.options.layout) return this.options.layout;
+    try {
+      const info = NFSeMunicipioResolver.resolver(
+        documento.codigoMunicipio,
+        documento.ambiente ?? 2
+      );
+      return info.layout ?? NFSE_LAYOUTS.ABRASF;
+    } catch {
+      return NFSE_LAYOUTS.ABRASF;
+    }
+  }
+
+  /**
+   * @param {import('../types/NFSeDocument.js').NFSeDocumento} documento
+   * @param {string} [layout]
+   */
+  gerarXml(documento, layout) {
+    return this.builder.buildGerarNfse(documento, layout ?? this.resolverLayout(documento));
+  }
+
+  /**
+   * @param {import('../types/NFSeDocument.js').NFSeDocumento} documento
+   * @param {{ pfx: Buffer|string, senha: string }} certificado
+   * @param {string} [layout]
+   */
+  gerarXmlAssinado(documento, certificado, layout) {
+    const xml = this.gerarXml(documento, layout);
+    return this.signService.assinarRps(xml, certificado.pfx, certificado.senha);
+  }
+
+  /**
+   * @param {{
+   *   numeroNfse: string,
+   *   cnpjPrestador: string,
+   *   inscricaoMunicipal: string,
+   *   codigoMunicipio: string,
+   *   codigoCancelamento?: string,
+   * }} dados
+   */
+  gerarXmlCancelamento(dados) {
+    return this.eventoBuilder.buildCancelamento(dados);
+  }
+
+  /**
+   * @param {{
+   *   numeroNfseSubstituida: string,
+   *   cnpjPrestador: string,
+   *   inscricaoMunicipal: string,
+   *   codigoMunicipio: string,
+   *   codigoCancelamento?: string,
+   *   documentoSubstituto: import('../types/NFSeDocument.js').NFSeDocumento,
+   * }} dados
+   */
+  gerarXmlSubstituicao(dados) {
+    const xmlRps = this.gerarXml(dados.documentoSubstituto);
+    return this.eventoBuilder.buildSubstituicao({
+      ...dados,
+      xmlRpsSubstituto: xmlRps,
+    });
+  }
+
+  /**
+   * @param {import('../types/NFSeDocument.js').NFSeDocumento} documento
+   * @param {{ pfx?: Buffer|string, senha?: string }} [certificado]
+   */
+  async emitir(documento, certificado) {
+    const layout = this.resolverLayout(documento);
+    let xml = this.gerarXml(documento, layout);
+    let xmlAssinado = null;
+
+    if (certificado?.pfx && certificado?.senha) {
+      xmlAssinado = this.signService.assinarRps(xml, certificado.pfx, certificado.senha);
+      xml = xmlAssinado;
+    }
+
+    const retorno = await this.soapService.gerarNfse(
+      xml,
+      documento.codigoMunicipio,
+      documento.ambiente ?? 2
+    );
+
+    return {
+      layout,
+      xmlGerado: xmlAssinado ? this.gerarXml(documento, layout) : xml,
+      xmlAssinado,
+      retorno,
+    };
+  }
+
+  /**
+   * Cancela NFS-e já autorizada.
+   * @param {{
+   *   numeroNfse: string,
+   *   cnpjPrestador: string,
+   *   inscricaoMunicipal: string,
+   *   codigoMunicipio: string,
+   *   codigoCancelamento?: string,
+   *   ambiente?: number,
+   * }} dados
+   */
+  async cancelar(dados) {
+    const xml = this.gerarXmlCancelamento(dados);
+    const retorno = await this.soapService.cancelarNfse(
+      xml,
+      dados.codigoMunicipio,
+      dados.ambiente ?? 2
+    );
+    return { tipo: 'cancelamento', xmlGerado: xml, retorno };
+  }
+
+  /**
+   * Substitui NFS-e por um novo RPS.
+   * @param {{
+   *   numeroNfseSubstituida: string,
+   *   cnpjPrestador: string,
+   *   inscricaoMunicipal: string,
+   *   codigoMunicipio: string,
+   *   codigoCancelamento?: string,
+   *   documentoSubstituto: import('../types/NFSeDocument.js').NFSeDocumento,
+   *   ambiente?: number,
+   * }} dados
+   * @param {{ pfx?: Buffer|string, senha?: string }} [certificado]
+   */
+  async substituir(dados, certificado) {
+    let xmlEnvio = this.gerarXmlSubstituicao(dados);
+
+    if (certificado?.pfx && certificado?.senha) {
+      const xmlRps = this.gerarXmlAssinado(dados.documentoSubstituto, certificado);
+      xmlEnvio = this.eventoBuilder.buildSubstituicao({
+        ...dados,
+        xmlRpsSubstituto: xmlRps,
+      });
+    }
+
+    const retorno = await this.soapService.substituirNfse(
+      xmlEnvio,
+      dados.codigoMunicipio,
+      dados.ambiente ?? 2
+    );
+
+    return { tipo: 'substituicao', xmlGerado: xmlEnvio, retorno };
+  }
+
+  /**
+   * @param {Awaited<ReturnType<NFSeService['emitir']>>} resultado
+   */
+  toPersistencePayload(resultado) {
+    if (!resultado.retorno.autorizado) {
+      throw new GhinfeError('NFS-e não autorizada', 'NFSE_NOT_AUTHORIZED', resultado.retorno);
+    }
+
+    return {
+      numero_nfse: resultado.retorno.numeroNfse,
+      codigo_verificacao: resultado.retorno.codigoVerificacao,
+      layout: resultado.layout,
+      xml_rps: resultado.xmlAssinado ?? resultado.xmlGerado,
+      xml_retorno: resultado.retorno.xmlRetorno,
+      autorizado_em: new Date(),
+    };
+  }
+}

package/src/nfse/services/NFSeSoapService.js

@@ -0,0 +1,232 @@
+import axios from 'axios';
+import { GhinfeError } from '../../errors/GhinfeError.js';
+import { NFSeMunicipioResolver } from '../NFSeMunicipioResolver.js';
+import {
+  buildMockGerarNfseResponse,
+  buildMockCancelarNfseResponse,
+  buildMockSubstituirNfseResponse,
+  NFSE_MOCK_RESPONSES,
+} from '../mocks/nfse-responses.js';
+
+export class NFSeSoapError extends GhinfeError {
+  /**
+   * @param {string} codigo
+   * @param {string} mensagem
+   * @param {Record<string, unknown>} [details]
+   */
+  constructor(codigo, mensagem, details = {}) {
+    super(`NFS-e [${codigo}]: ${mensagem}`, `NFSE_${codigo}`, { codigo, mensagem, ...details });
+    this.name = 'NFSeSoapError';
+    this.codigo = codigo;
+  }
+}
+
+/**
+ * Comunicação SOAP com prefeituras (NFS-e ABRASF).
+ */
+export class NFSeSoapService {
+  /**
+   * @param {{ mock?: boolean, endpoint?: string, timeout?: number, mockScenario?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.mock = options.mock ?? true;
+    this.endpoint = options.endpoint;
+    this.timeout = options.timeout ?? 30000;
+    this.mockScenario = options.mockScenario ?? 'autorizada';
+  }
+
+  /**
+   * @param {string} xmlRps
+   * @param {string} codigoMunicipio
+   * @param {number} [ambiente]
+   */
+  async gerarNfse(xmlRps, codigoMunicipio, ambiente = 2) {
+    if (this.mock) {
+      return this.#mockGerarNfse(xmlRps);
+    }
+
+    const { url } = this.endpoint
+      ? { url: this.endpoint }
+      : NFSeMunicipioResolver.resolver(codigoMunicipio, ambiente);
+
+    const envelope = this.#buildEnvelope('GerarNfse', xmlRps);
+
+    try {
+      const response = await axios.post(url, envelope, {
+        headers: { 'Content-Type': 'text/xml; charset=utf-8', SOAPAction: 'GerarNfse' },
+        timeout: this.timeout,
+        responseType: 'text',
+      });
+
+      return this.#processarRetorno(response.data);
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        throw new GhinfeError(`Falha SOAP NFS-e: ${error.message}`, 'NFSE_HTTP_ERROR', {
+          status: error.response?.status,
+        });
+      }
+      throw error;
+    }
+  }
+
+  /** @param {string} metodo @param {string} xml */
+  #buildEnvelope(metodo, xml) {
+    const escaped = xml.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<?xml version="1.0" encoding="utf-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <${metodo} xmlns="http://www.abrasf.org.br/nfse.xsd">
+      <nfseDadosMsg>${escaped}</nfseDadosMsg>
+    </${metodo}>
+  </soap:Body>
+</soap:Envelope>`;
+  }
+
+  /**
+   * @param {string} xmlCancelamento
+   * @param {string} codigoMunicipio
+   * @param {number} [ambiente]
+   */
+  async cancelarNfse(xmlCancelamento, codigoMunicipio, ambiente = 2) {
+    if (this.mock) {
+      await new Promise((r) => setTimeout(r, 150));
+      const numero = xmlCancelamento.match(/<Numero>(\d+)<\/Numero>/)?.[1] ?? '';
+      const resultado = this.mockScenario === 'rejeicao'
+        ? NFSE_MOCK_RESPONSES.rejeicao
+        : NFSE_MOCK_RESPONSES.cancelada;
+      const xml = buildMockCancelarNfseResponse(numero, resultado);
+      return this.#processarRetornoEvento(xml, { mock: true, operacao: 'cancelamento' });
+    }
+
+    return this.#postMetodo('CancelarNfse', xmlCancelamento, codigoMunicipio, ambiente, 'cancelamento');
+  }
+
+  /**
+   * @param {string} xmlSubstituicao
+   * @param {string} codigoMunicipio
+   * @param {number} [ambiente]
+   */
+  async substituirNfse(xmlSubstituicao, codigoMunicipio, ambiente = 2) {
+    if (this.mock) {
+      await new Promise((r) => setTimeout(r, 150));
+      const resultado = this.mockScenario === 'rejeicao'
+        ? NFSE_MOCK_RESPONSES.rejeicao
+        : NFSE_MOCK_RESPONSES.substituida;
+      const xml = buildMockSubstituirNfseResponse(resultado);
+      return this.#processarRetornoEvento(xml, { mock: true, operacao: 'substituicao' });
+    }
+
+    return this.#postMetodo('SubstituirNfse', xmlSubstituicao, codigoMunicipio, ambiente, 'substituicao');
+  }
+
+  /**
+   * @param {string} metodo
+   * @param {string} xml
+   * @param {string} codigoMunicipio
+   * @param {number} ambiente
+   * @param {string} operacao
+   */
+  async #postMetodo(metodo, xml, codigoMunicipio, ambiente, operacao) {
+    const { url } = this.endpoint
+      ? { url: this.endpoint }
+      : NFSeMunicipioResolver.resolver(codigoMunicipio, ambiente);
+
+    const envelope = this.#buildEnvelope(metodo, xml);
+
+    try {
+      const response = await axios.post(url, envelope, {
+        headers: { 'Content-Type': 'text/xml; charset=utf-8', SOAPAction: metodo },
+        timeout: this.timeout,
+        responseType: 'text',
+      });
+      return this.#processarRetornoEvento(response.data, { operacao });
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        throw new GhinfeError(`Falha SOAP NFS-e (${operacao}): ${error.message}`, 'NFSE_HTTP_ERROR', {
+          status: error.response?.status,
+        });
+      }
+      throw error;
+    }
+  }
+
+  /** @param {string} xmlRps */
+  async #mockGerarNfse(xmlRps) {
+    await new Promise((r) => setTimeout(r, 200));
+
+    const numeroMatch = xmlRps.match(/<Numero>(\d+)<\/Numero>/);
+    const numeroRps = numeroMatch?.[1] ?? '1';
+
+    const scenario = this.mockScenario === 'rejeicao'
+      ? NFSE_MOCK_RESPONSES.rejeicao
+      : NFSE_MOCK_RESPONSES.autorizada;
+
+    const innerXml = buildMockGerarNfseResponse(numeroRps, scenario);
+    return this.#processarRetorno(innerXml, { mock: true });
+  }
+
+  /** @param {string} xml @param {Record<string, unknown>} [meta] */
+  #processarRetorno(xml, meta = {}) {
+    const codigoMatch = xml.match(/<Codigo>([^<]+)<\/Codigo>/);
+    const mensagemMatch = xml.match(/<Mensagem>([^<]+)<\/Mensagem>/);
+    const numeroNfseMatch = xml.match(/<InfNfse[\s\S]*?<Numero>(\d+)<\/Numero>/);
+    const codVerifMatch = xml.match(/<CodigoVerificacao>([^<]+)<\/CodigoVerificacao>/);
+
+    const temNfse = xml.includes('<ListaNfse>') || xml.includes('<InfNfse>');
+
+    if (temNfse && !xml.includes('ListaMensagemRetorno')) {
+      return {
+        sucesso: true,
+        autorizado: true,
+        numeroNfse: numeroNfseMatch?.[1],
+        codigoVerificacao: codVerifMatch?.[1],
+        xmlRetorno: xml,
+        ...meta,
+      };
+    }
+
+    const codigo = codigoMatch?.[1] ?? 'E999';
+    const mensagem = mensagemMatch?.[1] ?? 'Retorno não identificado';
+    throw new NFSeSoapError(codigo, mensagem, { xmlRetorno: xml, ...meta });
+  }
+
+  /**
+   * @param {string} xml
+   * @param {Record<string, unknown>} [meta]
+   */
+  #processarRetornoEvento(xml, meta = {}) {
+    if (xml.includes('ListaMensagemRetorno') && !xml.includes('RetCancelamento') && !xml.includes('RetSubstituicao')) {
+      const codigo = xml.match(/<Codigo>([^<]+)<\/Codigo>/)?.[1] ?? 'E999';
+      const mensagem = xml.match(/<Mensagem>([^<]+)<\/Mensagem>/)?.[1] ?? 'Retorno não identificado';
+      throw new NFSeSoapError(codigo, mensagem, { xmlRetorno: xml, ...meta });
+    }
+
+    if (xml.includes('RetCancelamento') || xml.includes('Confirmacao')) {
+      const numero = xml.match(/<Numero>(\d+)<\/Numero>/)?.[1];
+      return {
+        sucesso: true,
+        cancelado: true,
+        numeroNfse: numero,
+        xmlRetorno: xml,
+        ...meta,
+      };
+    }
+
+    if (xml.includes('RetSubstituicao') || xml.includes('NfseSubstituidora')) {
+      const nova = xml.match(/<NfseSubstituidora>[\s\S]*?<Numero>(\d+)<\/Numero>/)?.[1];
+      const antiga = xml.match(/<NfseSubstituida>[\s\S]*?<Numero>(\d+)<\/Numero>/)?.[1];
+      const codVerif = xml.match(/<CodigoVerificacao>([^<]+)<\/CodigoVerificacao>/)?.[1];
+      return {
+        sucesso: true,
+        substituido: true,
+        numeroNfse: nova,
+        numeroNfseSubstituida: antiga,
+        codigoVerificacao: codVerif,
+        xmlRetorno: xml,
+        ...meta,
+      };
+    }
+
+    return this.#processarRetorno(xml, meta);
+  }
+}

package/src/nfse/services/NFSeXmlService.js

@@ -0,0 +1,12 @@
+import { NFSeXmlBuilder } from '../builders/NFSeXmlBuilder.js';
+
+export class NFSeXmlService {
+  constructor() {
+    this.builder = new NFSeXmlBuilder();
+  }
+
+  /** @param {import('../types/NFSeDocument.js').NFSeDocumento} documento @param {string} [layout] */
+  gerarXml(documento, layout) {
+    return this.builder.buildGerarNfse(documento, layout);
+  }
+}

package/src/nfse/types/NFSeDocument.js

@@ -0,0 +1,54 @@
+/**
+ * @typedef {Object} NFSeTomador
+ * @property {string} [cnpj]
+ * @property {string} [cpf]
+ * @property {string} razaoSocial
+ * @property {string} [email]
+ * @property {string} [telefone]
+ * @property {Object} [endereco]
+ * @property {string} endereco.logradouro
+ * @property {string} endereco.numero
+ * @property {string} [endereco.complemento]
+ * @property {string} endereco.bairro
+ * @property {string} endereco.codigoMunicipio IBGE
+ * @property {string} endereco.uf
+ * @property {string} endereco.cep
+ */
+
+/**
+ * @typedef {Object} NFSeServico
+ * @property {string} itemListaServico LC 116 (ex: "01.01")
+ * @property {string} discriminacao
+ * @property {string} codigoMunicipio IBGE prestação
+ * @property {number} valorServicos
+ * @property {number} [valorDeducoes]
+ * @property {number} [valorPis]
+ * @property {number} [valorCofins]
+ * @property {number} [valorInss]
+ * @property {number} [valorIr]
+ * @property {number} [valorCsll]
+ * @property {number} [aliquotaIss]
+ * @property {number} [valorIss]
+ * @property {number} [descontoIncondicionado]
+ * @property {number} [descontoCondicionado]
+ * @property {number} [issRetido] 1=Sim, 2=Não
+ */
+
+/**
+ * @typedef {Object} NFSeDocumento
+ * @property {number} numero RPS
+ * @property {string} [serie]
+ * @property {number} [tipo] 1=RPS
+ * @property {number} [ambiente] 1=Produção, 2=Homologação
+ * @property {string} codigoMunicipio IBGE do prestador
+ * @property {string} cnpjPrestador
+ * @property {string} inscricaoMunicipal
+ * @property {number} [naturezaOperacao] 1=Tributação no município
+ * @property {number} [optanteSimplesNacional] 1=Sim, 2=Não
+ * @property {number} [incentivadorCultural] 1=Sim, 2=Não
+ * @property {NFSeServico} servico
+ * @property {NFSeTomador} tomador
+ * @property {string} [informacoesComplementares]
+ */
+
+export {};

package/src/queue/NFCeQueue.js

@@ -0,0 +1,63 @@
+import Bull from 'bull';
+import { NFCeService } from '../nfce/services/NFCeService.js';
+
+/**
+ * Fila Bull/Redis para processamento assíncrono de NFC-e.
+ */
+export class NFCeQueue {
+  /**
+   * @param {{
+   *   redis?: { host?: string, port?: number, password?: string },
+   *   queueName?: string,
+   *   nfceOptions?: ConstructorParameters<typeof NFCeService>[0],
+   * }} [options]
+   */
+  constructor(options = {}) {
+    const redis = options.redis ?? { host: '127.0.0.1', port: 6379 };
+    const queueName = options.queueName ?? 'ghinfe:nfce:emissao';
+
+    this.queue = new Bull(queueName, { redis });
+    this.nfceService = new NFCeService(options.nfceOptions ?? { mock: true });
+    this.#registerProcessor();
+  }
+
+  #registerProcessor() {
+    this.queue.process(async (job) => {
+      const { documento, certificado } = job.data;
+      return this.nfceService.emitir(documento, certificado);
+    });
+  }
+
+  /**
+   * @param {{
+   *   documento: import('../nfce/types/NFCeDocument.js').NFCeDocumento,
+   *   certificado: { pfx: Buffer|string, senha: string },
+   * }} payload
+   */
+  async adicionarEmissao(payload) {
+    return this.queue.add(payload, {
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 5000 },
+      removeOnComplete: 100,
+      removeOnFail: 500,
+    });
+  }
+
+  /** @param {(resultado: Awaited<ReturnType<NFCeService['emitir']>>, job: Bull.Job) => Promise<void>} handler */
+  onCompleted(handler) {
+    this.queue.on('completed', async (job, resultado) => {
+      await handler(resultado, job);
+    });
+  }
+
+  /** @param {(error: Error, job: Bull.Job) => Promise<void>} handler */
+  onFailed(handler) {
+    this.queue.on('failed', async (job, error) => {
+      await handler(error, job);
+    });
+  }
+
+  async close() {
+    await this.queue.close();
+  }
+}

package/src/queue/NFSeQueue.js

@@ -0,0 +1,59 @@
+import Bull from 'bull';
+import { NFSeService } from '../nfse/services/NFSeService.js';
+
+/**
+ * Fila Bull/Redis para processamento assíncrono de NFS-e.
+ */
+export class NFSeQueue {
+  /**
+   * @param {{
+   *   redis?: { host?: string, port?: number, password?: string },
+   *   queueName?: string,
+   *   nfseOptions?: ConstructorParameters<typeof NFSeService>[0],
+   * }} [options]
+   */
+  constructor(options = {}) {
+    const redis = options.redis ?? { host: '127.0.0.1', port: 6379 };
+    const queueName = options.queueName ?? 'ghinfe:nfse:emissao';
+
+    this.queue = new Bull(queueName, { redis });
+    this.nfseService = new NFSeService(options.nfseOptions ?? { mock: true });
+    this.#registerProcessor();
+  }
+
+  #registerProcessor() {
+    this.queue.process(async (job) => {
+      const { documento } = job.data;
+      return this.nfseService.emitir(documento);
+    });
+  }
+
+  /**
+   * @param {{ documento: import('../nfse/types/NFSeDocument.js').NFSeDocumento }} payload
+   */
+  async adicionarEmissao(payload) {
+    return this.queue.add(payload, {
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 5000 },
+      removeOnComplete: 100,
+      removeOnFail: 500,
+    });
+  }
+
+  /** @param {(resultado: Awaited<ReturnType<NFSeService['emitir']>>, job: Bull.Job) => Promise<void>} handler */
+  onCompleted(handler) {
+    this.queue.on('completed', async (job, resultado) => {
+      await handler(resultado, job);
+    });
+  }
+
+  onFailed(handler) {
+    this.queue.on('failed', async (job, error) => {
+      await handler(error, job);
+    });
+  }
+
+  async close() {
+    await this.queue.close();
+  }
+}

package/src/queue/NFeQueue.js

@@ -0,0 +1,76 @@
+import Bull from 'bull';
+import { NFeService } from '../nfe/services/NFeService.js';
+
+/**
+ * Fila Bull/Redis para processamento assíncrono de NF-e.
+ * Integra com Sequelize no worker: persista o retorno após autorização.
+ *
+ * @example
+ * const queue = new NFeQueue({ redis: { host: '127.0.0.1', port: 6379 } });
+ * await queue.adicionarEmissao({ documento, certificado });
+ * queue.processar(async (resultado) => { await NotaFiscal.create(...); });
+ */
+export class NFeQueue {
+  /**
+   * @param {{
+   *   redis?: { host?: string, port?: number, password?: string },
+   *   queueName?: string,
+   *   nfeOptions?: ConstructorParameters<typeof NFeService>[0],
+   * }} [options]
+   */
+  constructor(options = {}) {
+    const redis = options.redis ?? { host: '127.0.0.1', port: 6379 };
+    const queueName = options.queueName ?? 'ghinfe:nfe:emissao';
+
+    this.queue = new Bull(queueName, { redis });
+    this.nfeService = new NFeService(options.nfeOptions ?? { mock: true });
+    this.#registerProcessor();
+  }
+
+  #registerProcessor() {
+    this.queue.process(async (job) => {
+      const { documento, certificado, idLote } = job.data;
+      const resultado = await this.nfeService.emitir(documento, certificado, idLote);
+      return resultado;
+    });
+  }
+
+  /**
+   * @param {{
+   *   documento: import('../nfe/types/NFeDocument.js').NFeDocument,
+   *   certificado: { pfx: Buffer|string, senha: string },
+   *   idLote?: string,
+   * }} payload
+   */
+  async adicionarEmissao(payload) {
+    return this.queue.add(payload, {
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 5000 },
+      removeOnComplete: 100,
+      removeOnFail: 500,
+    });
+  }
+
+  /**
+   * Callback executado após emissão bem-sucedida (ex: salvar no Sequelize).
+   * @param {(resultado: Awaited<ReturnType<NFeService['emitir']>>, job: Bull.Job) => Promise<void>} handler
+   */
+  onCompleted(handler) {
+    this.queue.on('completed', async (job, resultado) => {
+      await handler(resultado, job);
+    });
+  }
+
+  /**
+   * @param {(error: Error, job: Bull.Job) => Promise<void>} handler
+   */
+  onFailed(handler) {
+    this.queue.on('failed', async (job, error) => {
+      await handler(error, job);
+    });
+  }
+
+  async close() {
+    await this.queue.close();
+  }
+}