ghinfe 0.6.0 → 0.6.2

package/src/dce/services/DCeService.js

@@ -0,0 +1,263 @@
+import { DCeXmlService } from './DCeXmlService.js';
+import { DCeSoapService } from './DCeSoapService.js';
+import { DCeEventoXmlBuilder } from '../builders/DCeEventoXmlBuilder.js';
+import { DaceService } from '../dace/DaceService.js';
+import { NFeSignService } from '../../nfe/services/NFeSignService.js';
+import { GhinfeError } from '../../errors/GhinfeError.js';
+import { gerarChaveAcessoDCe, parseChaveAcessoDCe } from '../../utils/chave.utils.js';
+import { assinarChaveQrCodeDCe, gerarUrlQrCodeDCe } from '../utils/qrcode.utils.js';
+import { DCE_MODELO, DCE_TIPO_EMITENTE, DCE_TIPO_EMISSAO } from '../constants/dce.js';
+
+/**
+ * Orquestrador da DC-e (Declaração de Conteúdo eletrônica, modelo 99).
+ */
+export class DCeService {
+  /**
+   * @param {{
+   *   certificado?: { pfx: Buffer|string, senha: string },
+   *   ambiente?: number,
+   *   timeout?: number,
+   *   compactar?: boolean,
+   *   validarXsd?: boolean,
+   *   qrCodeUrl?: string,
+   *   urlChave?: string,
+   * }} [options]
+   *   certificado: obrigatório para comunicação com a SEFAZ (TLS mútuo e assinatura)
+   *   compactar: envia a DC-e via dceAutorizacaoZip (GZip + Base64)
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.ambiente = options.ambiente ?? 2;
+    this.xmlService = new DCeXmlService({ validarXsd: options.validarXsd });
+    this.signService = new NFeSignService();
+    this.eventoBuilder = new DCeEventoXmlBuilder();
+    this.soapService = options.certificado
+      ? new DCeSoapService({ certificado: options.certificado, ambiente: this.ambiente, timeout: options.timeout })
+      : null;
+  }
+
+  #certificado() {
+    if (!this.options.certificado || !this.soapService) {
+      throw new GhinfeError(
+        'Informe options.certificado no DCeService para comunicar com a SEFAZ',
+        'DCE_CERTIFICADO_AUSENTE'
+      );
+    }
+    return this.options.certificado;
+  }
+
+  /**
+   * CNPJ que compõe a chave: de quem emite/assina a DC-e.
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento
+   */
+  #cnpjChave(documento) {
+    const tpEmit = documento.ide.tipoEmitente;
+    const origem = {
+      [DCE_TIPO_EMITENTE.FISCO]: ['fisco', documento.fisco],
+      [DCE_TIPO_EMITENTE.MARKETPLACE]: ['marketplace', documento.marketplace],
+      [DCE_TIPO_EMITENTE.EMISSOR_PROPRIO]: ['emitente', documento.emitente],
+      [DCE_TIPO_EMITENTE.TRANSPORTADORA]: ['transportadora', documento.transportadora],
+      [DCE_TIPO_EMITENTE.ECT]: ['ect', documento.ect],
+    }[tpEmit];
+
+    if (!origem) {
+      throw new GhinfeError(`ide.tipoEmitente inválido: ${tpEmit}`, 'DCE_TP_EMIT_INVALIDO');
+    }
+    const [campo, parte] = origem;
+    if (!parte?.cnpj) {
+      throw new GhinfeError(`${campo}.cnpj é obrigatório para tipoEmitente=${tpEmit}`, 'DCE_CNPJ_CHAVE_AUSENTE');
+    }
+    return parte.cnpj;
+  }
+
+  /**
+   * Gera a chave de acesso (se ausente) e fixa a data de emissão usada no AAMM e no dhEmi.
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento
+   */
+  resolverDocumento(documento) {
+    const ambiente = documento.ambiente ?? this.ambiente;
+
+    if (documento.chaveAcesso) {
+      const chave = parseChaveAcessoDCe(documento.chaveAcesso);
+      if (!chave.valida) {
+        throw new GhinfeError('chaveAcesso com dígito verificador inválido', 'CHAVE_DV_INVALIDO');
+      }
+      if (chave.modelo !== DCE_MODELO) {
+        throw new GhinfeError('chaveAcesso não é de DC-e (modelo 99)', 'DCE_MODELO_INVALIDO');
+      }
+      return { ...documento, ambiente };
+    }
+
+    const dataEmissao = documento.ide.dataEmissao ?? new Date();
+    const chaveAcesso = gerarChaveAcessoDCe({
+      uf: documento.ide.uf,
+      cnpj: this.#cnpjChave(documento),
+      serie: documento.ide.serie ?? 1,
+      numero: documento.ide.numero,
+      tipoEmitente: documento.ide.tipoEmitente,
+      tipoEmissao: documento.ide.tipoEmissao,
+      siteAutorizador: documento.ide.siteAutorizador,
+      codigoNumerico: documento.ide.codigoNumerico,
+      dataEmissao,
+    });
+
+    return { ...documento, ambiente, ide: { ...documento.ide, dataEmissao }, chaveAcesso };
+  }
+
+  /**
+   * Monta a URL do QR Code. Em contingência off-line exige o certificado para o parâmetro sign.
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento Já resolvido (com chaveAcesso)
+   * @param {{ pfx: Buffer|string, senha: string }} [certificado]
+   */
+  gerarQrCode(documento, certificado) {
+    const { tipoEmissao } = parseChaveAcessoDCe(documento.chaveAcesso);
+    const offline = tipoEmissao === DCE_TIPO_EMISSAO.CONTINGENCIA_OFFLINE;
+
+    if (offline && !certificado) {
+      throw new GhinfeError(
+        'Certificado obrigatório para gerar o QR Code em contingência off-line',
+        'DCE_QRCODE_CERTIFICADO_AUSENTE'
+      );
+    }
+
+    return gerarUrlQrCodeDCe({
+      chaveAcesso: documento.chaveAcesso,
+      ambiente: documento.ambiente ?? 2,
+      tipoEmissao,
+      emitente: documento.emitente,
+      sign: offline ? assinarChaveQrCodeDCe(documento.chaveAcesso, certificado.pfx, certificado.senha) : undefined,
+      baseUrl: this.options.qrCodeUrl,
+    });
+  }
+
+  /**
+   * Gera XML completo (com infDCeSupl) sem assinatura.
+   * Em contingência off-line use gerarXmlAssinado — o QR Code depende do certificado.
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento
+   * @param {{ validarXsd?: boolean }} [options]
+   */
+  gerarXml(documento, options = {}) {
+    const doc = this.resolverDocumento(documento);
+    return this.xmlService.gerarXml(doc, {
+      validarXsd: options.validarXsd,
+      qrCode: this.gerarQrCode(doc),
+      urlChave: this.options.urlChave ?? this.options.qrCodeUrl,
+    });
+  }
+
+  /**
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento
+   * @param {{ pfx: Buffer|string, senha: string }} certificado
+   * @param {{ validarXsd?: boolean }} [options]
+   */
+  gerarXmlAssinado(documento, certificado, options = {}) {
+    const doc = this.resolverDocumento(documento);
+    const qrCode = this.gerarQrCode(doc, certificado);
+
+    const xml = this.xmlService.gerarXml(doc, {
+      validarXsd: false,
+      qrCode,
+      urlChave: this.options.urlChave ?? this.options.qrCodeUrl,
+    });
+    const xmlAssinado = this.signService.assinarDCe(xml, certificado.pfx, certificado.senha);
+
+    if (options.validarXsd ?? this.xmlService.validarXsd) {
+      this.xmlService.validarXml(xmlAssinado);
+    }
+
+    return { chaveAcesso: doc.chaveAcesso, xml: xmlAssinado, qrCode };
+  }
+
+  /** @param {string} xml */
+  validarXsd(xml) {
+    return this.xmlService.validarXml(xml);
+  }
+
+  /**
+   * Consulta status do web service de autorização (DCeStatusServico).
+   * @param {string} [uf]
+   */
+  async consultarStatus(uf) {
+    this.#certificado();
+    return this.soapService.consultarStatus(uf);
+  }
+
+  /**
+   * Gera, assina, valida (XSD) e envia a DC-e para autorização.
+   * Lança SefazError em caso de rejeição.
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento
+   * @param {{ compactar?: boolean }} [options]
+   */
+  async emitir(documento, options = {}) {
+    const certificado = this.#certificado();
+    const doc = this.resolverDocumento(documento);
+
+    if (doc.ambiente !== this.ambiente) {
+      throw new GhinfeError(
+        `documento.ambiente (${doc.ambiente}) difere do ambiente do serviço (${this.ambiente})`,
+        'DCE_AMBIENTE_DIVERGENTE'
+      );
+    }
+
+    const { xml, qrCode } = this.gerarXmlAssinado(doc, certificado, { validarXsd: true });
+    const retorno = await this.soapService.autorizar(xml, {
+      compactar: options.compactar ?? this.options.compactar,
+    });
+
+    return { chaveAcesso: doc.chaveAcesso, qrCode, xmlAssinado: xml, retorno };
+  }
+
+  /**
+   * Consulta situação da DC-e na SEFAZ (DCeConsulta).
+   * @param {string} chaveAcesso
+   */
+  async consultar(chaveAcesso) {
+    this.#certificado();
+    return this.soapService.consultar(chaveAcesso);
+  }
+
+  /**
+   * Cancela a DC-e (evento 110111). Prazo: até 24h após a autorização.
+   * @param {{
+   *   chaveAcesso: string,
+   *   protocolo: string,
+   *   justificativa: string,
+   *   emitente: { cnpj?: string, cpf?: string, idOutros?: string },
+   *   sequencia?: number,
+   *   dataEvento?: Date,
+   * }} params emitente: mesmo usuário emitente (grupo emit) da DC-e
+   */
+  async cancelar(params) {
+    const certificado = this.#certificado();
+    const xmlEvento = this.eventoBuilder.buildCancelamento({ ...params, ambiente: this.ambiente });
+    const xmlAssinado = this.signService.assinarEvento(xmlEvento, certificado.pfx, certificado.senha);
+    this.xmlService.validarEvento(xmlAssinado);
+
+    const retorno = await this.soapService.enviarEvento(xmlAssinado);
+    return { chaveAcesso: params.chaveAcesso, xmlEvento: xmlAssinado, retorno };
+  }
+
+  /**
+   * Gera a DACE em HTML a partir do dceProc (ou do resultado de emitir()).
+   * @param {string|Awaited<ReturnType<DCeService['emitir']>>} xmlOuResultado
+   * @param {Parameters<DaceService['gerar']>[1]} [opcoes]
+   */
+  async gerarDace(xmlOuResultado, opcoes) {
+    const xml = typeof xmlOuResultado === 'string' ? xmlOuResultado : xmlOuResultado.retorno.xmlProc;
+    return new DaceService().gerar(xml, opcoes);
+  }
+
+  /** @param {Awaited<ReturnType<DCeService['emitir']>>} resultado */
+  toPersistencePayload(resultado) {
+    return {
+      chave_acesso: resultado.chaveAcesso,
+      modelo: DCE_MODELO,
+      xml_dce: resultado.retorno.xmlProc,
+      protocolo: resultado.retorno.protocolo,
+      qrcode_url: resultado.qrCode,
+      status: resultado.retorno.cStat,
+      motivo: resultado.retorno.xMotivo,
+      autorizado_em: resultado.retorno.dhRecbto ? new Date(resultado.retorno.dhRecbto) : new Date(),
+    };
+  }
+}

