@sinete/nfe 0.0.0 → 0.1.0

package/src/services/gzip.ts

@@ -0,0 +1,26 @@
+/**
+ * Descompressão do `docZip` da Distribuição DF-e (gzip em base64, NT 2014.002). Usa o `DecompressionStream` da
+ * plataforma (Node 18+, Bun, Deno e browsers), sem dependência.
+ */
+
+import { ProtocolError, UnsupportedError } from '@sinete/core';
+import { base64Decode } from '@sinete/core/xml';
+
+/** Base64 de um gzip para o texto UTF-8 de dentro. */
+export async function gunzipBase64(b64: string): Promise<string> {
+  const Ds = (globalThis as { DecompressionStream?: typeof DecompressionStream }).DecompressionStream;
+  if (Ds === undefined)
+    throw new UnsupportedError('DecompressionStream indisponível nesta runtime; docZip não pode ser lido');
+  let bytes: Uint8Array<ArrayBuffer>;
+  try {
+    bytes = base64Decode(b64.trim());
+  } catch (cause) {
+    throw new ProtocolError('docZip com base64 inválido', { cause });
+  }
+  try {
+    const stream = new Blob([bytes]).stream().pipeThrough(new Ds('gzip'));
+    return await new Response(stream).text();
+  } catch (cause) {
+    throw new ProtocolError('docZip não é um gzip válido', { cause });
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Serviços da NF-e (webservices 4.00 da SEFAZ e do Ambiente Nacional). Veja `client.ts` para o contrato de cada
+ * operação e `resolver.ts` para a regra de idempotência da autorização.
+ */
+
+export type {
+  AutorDocumento,
+  AutorizacaoOutcome,
+  AutorizarOpcoes,
+  Cadastro,
+  CadastroPedido,
+  CancelamentoPedido,
+  CancelamentoSubstituicaoPedido,
+  CartaCorrecaoPedido,
+  ConsultaNfe,
+  ConsultaOutcome,
+  ConsultaReciboOpcoes,
+  Distribuicao,
+  DistribuicaoConsulta,
+  DistribuicaoOpcoes,
+  DocumentoDistribuido,
+  EventoOutcome,
+  EventoRegistrado,
+  Inutilizacao,
+  InutilizacaoOutcome,
+  InutilizacaoPedido,
+  ManifestacaoPedido,
+  ManifestacaoTipo,
+  NfeClient,
+  NfeClientOptions,
+  PoliticaRecibo,
+  ProtocoloNfe,
+  Sleep,
+  StatusServico,
+} from './client.ts';
+export { autorizadorContingencia, createNfeClient } from './client.ts';
+export { gunzipBase64 } from './gzip.ts';
+export type { DocumentoAssinado } from './proc.ts';
+export { documentoAssinado, nfeAssinadaDoProc, sliceElement } from './proc.ts';
+export type { RecuperacaoEvento } from './recuperar.ts';
+export { recuperarEventoRegistrado } from './recuperar.ts';
+export type { ConteudoDoProtocolo, ResolucaoEnvio } from './resolver.ts';
+export { chaveDaDuplicidade, resolverEnvioSemResposta } from './resolver.ts';

package/src/services/outcome.ts

@@ -0,0 +1,50 @@
+/**
+ * Desfechos da SEFAZ a partir da tabela versionada de `cStat` (`data/cstat.json`, MOC 7.0 Anexo I, tabela 4.4.1).
+ * Nenhuma lista de códigos fica no código: quem decide se um `cStat` é autorização, denegação ou pendência é o dado.
+ */
+
+import type { Rejected, RejectionHint, SefazStatus } from '@sinete/core';
+import { rejected } from '@sinete/core';
+import { enrichRejected } from '@sinete/rejeicoes';
+import table from '../data/cstat.json' with { type: 'json' };
+
+/** Classes de `cStat` que a tabela descreve. */
+export type CStatClasse =
+  | 'autorizada'
+  | 'denegada'
+  | 'cancelada'
+  | 'loteRecebido'
+  | 'loteProcessado'
+  | 'loteEmProcessamento'
+  | 'loteNaoLocalizado'
+  | 'servicoEmOperacao'
+  | 'inutilizacaoHomologada'
+  | 'eventoRegistrado'
+  | 'loteEventoProcessado'
+  | 'cadastroEncontrado'
+  | 'distribuicaoNenhumDocumento'
+  | 'distribuicaoDocumentos'
+  | 'duplicidade'
+  | 'duplicidadeChaveDiferente'
+  | 'naoConsta'
+  | 'outraNfeNoNumero'
+  | 'consumoIndevido';
+
+const CLASSES: Readonly<Record<CStatClasse, readonly string[]>> = table;
+const DICAS: Readonly<Record<string, RejectionHint>> = table.dicas;
+
+/** O `cStat` pertence à classe da tabela. */
+export function cstatEm(cStat: string, classe: CStatClasse): boolean {
+  return CLASSES[classe].includes(cStat);
+}
+
+/**
+ * Desfecho `rejected` enriquecido pelo `@sinete/rejeicoes`; sem curadoria lá, usa a dica própria do `@sinete/nfe`
+ * (`dicas` em `data/cstat.json`) quando houver.
+ */
+export function rejeitado(status: SefazStatus): Rejected {
+  const r = enrichRejected(rejected(status));
+  if (r.hint !== undefined) return r;
+  const dica = Object.hasOwn(DICAS, status.cStat) ? DICAS[status.cStat] : undefined;
+  return dica === undefined ? r : rejected(status, dica);
+}

package/src/services/proc.ts

@@ -0,0 +1,164 @@
+/**
+ * Montagem dos documentos processados (`nfeProc`, `procEventoNFe`, `ProcInutNFe`) por splice de texto. O documento
+ * assinado entra byte a byte como foi assinado e o protocolo entra como fatia da resposta recebida: nada é reparseado
+ * para gerar saída nem reserializado (invariante do repositório, ADR 0003).
+ */
+
+import { ConfigError, ProtocolError } from '@sinete/core';
+import type { XmlDocument, XmlElement } from '@sinete/core/xml';
+import {
+  attributeOf,
+  descendants,
+  firstChild,
+  inScopeNamespaces,
+  parseXml,
+  textOf,
+  XMLDSIG_NS,
+} from '@sinete/core/xml';
+
+/** Namespace dos documentos da NF-e. */
+export const NFE_NS = 'http://www.portalfiscal.inf.br/nfe';
+
+const XML_DECL = /^?<\?xml[^?]*\?>\s*/;
+
+/**
+ * Recorta o elemento da fonte, acrescentando na tag de abertura só as declarações de namespace que ele usa e que
+ * estão em ancestrais fora do recorte. O default entra apenas quando difere de `parentDefaultNs` (o default do
+ * envelope onde a fatia vai morar).
+ */
+export function sliceElement(doc: XmlDocument, el: XmlElement, parentDefaultNs: string = NFE_NS): string {
+  const slice = doc.source.slice(el.start, el.end);
+  // Só os prefixos usados por algum elemento ou atributo cuja declaração está fora do recorte: um prefixo redeclarado
+  // dentro dele não pode ganhar outra declaração na raiz, que mudaria o C14N inclusivo de um irmão assinado.
+  //
+  // Declaração herdada e não usada (xmlns:soap, xmlns:xsi, xmlns:xsd do envelope da resposta) fica de fora de
+  // propósito. O que a fatia leva é o contexto em que o autorizador montou o documento, não o do transporte: o
+  // protocolo vai para o proc como o leiaute pede, e é assim que o proc confere depois. Copiar para a fatia todo
+  // namespace em escopo mudaria o C14N inclusivo do documento assinado pelo emitente, que nunca viu o envelope.
+  const used = new Set<string>();
+  const cobertoDentro = (d: XmlElement, p: string): boolean => {
+    for (let e: XmlElement | null = d; e; e = e === el ? null : e.parent) if (e.namespaces.has(p)) return true;
+    return false;
+  };
+  for (const d of descendants(el)) {
+    const prefixos = [d.prefix, ...d.attributes.map((a) => a.prefix)].filter((p) => p !== '' && p !== 'xml');
+    for (const p of prefixos) if (!cobertoDentro(d, p)) used.add(p);
+  }
+  const extra: string[] = [];
+  const inScope = new Map<string, string>();
+  for (let e: XmlElement | null = el.parent; e; e = e.parent) {
+    for (const [p, u] of e.namespaces) if (!inScope.has(p)) inScope.set(p, u);
+  }
+  // O default herdado de fora entra quando algum elemento sem prefixo do recorte (a raiz ou um descendente, inclusive
+  // sob uma raiz prefixada) depende dele e ele difere do default do envelope de destino.
+  const herdado = inScope.get('') ?? '';
+  if (herdado !== parentDefaultNs && usaDefaultHerdado(el)) extra.push(` xmlns="${herdado}"`);
+  for (const p of [...used].sort()) {
+    const uri = inScope.get(p);
+    if (uri === undefined) throw new ProtocolError(`prefixo ${p} sem declaração no recorte de ${el.name}`);
+    extra.push(` xmlns:${p}="${uri}"`);
+  }
+  if (extra.length === 0) return slice;
+  const at = 1 + el.name.length;
+  return slice.slice(0, at) + extra.join('') + slice.slice(at);
+}
+
+/** Algum elemento sem prefixo do recorte resolve o default por uma declaração de fora do recorte. */
+function usaDefaultHerdado(raiz: XmlElement): boolean {
+  for (const d of descendants(raiz)) {
+    if (d.prefix !== '') continue;
+    let coberto = false;
+    for (let e: XmlElement | null = d; e; e = e === raiz ? null : e.parent) {
+      if (e.namespaces.has('')) {
+        coberto = true;
+        break;
+      }
+    }
+    if (!coberto) return true;
+  }
+  return false;
+}
+
+/** Documento assinado já conferido: a string como veio (sem a declaração XML) e o que se lê dela. */
+export interface DocumentoAssinado {
+  /** O texto que vai no envelope, byte a byte o assinado (só a declaração XML inicial removida). */
+  readonly xml: string;
+  /** `Id` do elemento assinado (`NFe3526...`, `ID110111...`). */
+  readonly id: string;
+  /** DigestValue da assinatura (base64). */
+  readonly digestValue: string;
+  readonly doc: XmlDocument;
+}
+
+/**
+ * Confere que `xml` é um documento `raiz` assinado (no namespace da NF-e, com `Signature` referenciando o filho
+ * `elemento`) e devolve a string sem a declaração XML. Lança `ConfigError` para qualquer outra coisa: o serviço nunca
+ * "conserta" o documento de quem chama.
+ */
+export function documentoAssinado(xml: string, raiz: string, elemento: string): DocumentoAssinado {
+  const text = xml.replace(XML_DECL, '');
+  let doc: XmlDocument;
+  try {
+    doc = parseXml(text);
+  } catch (cause) {
+    throw new ConfigError(`${raiz} assinado malformado`, { cause });
+  }
+  if (doc.root.local !== raiz || doc.root.ns !== NFE_NS) {
+    throw new ConfigError(`esperado <${raiz}> no namespace da NF-e, veio <${doc.root.name}>`);
+  }
+  // O envelope (nfeProc, procEventoNFe) declara o default da NF-e; o C14N inclusivo herda os namespaces dos
+  // ancestrais, então a raiz assinada precisa declarar ela mesma esse default, ou a assinatura deixa de conferir
+  // dentro do envelope. Não se conserta o documento de quem chama: recusa.
+  if (doc.root.namespaces.get('') !== NFE_NS) {
+    throw new ConfigError(`<${raiz}> assinado precisa declarar xmlns="${NFE_NS}" na própria raiz`);
+  }
+  const alvo = firstChild(doc.root, elemento, NFE_NS);
+  const id = alvo ? attributeOf(alvo, 'Id') : undefined;
+  const sig = firstChild(doc.root, 'Signature', XMLDSIG_NS);
+  const digest = sig && descendantText(sig, 'DigestValue');
+  if (!id || digest === undefined) throw new ConfigError(`${raiz} sem ${elemento} identificado ou sem assinatura`);
+  return { xml: text, id, digestValue: digest, doc };
+}
+
+function descendantText(el: XmlElement, local: string): string | undefined {
+  for (const d of descendants(el)) if (d.local === local && d.ns === XMLDSIG_NS) return textOf(d).trim();
+  return undefined;
+}
+
+/**
+ * NF-e assinada de dentro de um `nfeProc` (ou a própria NF-e assinada), como fatia do texto e sem a declaração XML,
+ * pronta para `consultar`, `resolverEnvioSemResposta` e a retomada, que recusam raiz sem `xmlns` próprio. O `NFe` dentro
+ * do proc herda os namespaces do envelope; eles são declarados na raiz da fatia. O C14N inclusivo do `infNFe` já os
+ * enxergava em escopo, então o digest e a assinatura são os mesmos dentro e fora do proc. Nada mais muda nos bytes.
+ * Lança `ConfigError` quando não há NF-e assinada (proc de outro documento, NFe sem assinatura, XML malformado).
+ */
+export function nfeAssinadaDoProc(xml: string): string {
+  const text = xml.replace(XML_DECL, '');
+  let doc: XmlDocument;
+  try {
+    doc = parseXml(text);
+  } catch (cause) {
+    throw new ConfigError('nfeProc malformado', { cause });
+  }
+  const noProc =
+    doc.root.local === 'nfeProc' && doc.root.ns === NFE_NS ? firstChild(doc.root, 'NFe', NFE_NS) : undefined;
+  const el = noProc ?? (doc.root.local === 'NFe' && doc.root.ns === NFE_NS ? doc.root : undefined);
+  if (el === undefined) throw new ConfigError(`esperado <nfeProc> ou <NFe> assinada, veio <${doc.root.name}>`);
+  const fatia = doc.source.slice(el.start, el.end);
+  const herdados = [...inScopeNamespaces(el)].filter(([p]) => p !== 'xml' && !el.namespaces.has(p));
+  const decl = herdados
+    .map(
+      ([p, uri]) =>
+        ` ${p === '' ? 'xmlns' : `xmlns:${p}`}="${uri.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;')}"`,
+    )
+    .join('');
+  const at = 1 + el.name.length;
+  const assinado = decl === '' ? fatia : fatia.slice(0, at) + decl + fatia.slice(at);
+  // Confere raiz, Id e assinatura como a retomada vai conferir: o que sai daqui serve direto nela.
+  return documentoAssinado(assinado, 'NFe', 'infNFe').xml;
+}
+
+/** `<raiz xmlns versao>` + partes + `</raiz>`, sem tocar nas partes. */
+export function envelope(raiz: string, versao: string, partes: readonly string[]): string {
+  return `<${raiz} xmlns="${NFE_NS}" versao="${versao}">${partes.join('')}</${raiz}>`;
+}

package/src/services/recuperar.ts

@@ -0,0 +1,91 @@
+/**
+ * Recuperação de um evento que a SEFAZ registrou e cuja resposta se perdeu.
+ *
+ * Um pedido de evento sem resposta (timeout, conexão caída), ou respondido com 573 (duplicidade de evento) ou 580
+ * (evento já registrado no contexto do cancelamento), pode ter sido registrado. O `cStat` sozinho não prova: 573 e
+ * 580 dizem que algo foi registrado antes, não que foi este evento, com este conteúdo e para esta chave. A prova é a
+ * consulta da chave, que devolve os `procEventoNFe` que a SEFAZ tem (MOC 7.0, Visão Geral, consulta protocolo). Esta
+ * função lê o evento de lá e só o dá como registrado quando o retorno dele diz 135, 136 ou 155 para a mesma chave e o
+ * mesmo tipo.
+ */
+
+import type { XmlDocument, XmlElement } from '@sinete/core/xml';
+import { firstChild, parseXml, textOf } from '@sinete/core/xml';
+import type { ConsultaOutcome, EventoRegistrado, NfeClient } from './client.ts';
+import { cstatEm } from './outcome.ts';
+import { NFE_NS, sliceElement } from './proc.ts';
+
+/** Resultado da recuperação: o evento registrado, com a consulta que o prova, ou só a consulta. */
+export type RecuperacaoEvento =
+  | { readonly registrado: true; readonly evento: EventoRegistrado; readonly consulta: ConsultaOutcome }
+  | { readonly registrado: false; readonly consulta: ConsultaOutcome };
+
+/** Texto do filho `local` no namespace da NF-e, se houver. */
+function campo(el: XmlElement, local: string): string | undefined {
+  const c = firstChild(el, local, NFE_NS);
+  return c === undefined ? undefined : textOf(c).trim();
+}
+
+/** Lê um `procEventoNFe` da consulta; `undefined` para o que não é um evento com retorno legível. */
+function lerProcEvento(xml: string): EventoRegistrado | undefined {
+  let doc: XmlDocument;
+  try {
+    doc = parseXml(xml);
+  } catch {
+    return undefined;
+  }
+  const evento = firstChild(doc.root, 'evento', NFE_NS);
+  const pedido = evento === undefined ? undefined : firstChild(evento, 'infEvento', NFE_NS);
+  const retEl = firstChild(doc.root, 'retEvento', NFE_NS);
+  const ret = retEl === undefined ? undefined : firstChild(retEl, 'infEvento', NFE_NS);
+  if (doc.root.local !== 'procEventoNFe' || pedido === undefined || retEl === undefined || ret === undefined) {
+    return undefined;
+  }
+  const cStat = campo(ret, 'cStat');
+  const chNFe = campo(ret, 'chNFe');
+  const tpEvento = campo(ret, 'tpEvento');
+  const nSeq = campo(ret, 'nSeqEvento');
+  const dhRegEvento = campo(ret, 'dhRegEvento');
+  if (cStat === undefined || !cstatEm(cStat, 'eventoRegistrado')) return undefined;
+  // O pedido e o retorno têm de falar do mesmo evento.
+  // Chave, tipo e sequência têm de vir no retorno e ser iguais aos do pedido: um retorno registrado de outro evento, ou
+  // sem dizer de qual, não prova nada.
+  if (chNFe === undefined || tpEvento === undefined || nSeq === undefined) return undefined;
+  const nSeqPedido = campo(pedido, 'nSeqEvento');
+  if (campo(pedido, 'chNFe') !== chNFe || campo(pedido, 'tpEvento') !== tpEvento) return undefined;
+  if (nSeqPedido === undefined || Number(nSeqPedido) !== Number(nSeq)) return undefined;
+  if (chNFe === undefined || tpEvento === undefined || nSeq === undefined || dhRegEvento === undefined)
+    return undefined;
+  const nProt = campo(ret, 'nProt');
+  return {
+    chNFe,
+    tpEvento,
+    nSeqEvento: String(Number(nSeq)),
+    dhRegEvento,
+    retEvento: sliceElement(doc, retEl, ''),
+    procEventoNFe: xml,
+    ...(nProt === undefined ? {} : { nProt }),
+  };
+}
+
+/**
+ * Consulta a chave e devolve o evento `tpEvento` que a SEFAZ registrou para ela (o de maior `nSeqEvento`, quando há
+ * vários, como na CC-e). Serve depois de um pedido de evento sem resposta ou respondido com 573 ou 580: nunca conclua
+ * que o evento existe só pelo `cStat` do pedido. `registrado: false` quer dizer que a consulta não mostrou o evento
+ * (ou não decidiu: veja `consulta`); não quer dizer que o evento não existe.
+ */
+export async function recuperarEventoRegistrado(
+  client: NfeClient,
+  chave: string,
+  tpEvento: string,
+): Promise<RecuperacaoEvento> {
+  const consulta = await client.consultar(chave);
+  if (consulta.status !== 'authorized' && consulta.status !== 'denied') return { registrado: false, consulta };
+  let achado: EventoRegistrado | undefined;
+  for (const xml of consulta.value.eventos) {
+    const e = lerProcEvento(xml);
+    if (e === undefined || e.chNFe !== consulta.value.chNFe || e.tpEvento !== tpEvento) continue;
+    if (achado === undefined || Number(e.nSeqEvento) > Number(achado.nSeqEvento)) achado = e;
+  }
+  return achado === undefined ? { registrado: false, consulta } : { registrado: true, evento: achado, consulta };
+}

package/src/services/resolver.ts

@@ -0,0 +1,127 @@
+/**
+ * Envio sem resposta e duplicidade na autorização.
+ *
+ * Idempotência: a chave de acesso contém o `cNF` e o número da nota, e o `digVal` do protocolo é o DigestValue do
+ * conteúdo autorizado. Enquanto o mesmo XML assinado (os mesmos bytes) for reenviado, a SEFAZ ou autoriza, ou devolve
+ * duplicidade (204) com o protocolo existente. Gerar outro `cNF`, outro `dhEmi` ou reassinar depois de um envio sem
+ * resposta cria uma segunda nota para o mesmo número: a primeira pode ter sido autorizada, e a segunda cai em 539
+ * (duplicidade com diferença na chave) ou, pior, é autorizada com outra chave se o número mudar. Por isso:
+ *
+ * 1. grave o XML assinado antes de enviar;
+ * 2. envio sem resposta (timeout, conexão caída) ou 204: consulte a chave (`resolverEnvioSemResposta`);
+ * 3. `reenviar` (cStat 217, a NF-e não consta): reenvie exatamente os bytes gravados;
+ * 4. `concluida`: o `nfeProc` vem montado com o XML gravado, sem novo envio.
+ *
+ * O `digVal` é opcional no protocolo (`TProtNFe/infProt/digVal`, minOccurs 0 no `leiauteNFe_v4.00.xsd` do PL_010), e
+ * há autorizador que o omite. Sem ele, nada prova que o conteúdo registrado é o destes bytes, e as duas decisões se
+ * separam:
+ *
+ * - denegação (110, 301, 302, 303; MOC 7.0 Anexo I, tabela 4.4.3 e regras 1C17-40, 5E17-40 e 5E17-60) é decisão
+ *   sobre a chave: a NF-e fica registrada como denegada e o número não pode ser reaproveitado nem inutilizado, qualquer
+ *   que seja o conteúdo. A resolução é `concluida` com o protocolo, e `conteudo` diz se o `digVal` confere, falta ou
+ *   difere; o `nfeProc` só vem quando confere;
+ * - autorização sem `digVal` não prova que a NF-e autorizada é esta: `sem-prova`, e quem chama decide com um humano.
+ *
+ * Fontes: MOC 7.0 Anexo I (RV 204 "Duplicidade de NF-e", RV 539 "Duplicidade de NF-e com diferença na Chave de
+ * Acesso [chNFe: ...]") e serviço de consulta protocolo (cStat 217; 561, 562 e 613 quando a numeração tem outra NF-e).
+ */
+
+import type { Rejected } from '@sinete/core';
+import { authorized, denied } from '@sinete/core';
+import type { AutorizacaoOutcome, ConsultaOutcome, NfeClient, ProtocoloNfe } from './client.ts';
+import { cstatEm } from './outcome.ts';
+import { documentoAssinado } from './proc.ts';
+
+/**
+ * O que o `digVal` do protocolo diz dos bytes assinados: `confere` (é o DigestValue deles), `sem-digval` (o protocolo
+ * não o traz) ou `difere` (a SEFAZ registrou outro conteúdo com a mesma chave).
+ */
+export type ConteudoDoProtocolo = 'confere' | 'sem-digval' | 'difere';
+
+/** O que fazer com uma NF-e cujo envio ficou sem resposta ou voltou como duplicidade. */
+export type ResolucaoEnvio =
+  /**
+   * A chave está decidida: autorizada (ou cancelada) com o mesmo conteúdo, e `outcome` traz o protocolo e o `nfeProc`;
+   * ou denegada, com qualquer conteúdo (a denegação é da chave), e `outcome` traz o protocolo, com o `nfeProc` só
+   * quando `conteudo` é `confere`.
+   */
+  | {
+      readonly acao: 'concluida';
+      readonly situacao: 'autorizada' | 'cancelada' | 'denegada';
+      readonly conteudo: ConteudoDoProtocolo;
+      readonly outcome: AutorizacaoOutcome;
+    }
+  /** A NF-e não consta na SEFAZ (217): reenvie `nfeAssinada`, os mesmos bytes. */
+  | { readonly acao: 'reenviar'; readonly nfeAssinada: string }
+  /**
+   * Existe outra NF-e para o mesmo número: a mesma chave com outro conteúdo (`digVal` diferente) ou outra chave (539 no
+   * envio, ou 561, 562 e 613 na consulta; `chNFe` extraída do `xMotivo` quando vier). Não reenvie: recupere a nota registrada e descarte a local.
+   */
+  | {
+      readonly acao: 'divergente';
+      readonly chNFe?: string;
+      readonly consulta?: ConsultaOutcome;
+      readonly motivo: Rejected | ConsultaOutcome;
+    }
+  /**
+   * A chave está autorizada (ou cancelada), mas o protocolo não traz `digVal`: nada prova que o conteúdo autorizado é o
+   * destes bytes. Não reenvie nem descarte a nota local, e não a guarde como autorizada sem conferir o XML registrado
+   * na SEFAZ (a Distribuição DF-e ou o portal devolvem a NF-e autorizada).
+   */
+  | { readonly acao: 'sem-prova'; readonly situacao: 'autorizada' | 'cancelada'; readonly consulta: ConsultaOutcome }
+  /**
+   * A consulta não decidiu (serviço paralisado, consumo indevido, rejeição de schema, situação sem protocolo): tente de
+   * novo mais tarde, sem descartar a nota local.
+   */
+  | { readonly acao: 'indefinida'; readonly outcome: ConsultaOutcome };
+
+/** Chave com CNPJ alfanumérico (NT 2025.001): 6 dígitos, 12 alfanuméricos, 26 dígitos. */
+const CHAVE_NO_MOTIVO = /\[\s*chNFe\s*:\s*([0-9]{6}[0-9A-Z]{12}[0-9]{26})\s*\]/i;
+
+/** Chave de acesso que a SEFAZ informa no `xMotivo` da rejeição 539 (`[chNFe:...]`), se houver. */
+export function chaveDaDuplicidade(xMotivo: string): string | undefined {
+  return CHAVE_NO_MOTIVO.exec(xMotivo)?.[1]?.toUpperCase();
+}
+
+/**
+ * Resolve um envio de autorização sem resposta, ou cuja resposta foi 204 ou 539, consultando a chave da NF-e
+ * assinada. `anterior` é o desfecho do envio, quando houve um.
+ */
+export async function resolverEnvioSemResposta(
+  client: NfeClient,
+  nfeAssinada: string,
+  anterior?: AutorizacaoOutcome,
+): Promise<ResolucaoEnvio> {
+  const a = documentoAssinado(nfeAssinada, 'NFe', 'infNFe');
+  const chave = a.id.slice(3);
+  if (anterior && anterior.status === 'rejected' && cstatEm(anterior.cStat, 'duplicidadeChaveDiferente')) {
+    const outra = chaveDaDuplicidade(anterior.xMotivo);
+    return { acao: 'divergente', motivo: anterior, ...(outra === undefined ? {} : { chNFe: outra }) };
+  }
+  const consulta = await client.consultar(chave, nfeAssinada);
+  if (consulta.status === 'rejected') {
+    if (cstatEm(consulta.cStat, 'naoConsta')) return { acao: 'reenviar', nfeAssinada: a.xml };
+    // 561, 562 e 613 na consulta: a chave local não consta, mas a numeração dela tem outra NF-e (outro mês, outro cNF
+    // ou outra chave). É a mesma situação da 539 no envio; o 562 traz a chave registrada no xMotivo.
+    if (cstatEm(consulta.cStat, 'outraNfeNoNumero')) {
+      const outra = chaveDaDuplicidade(consulta.xMotivo);
+      return { acao: 'divergente', motivo: consulta, ...(outra === undefined ? {} : { chNFe: outra }) };
+    }
+    return { acao: 'indefinida', outcome: consulta };
+  }
+  if (consulta.status === 'pending') return { acao: 'indefinida', outcome: consulta };
+  const v = consulta.value;
+  const p: ProtocoloNfe | undefined = v.protocolo;
+  if (!p) return { acao: 'indefinida', outcome: consulta };
+  const conteudo: ConteudoDoProtocolo =
+    p.digVal === undefined ? 'sem-digval' : v.digValConfere === true ? 'confere' : 'difere';
+  const protStatus = { cStat: p.cStat, xMotivo: p.xMotivo };
+  // A denegação é da chave: o número está denegado com qualquer conteúdo, e o `conteudo` diz se é o destes bytes.
+  if (v.situacao === 'denegada')
+    return { acao: 'concluida', situacao: 'denegada', conteudo, outcome: denied(protStatus, p) };
+  // Só um digVal presente e diferente prova outro conteúdo para a chave.
+  if (conteudo === 'difere') return { acao: 'divergente', chNFe: chave, consulta, motivo: consulta };
+  if (conteudo === 'sem-digval') return { acao: 'sem-prova', situacao: v.situacao, consulta };
+  if (p.nfeProc === undefined) return { acao: 'indefinida', outcome: consulta };
+  return { acao: 'concluida', situacao: v.situacao, conteudo, outcome: authorized(protStatus, p) };
+}

package/src/services/soap.ts

@@ -0,0 +1,133 @@
+/**
+ * Chamada SOAP 1.2 a um web service da NF-e 4.00: monta o corpo com o namespace do WSDL (dado em `data/servicos.json`),
+ * envia pelo `Transport` injetado e devolve o elemento de retorno como fatia da resposta, com a árvore para leitura.
+ */
+
+import type { Logger } from '@sinete/core';
+import { ProtocolError } from '@sinete/core';
+import type { XmlDocument, XmlElement } from '@sinete/core/xml';
+import { childElements, descendants, parseXml } from '@sinete/core/xml';
+import type { EndpointRef, NfeServico, Transport } from '@sinete/transport';
+import { soap12ContentType, soap12Envelope, soapFault } from '@sinete/transport';
+import servicos from '../data/servicos.json' with { type: 'json' };
+import { NFE_NS } from './proc.ts';
+
+interface ServicoInfo {
+  readonly namespace: string;
+  readonly operacao: string;
+  readonly envelope?: string;
+  /**
+   * Autorizadores que pedem a mensagem dentro do elemento da operação do WSDL (`<operacao><nfeDadosMsg>`), como a
+   * Distribuição DF-e faz para todos. Valor `operacao`; a fonte fica em `fonteEnvelope`.
+   */
+  readonly envelopeNoAutorizador?: Readonly<Record<string, string>>;
+  readonly fonteEnvelope?: string;
+}
+
+const SERVICOS: Readonly<Record<string, ServicoInfo>> = servicos.servicos;
+
+/** Namespace do WSDL e operação do serviço. */
+export function servicoInfo(servico: NfeServico): ServicoInfo {
+  const s = SERVICOS[servico];
+  if (!s) throw new ProtocolError(`serviço sem descrição em data/servicos.json: ${servico}`);
+  return s;
+}
+
+/** Corpo SOAP do serviço: a mensagem entra como texto, sem reparse. */
+export function soapBodyFor(servico: NfeServico, mensagem: string, autorizador?: string): string {
+  const s = servicoInfo(servico);
+  if (s.envelope === 'distDFeInteresse' || (autorizador && s.envelopeNoAutorizador?.[autorizador] === 'operacao')) {
+    return `<${s.operacao} xmlns="${s.namespace}"><nfeDadosMsg>${mensagem}</nfeDadosMsg></${s.operacao}>`;
+  }
+  return `<nfeDadosMsg xmlns="${s.namespace}">${mensagem}</nfeDadosMsg>`;
+}
+
+/** Resposta de um serviço: o documento inteiro (para fatiar) e o elemento de retorno. */
+export interface RespostaSoap {
+  readonly doc: XmlDocument;
+  readonly ret: XmlElement;
+  readonly status: number;
+}
+
+export interface ChamadaSoap {
+  readonly transport: Transport;
+  readonly endpoint: EndpointRef;
+  readonly servico: NfeServico;
+  readonly mensagem: string;
+  /** Nome local do elemento de retorno (`retEnviNFe`, `retConsSitNFe`...). */
+  readonly retorno: string;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly logger: Logger;
+}
+
+/** Envia e devolve o elemento de retorno. Fault SOAP, retorno ausente ou XML malformado viram `ProtocolError`. */
+export async function chamar(c: ChamadaSoap): Promise<RespostaSoap> {
+  const s = servicoInfo(c.servico);
+  const started = { servico: c.servico, autorizador: c.endpoint.autorizador, host: c.endpoint.host };
+  const res = await c.transport.send({
+    url: c.endpoint.url,
+    endpoint: c.endpoint,
+    method: 'POST',
+    headers: { 'content-type': soap12ContentType(`${s.namespace}/${s.operacao}`) },
+    body: soap12Envelope(soapBodyFor(c.servico, c.mensagem, c.endpoint.autorizador)),
+    ...(c.timeoutMs === undefined ? {} : { timeoutMs: c.timeoutMs }),
+    ...(c.signal === undefined ? {} : { signal: c.signal }),
+  });
+  const text = res.text();
+  const fault = soapFault(text);
+  if (fault) {
+    c.logger.warn('nfe.soap.fault', { ...started, status: res.status, code: fault.code });
+    throw new ProtocolError(`SOAP fault de ${c.endpoint.host}: ${fault.reason ?? fault.code ?? 'sem motivo'}`, {
+      details: { status: res.status, code: fault.code, reason: fault.reason, servico: c.servico },
+    });
+  }
+  let doc: XmlDocument;
+  try {
+    doc = parseXml(text.replace(/^/, ''));
+  } catch (cause) {
+    throw new ProtocolError(`resposta de ${c.endpoint.host} não é XML (HTTP ${res.status})`, {
+      cause,
+      details: { status: res.status, servico: c.servico },
+    });
+  }
+  let ret: XmlElement | undefined;
+  for (const el of descendants(doc.root)) {
+    if (el.local === c.retorno && el.ns === NFE_NS) {
+      ret = el;
+      break;
+    }
+  }
+  if (!ret) ret = retornoForaDoNamespace(doc.root, c.retorno);
+  if (ret && ret.ns !== NFE_NS) {
+    // A SEFAZ-MG devolve o <retConsCad> sem o namespace da NF-e: ele herda o default do WSDL do nfeResultMsg, e só
+    // os filhos declaram o da NF-e (visto em homologação e em produção em 28/09/2026). O conteúdo é o do leiaute.
+    c.logger.warn('nfe.soap.retorno_fora_do_namespace', { ...started, retorno: c.retorno, ns: ret.ns });
+  }
+  if (!ret) {
+    throw new ProtocolError(`resposta de ${c.endpoint.host} sem <${c.retorno}> (HTTP ${res.status})`, {
+      details: { status: res.status, servico: c.servico },
+    });
+  }
+  if (!Array.from(descendants(ret)).some((el) => el.local === 'cStat' && el.ns === NFE_NS)) {
+    throw new ProtocolError(`<${c.retorno}> de ${c.endpoint.host} sem cStat (HTTP ${res.status})`, {
+      details: { status: res.status, servico: c.servico },
+    });
+  }
+  c.logger.debug('nfe.soap.resposta', { ...started, status: res.status });
+  return { doc, ret, status: res.status };
+}
+
+/**
+ * O elemento de retorno com o nome certo em outro namespace, aceito só quando os filhos dele estão no namespace da
+ * NF-e: é o caso do autorizador que esquece o `xmlns` no elemento de retorno e o declara nos filhos. Com os filhos
+ * fora do namespace, a resposta continua recusada.
+ */
+function retornoForaDoNamespace(root: XmlElement, retorno: string): XmlElement | undefined {
+  for (const el of descendants(root)) {
+    if (el.local !== retorno) continue;
+    const filhos = childElements(el);
+    if (filhos.length > 0 && filhos.every((f) => f.ns === NFE_NS)) return el;
+  }
+  return undefined;
+}

package/src/time.ts

@@ -0,0 +1,23 @@
+/**
+ * Fuso do emitente e formatação dos instantes do leiaute (`TDateTimeUTC`, `AAAA-MM-DDThh:mm:ss±hh:mm`). O fuso vem da
+ * tabela `data/fusos.json` pela UF, ou do chamador; nunca do fuso da máquina.
+ */
+
+import type { Clock, Uf } from '@sinete/core';
+import { formatDateTimeOffset } from '@sinete/core';
+import fusos from './data/fusos.json' with { type: 'json' };
+
+/** Instante no tempo, como os relógios do `@sinete/core` o devolvem (o tipo `Date`, sem tocar no global). */
+export type Instante = ReturnType<Clock['now']>;
+
+const UF_OFFSETS: Readonly<Record<string, number>> = fusos.ufs;
+
+/** Deslocamento do horário legal da UF em minutos (`-180` para Brasília). */
+export function offsetDaUf(uf: Uf): number {
+  return Object.hasOwn(UF_OFFSETS, uf) ? (UF_OFFSETS[uf] as number) : fusos.padrao;
+}
+
+/** `TDateTimeUTC` do instante no deslocamento dado. */
+export function formatDh(date: Instante, offsetMinutes: number): string {
+  return formatDateTimeOffset(date, offsetMinutes);
+}

package/src/versao-gerada.ts

@@ -0,0 +1,3 @@
+// GERADO por scripts/versao-gerada.ts a partir do package.json. Não edite: rode `bun scripts/versao-gerada.ts`.
+/** Versão de `@sinete/nfe`, para o padrão de `verProc`/`verAplic` (`formatarVerProc` do @sinete/core). */
+export const VERSAO_PACOTE = '0.1.0';