package/src/dce/services/DCeSoapService.js

@@ -0,0 +1,235 @@
+import zlib from 'zlib';
+import axios from 'axios';
+import { criarHttpsAgentSefaz } from '../../sefaz/httpsAgent.js';
+import { GhinfeError } from '../../errors/GhinfeError.js';
+import { SefazError } from '../../errors/SefazError.js';
+import { UF_IBGE } from '../../constants/sefaz.js';
+import { DCE_NAMESPACE, DCE_VERSAO, DCE_WEBSERVICES, DCE_STATUS } from '../constants/dce.js';
+
+const SERVICOS = {
+  autorizacao: { wsdl: 'DCeAutorizacao', metodo: 'dceAutorizacao' },
+  consulta: { wsdl: 'DCeConsulta', metodo: 'dceConsulta' },
+  status: { wsdl: 'DCeStatusServico', metodo: 'dceStatusServico' },
+  evento: { wsdl: 'DCeRecepcaoEvento', metodo: 'dceRecepcaoEvento' },
+};
+
+// O WSDL de DCeConsulta declara dceResultMsg, mas o servidor responde dceConsultaResult
+const RESULTADO_SOAP = /<(dce\w*Result(?:Msg)?)(?:\s[^>]*)?>([\s\S]*?)<\/\1>/;
+
+const semDeclaracao = (xml) => xml.replace(/^\s*<\?xml[^>]*\?>\s*/, '');
+
+/** @param {string} xml @param {string} nome */
+function tag(xml, nome) {
+  return xml?.match(new RegExp(`<${nome}(?:\\s[^>]*)?>([^<]*)</${nome}>`))?.[1];
+}
+
+/** @param {string} xml @param {string} nome */
+function grupo(xml, nome) {
+  return xml?.match(new RegExp(`<${nome}[\\s>][\\s\\S]*?</${nome}>`))?.[0];
+}
+
+/**
+ * Cliente SOAP 1.2 dos web services da DC-e, com TLS mútuo (certificado A1).
+ */
+export class DCeSoapService {
+  /**
+   * @param {{
+   *   certificado: { pfx: Buffer|string, senha: string },
+   *   ambiente?: number,
+   *   timeout?: number,
+   *   endpoints?: Partial<Record<keyof typeof SERVICOS, string>>,
+   *   ca?: string|string[],
+   * }} options
+   */
+  constructor(options) {
+    if (!options?.certificado) {
+      throw new GhinfeError('Certificado A1 obrigatório para comunicação com a SEFAZ', 'DCE_CERTIFICADO_AUSENTE');
+    }
+    this.ambiente = options.ambiente ?? 2;
+    this.timeout = options.timeout ?? 30000;
+    this.endpoints = { ...DCE_WEBSERVICES[this.ambiente], ...options.endpoints };
+    this.httpsAgent = criarHttpsAgentSefaz(options.certificado, { ca: options.ca });
+  }
+
+  /**
+   * @param {keyof typeof SERVICOS} servico
+   * @param {string} xmlDados
+   * @param {{ compactar?: boolean }} [options]
+   * @returns {Promise<string>} XML de retorno (conteúdo do elemento *Result)
+   */
+  async #chamar(servico, xmlDados, options = {}) {
+    const { wsdl, metodo } = SERVICOS[servico];
+    const ns = `http://www.portalfiscal.inf.br/dce/wsdl/${wsdl}`;
+    const acao = options.compactar ? `${metodo}Zip` : metodo;
+
+    const corpo = options.compactar
+      ? `<dceDadosMsgZip xmlns="${ns}">${zlib.gzipSync(Buffer.from(semDeclaracao(xmlDados), 'utf8')).toString('base64')}</dceDadosMsgZip>`
+      : `<dceDadosMsg xmlns="${ns}">${semDeclaracao(xmlDados)}</dceDadosMsg>`;
+
+    const envelope =
+      '<?xml version="1.0" encoding="utf-8"?>' +
+      '<soap12:Envelope xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">' +
+      `<soap12:Body>${corpo}</soap12:Body></soap12:Envelope>`;
+
+    let response;
+    try {
+      response = await axios.post(this.endpoints[servico], envelope, {
+        httpsAgent: this.httpsAgent,
+        timeout: this.timeout,
+        responseType: 'text',
+        headers: { 'Content-Type': `application/soap+xml; charset=utf-8; action="${ns}/${acao}"` },
+      });
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        throw new GhinfeError(
+          `Falha na comunicação SOAP (${wsdl}): ${error.message}`,
+          'SEFAZ_HTTP_ERROR',
+          { status: error.response?.status, data: error.response?.data }
+        );
+      }
+      throw error;
+    }
+
+    const conteudo = response.data.match(RESULTADO_SOAP)?.[2];
+    if (!conteudo) {
+      throw new GhinfeError(`Resposta SOAP de ${wsdl} sem elemento de resultado`, 'SEFAZ_RESPOSTA_INVALIDA', {
+        data: response.data,
+      });
+    }
+    return conteudo;
+  }
+
+  /**
+   * Consulta status do serviço (DCeStatusServico).
+   * @param {string} [uf] UF consultada (o autorizador responde por todas)
+   */
+  async consultarStatus(uf = 'PR') {
+    const cUF = UF_IBGE[uf.toUpperCase()];
+    const xml =
+      `<consStatServDCe xmlns="${DCE_NAMESPACE}" versao="${DCE_VERSAO}">` +
+      `<tpAmb>${this.ambiente}</tpAmb><cUF>${cUF}</cUF><xServ>STATUS</xServ></consStatServDCe>`;
+
+    const retorno = await this.#chamar('status', xml);
+    const cStat = tag(retorno, 'cStat');
+    return {
+      emOperacao: cStat === DCE_STATUS.SERVICO_EM_OPERACAO,
+      cStat,
+      xMotivo: tag(retorno, 'xMotivo'),
+      cUF: tag(retorno, 'cUF'),
+      dhRecbto: tag(retorno, 'dhRecbto'),
+      tMed: tag(retorno, 'tMed'),
+      xObs: tag(retorno, 'xObs'),
+      xmlRetorno: retorno,
+    };
+  }
+
+  /**
+   * Envia DC-e assinada para autorização (síncrono). Lança SefazError se não autorizada.
+   * @param {string} xmlAssinado
+   * @param {{ compactar?: boolean }} [options] compactar: usa dceAutorizacaoZip (GZip + Base64)
+   */
+  async autorizar(xmlAssinado, options = {}) {
+    const retorno = await this.#chamar('autorizacao', xmlAssinado, options);
+    const protDCe = grupo(retorno, 'protDCe');
+    const fonte = protDCe ?? retorno;
+    const cStat = tag(fonte, 'cStat');
+    const xMotivo = tag(fonte, 'xMotivo');
+
+    if (cStat !== DCE_STATUS.AUTORIZADO) {
+      throw new SefazError(cStat ?? '999', xMotivo ?? 'Retorno não identificado', {
+        cStatRetorno: tag(retorno, 'cStat'),
+        xmlRetorno: retorno,
+      });
+    }
+
+    return {
+      autorizado: true,
+      cStat,
+      xMotivo,
+      protocolo: tag(protDCe, 'nProt'),
+      chaveAcesso: tag(protDCe, 'chDCe'),
+      dhRecbto: tag(protDCe, 'dhRecbto'),
+      digVal: tag(protDCe, 'digVal'),
+      xmlProtocolo: protDCe,
+      xmlProc: this.montarDCeProc(xmlAssinado, protDCe),
+      xmlRetorno: retorno,
+    };
+  }
+
+  /**
+   * Consulta situação da DC-e (DCeConsulta). Não lança erro para cStat de rejeição.
+   * @param {string} chaveAcesso
+   */
+  async consultar(chaveAcesso) {
+    const xml =
+      `<consSitDCe xmlns="${DCE_NAMESPACE}" versao="${DCE_VERSAO}">` +
+      `<tpAmb>${this.ambiente}</tpAmb><xServ>CONSULTAR</xServ><chDCe>${chaveAcesso}</chDCe></consSitDCe>`;
+
+    const retorno = await this.#chamar('consulta', xml);
+    const protDCe = grupo(retorno, 'protDCe');
+    const cStat = tag(retorno, 'cStat');
+
+    return {
+      cStat,
+      xMotivo: tag(retorno, 'xMotivo'),
+      autorizada: cStat === DCE_STATUS.AUTORIZADO,
+      cancelada: cStat === DCE_STATUS.CANCELADO,
+      protocolo: tag(protDCe, 'nProt'),
+      xmlProtocolo: protDCe,
+      eventos: [...retorno.matchAll(/<procEventoDCe[\s>][\s\S]*?<\/procEventoDCe>/g)].map((m) => m[0]),
+      xmlRetorno: retorno,
+    };
+  }
+
+  /**
+   * Envia evento assinado (DCeRecepcaoEvento). Lança SefazError se não registrado.
+   * @param {string} xmlEventoAssinado
+   */
+  async enviarEvento(xmlEventoAssinado) {
+    const retorno = await this.#chamar('evento', xmlEventoAssinado);
+    const infEvento = grupo(retorno, 'infEvento') ?? retorno;
+    const cStat = tag(infEvento, 'cStat');
+    const xMotivo = tag(infEvento, 'xMotivo');
+    const sucesso = [
+      DCE_STATUS.EVENTO_REGISTRADO,
+      DCE_STATUS.EVENTO_REGISTRADO_SEM_VINCULO,
+      DCE_STATUS.CANCELAMENTO_FORA_PRAZO,
+    ];
+
+    if (!sucesso.includes(cStat)) {
+      throw new SefazError(cStat ?? '999', xMotivo ?? 'Retorno não identificado', { xmlRetorno: retorno });
+    }
+
+    const retEvento = grupo(retorno, 'retEventoDCe');
+    return {
+      registrado: true,
+      cStat,
+      xMotivo,
+      protocolo: tag(infEvento, 'nProt'),
+      tpEvento: tag(infEvento, 'tpEvento'),
+      dhRegEvento: tag(infEvento, 'dhRegEvento'),
+      xmlRetorno: retorno,
+      xmlProc: retEvento
+        ? `<?xml version="1.0" encoding="UTF-8"?><procEventoDCe xmlns="${DCE_NAMESPACE}" versao="${DCE_VERSAO}">` +
+          `${semDeclaracao(xmlEventoAssinado)}${retEvento}</procEventoDCe>`
+        : undefined,
+    };
+  }
+
+  /**
+   * Monta dceProc (DC-e assinada + protocolo de autorização) para armazenamento.
+   * @param {string} xmlAssinado
+   * @param {string} protDCe
+   */
+  montarDCeProc(xmlAssinado, protDCe) {
+    // A SEFA-PR devolve protDCe sem o atributo versao, obrigatório em procDCe_v1.00.xsd
+    const prot = /^<protDCe[^>]*\sversao=/.test(protDCe)
+      ? protDCe
+      : protDCe.replace(/^<protDCe/, `<protDCe versao="${DCE_VERSAO}"`);
+
+    return (
+      `<?xml version="1.0" encoding="UTF-8"?><dceProc xmlns="${DCE_NAMESPACE}" versao="${DCE_VERSAO}">` +
+      `${semDeclaracao(xmlAssinado)}${prot}</dceProc>`
+    );
+  }
+}

package/src/dce/services/DCeXmlService.js

@@ -0,0 +1,67 @@
+import { DCeXmlBuilder } from '../builders/DCeXmlBuilder.js';
+import { XsdValidator } from '../../validation/XsdValidator.js';
+import { XSD_SCHEMAS } from '../../validation/schemas.js';
+
+/**
+ * Serviço de geração e validação XSD da DC-e.
+ */
+export class DCeXmlService {
+  /**
+   * @param {{ validarXsd?: boolean }} [options]
+   */
+  constructor(options = {}) {
+    this.builder = new DCeXmlBuilder();
+    this.validarXsd = options.validarXsd ?? false;
+  }
+
+  /**
+   * @param {import('../types/DCeDocument.js').DCeDocumento} documento
+   * @param {{ validarXsd?: boolean, qrCode?: string, urlChave?: string, sign?: string, qrCodeBaseUrl?: string }} [options]
+   */
+  gerarXml(documento, options = {}) {
+    const { validarXsd, ...buildOptions } = options;
+    const xml = this.builder.build(documento, buildOptions);
+
+    if (validarXsd ?? this.validarXsd) {
+      this.validarXml(xml);
+    }
+
+    return xml;
+  }
+
+  /**
+   * Valida contra dce_v1.00.xsd. XML sem assinatura recebe Signature stub.
+   * @param {string} xml
+   */
+  validarXml(xml) {
+    return XsdValidator.validar(xml, XSD_SCHEMAS.DCE, {
+      injetarAssinaturaStub: !xml.includes('</Signature>'),
+      modelo: '99',
+    });
+  }
+
+  /**
+   * Valida evento assinado (eventoDCe) e o detalhe do cancelamento (evCancDCe).
+   * @param {string} xmlEventoAssinado
+   */
+  validarEvento(xmlEventoAssinado) {
+    XsdValidator.validar(xmlEventoAssinado, XSD_SCHEMAS.DCE_EVENTO);
+
+    const detalhe = xmlEventoAssinado.match(/<evCancDCe>[\s\S]*?<\/evCancDCe>/)?.[0];
+    if (detalhe) {
+      XsdValidator.validar(
+        detalhe.replace('<evCancDCe>', '<evCancDCe xmlns="http://www.portalfiscal.inf.br/dce">'),
+        XSD_SCHEMAS.DCE_EVENTO_CANCELAMENTO
+      );
+    }
+    return { valido: true, avisos: [] };
+  }
+
+  /** @param {string} xml */
+  tentarValidar(xml) {
+    return XsdValidator.tentarValidar(xml, XSD_SCHEMAS.DCE, {
+      injetarAssinaturaStub: !xml.includes('</Signature>'),
+      modelo: '99',
+    });
+  }
+}

package/src/dce/types/DCeDocument.js

@@ -0,0 +1,106 @@
+/**
+ * @typedef {Object} DCeEndereco
+ * @property {string} logradouro
+ * @property {string} numero
+ * @property {string} [complemento]
+ * @property {string} bairro
+ * @property {string} codigoMunicipio IBGE 7 dígitos
+ * @property {string} municipio
+ * @property {string} uf
+ * @property {string} cep
+ * @property {string} [codigoPais] Padrão 1058 (Brasil)
+ * @property {string} [pais] Padrão "BRASIL"
+ * @property {string} [telefone]
+ * @property {string} [email] Somente destinatário
+ */
+
+/**
+ * Usuário emitente (quem remete o bem). Informe apenas um entre cnpj, cpf e idOutros.
+ * @typedef {Object} DCeParte
+ * @property {string} [cnpj]
+ * @property {string} [cpf]
+ * @property {string} [idOutros] Estrangeiro, indígena, quilombola etc.
+ * @property {string} razaoSocial
+ * @property {DCeEndereco} endereco
+ */
+
+/**
+ * @typedef {Object} DCeFisco
+ * @property {string} cnpj
+ * @property {string} orgao
+ * @property {string} uf
+ */
+
+/**
+ * @typedef {Object} DCeMarketplace
+ * @property {string} cnpj
+ * @property {string} razaoSocial
+ * @property {string} site
+ */
+
+/**
+ * Transportadora ou ECT (Correios) emitente da DC-e.
+ * @typedef {Object} DCeEmpresaEmissora
+ * @property {string} cnpj
+ * @property {string} razaoSocial
+ */
+
+/**
+ * @typedef {Object} DCeItem
+ * @property {string} descricao
+ * @property {string} ncm Capítulo (2 dígitos) ou NCM completo (8). "00000000" se não classificável
+ * @property {number} quantidade
+ * @property {number} valorUnitario
+ * @property {number} [valorTotal] Calculado (quantidade × valorUnitario) se omitido
+ * @property {string} [informacoesAdicionais]
+ */
+
+/**
+ * @typedef {Object} DCeObservacao
+ * @property {string} campo Até 20 caracteres
+ * @property {string} texto Até 60 caracteres
+ */
+
+/**
+ * @typedef {Object} DCeInformacoesAdicionais
+ * @property {string} [fisco]
+ * @property {string} [complementares]
+ * @property {string} [marketplace]
+ * @property {string} [ect]
+ * @property {DCeObservacao[]} [obsEmitente]
+ * @property {DCeObservacao[]} [obsFisco]
+ * @property {DCeObservacao[]} [obsMarketplace] Também usado por transportadoras
+ * @property {DCeObservacao[]} [obsECT]
+ */
+
+/**
+ * @typedef {Object} DCeIde
+ * @property {string} uf UF do usuário emitente
+ * @property {number} [serie] 0 a 999 (padrão 1)
+ * @property {number} numero 1 a 999999999
+ * @property {number} tipoEmitente 0=Fisco, 1=Marketplace, 2=Emissor próprio, 3=Transportadora, 4=ECT
+ * @property {number} [tipoEmissao] 1=Normal, 2=Contingência off-line
+ * @property {number} [siteAutorizador] 0 quando o autorizador tem site único
+ * @property {string} [codigoNumerico] cDC (6 dígitos) — gerado se omitido
+ * @property {Date} [dataEmissao]
+ */
+
+/**
+ * @typedef {Object} DCeDocumento
+ * @property {string} [chaveAcesso] 44 dígitos — gerada automaticamente se omitida
+ * @property {number} [ambiente] 1=Produção, 2=Homologação
+ * @property {DCeIde} ide
+ * @property {DCeParte} emitente
+ * @property {DCeFisco} [fisco] Obrigatório se tipoEmitente=0
+ * @property {DCeMarketplace} [marketplace] Obrigatório se tipoEmitente=1
+ * @property {DCeEmpresaEmissora} [transportadora] Obrigatório se tipoEmitente=3
+ * @property {DCeEmpresaEmissora} [ect] Obrigatório se tipoEmitente=4
+ * @property {DCeParte} destinatario
+ * @property {Array<{ cnpj?: string, cpf?: string }>} [autorizadosXml] Até 10
+ * @property {DCeItem[]} itens
+ * @property {{ modalidade: number, cnpjTransportadora?: string }} transporte 0=Correios, 1=Próprio, 2=Transportadora
+ * @property {DCeInformacoesAdicionais} [informacoesAdicionais]
+ * @property {string} [solicitacaoFisco] JSON do pedido no app do Fisco (somente tipoEmitente=0)
+ */
+
+export {};