@sinete/nfe 0.1.0 → 0.3.0

package/src/build/build.ts

@@ -1,15 +1,23 @@
 /**
- * Montagem da NF-e: entrada do domínio (`NfeInput`) para o objeto tipado do `@sinete/schemas` no PL vigente, com os
+ * Montagem da NF-e: entrada do domínio (`DadosNfe`) para o objeto tipado do `@sinete/schemas` no PL vigente, com os
  * derivados e os totais em decimal exato, a chave de acesso e as regras conferidas antes de qualquer serialização. A
- * saída é a string canônica de `<NFe>` ainda sem assinatura, já validada contra o schema; `signNfe` insere a
+ * saída é a string canônica de `<NFe>` ainda sem assinatura, já validada contra o schema; `assinarNfe` insere a
  * `Signature` por splice (ADR 0003) e nada mais toca nela.
  */
 
-import type { Ambiente, Signer, TimeContext, Uf, ValidationIssue } from '@sinete/core';
-import { ConfigError, fixedClock, formatarVerProc, isUf, tpAmbOf, ufBySigla, ValidationError } from '@sinete/core';
-import { base64Encode, firstChild, parseXml, signXml } from '@sinete/core/xml';
-import type { ComplexType, VigenciaEntry } from '@sinete/schemas';
-import { SerializeError, serialize, validate } from '@sinete/schemas';
+import type { Ambiente, Assinador, ContextoDeTempo, Ocorrencia, Uf } from '@sinete/core';
+import {
+  ErroDeConfiguracao,
+  ErroDeValidacao,
+  ehUf,
+  formatarVerProc,
+  relogioFixo,
+  tpAmbDoAmbiente,
+  ufPorSigla,
+} from '@sinete/core';
+import { assinarXml, codificarBase64, lerXml, primeiroFilho } from '@sinete/core/xml';
+import type { ComplexType, EntradaDeVigencia } from '@sinete/schemas';
+import { ErroSerializacao, serializar, validar } from '@sinete/schemas';
 import type {
   TNFe_infNFe,
   TNFe_infNFe_det,
@@ -21,7 +29,7 @@ import type {
   TTribNFe,
 } from '@sinete/schemas/nfe/PL_010f';
 import { TIS as TISCt, TNFe_infNFeSupl, TTribNFe as TTribNFeCt } from '@sinete/schemas/nfe/PL_010f';
-import { buildChaveAcesso, parseChaveAcesso, parseCnpj, parseCpf, parseIe } from '@sinete/validators';
+import { lerChaveAcesso, lerCnpj, lerCpf, lerIe, montarChaveAcesso } from '@sinete/validators';
 import arredondamento from '../data/arredondamento.json' with { type: 'json' };
 import produtorRural from '../data/produtor-rural.json' with { type: 'json' };
 import reforma from '../data/reforma.json' with { type: 'json' };
@@ -31,6 +39,7 @@ import { Decimal } from '../decimal.ts';
 import { D0302, D0302A04, D1104V, D1110V, D1203, D1302, D1302_OPC } from '../format.ts';
 import { Issues } from '../issues.ts';
 import type {
+  DadosNfe,
   Destinatario,
   DocumentoPessoa,
   Emitente,
@@ -38,14 +47,13 @@ import type {
   EnderecoExterior,
   Item,
   Local,
-  NfeInput,
   Referenciada,
   ResponsavelTecnico,
 } from '../model.ts';
-import type { IbsCbsCalculator, IbsCbsItemRequest } from '../ports.ts';
-import { ibsCbsCalculator } from '../rtc.ts';
+import type { CalculadoraIbsCbs, PedidoIbsCbsItem } from '../ports.ts';
+import { calculadoraIbsCbs } from '../rtc.ts';
 import type { Instante } from '../time.ts';
-import { formatDh, offsetDaUf } from '../time.ts';
+import { deslocamentoDaUf, formatarDh } from '../time.ts';
 import { VERSAO_PACOTE } from '../versao-gerada.ts';
 import { conferirDestinatario } from './destinatario.ts';
 import { decimaisInvalidos, grupoInvalido, ibsCbsDoItem, totalIbsCbs } from './ibscbs.ts';
@@ -62,15 +70,16 @@ import {
 } from './nfce.ts';
 import { camposForaDoPl, escolherPl } from './pl.ts';
 import { cstComIsento, vencimentos } from './rejeicoes.ts';
+import { conferirTextosDaEntrada, textoXmlValido } from './textos.ts';
 import { buildIcmsUfDest, buildIi, buildIpi, buildIssqn, buildPisCofins, buildPisCofinsSt } from './tributos.ts';
 import type { Familia } from './values.ts';
 import { Ctx, clean, digits, TOLERANCIA } from './values.ts';
 
-let padrao: IbsCbsCalculator | undefined;
+let padrao: CalculadoraIbsCbs | undefined;
 
-/** A calculadora de IBS/CBS usada quando `options.ibsCbs` não vem: o motor do sinete, criada uma vez por processo. */
-function calculadoraPadrao(): IbsCbsCalculator {
-  padrao ??= ibsCbsCalculator();
+/** A calculadora de IBS/CBS usada quando `opcoes.ibsCbs` não vem: o motor do sinete, criada uma vez por processo. */
+function calculadoraPadrao(): CalculadoraIbsCbs {
+  padrao ??= calculadoraIbsCbs();
   return padrao;
 }
 
@@ -84,18 +93,18 @@ export const XPROD_HOMOLOGACAO_NFCE = 'NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLO
 
 export type ExigenciaRespTec = 'obrigatorio' | 'opcional';
 
-export interface BuildNfeOptions {
+export interface MontarNfeOpcoes {
   readonly ambiente: Ambiente;
   /** Relógio de emissão (dhEmi, PL vigente, CSRT) e de fato gerador (IBS/CBS). */
-  readonly time: TimeContext;
+  readonly tempo: ContextoDeTempo;
   /**
-   * Calculadora de IBS/CBS dos itens com `ibsCbs.classificacao`. Padrão: `ibsCbsCalculator()`, o motor do sinete com o
+   * Calculadora de IBS/CBS dos itens com `ibsCbs.classificacao`. Padrão: `calculadoraIbsCbs()`, o motor do sinete com o
    * dataset embarcado (importado na primeira nota que precisar dele) e as alíquotas oficiais. Informe outra para trocar
    * dataset, alíquotas, base ou regras, ou para calcular fora do sinete.
    */
-  readonly ibsCbs?: IbsCbsCalculator;
+  readonly ibsCbs?: CalculadoraIbsCbs;
   /** Fuso do emitente em minutos; padrão pela UF (`data/fusos.json`). */
-  readonly offsetMinutes?: number;
+  readonly deslocamentoMin?: number;
   /** Versão do aplicativo emissor (`verProc`); padrão `sinete <versão do @sinete/nfe>` (`formatarVerProc`). */
   readonly verProc?: string;
   /** Sobrepõe o modo de arredondamento de uma família (`data/arredondamento.json`). */
@@ -105,7 +114,7 @@ export interface BuildNfeOptions {
   /** Sobrepõe a exigência de infRespTec e CSRT da tabela por UF (`data/resp-tec.json`). */
   readonly exigencias?: { readonly infRespTec?: ExigenciaRespTec; readonly csrt?: ExigenciaRespTec };
   /** Fonte de aleatoriedade para o cNF; padrão `crypto.getRandomValues`. */
-  readonly random?: (bytes: Uint8Array) => Uint8Array;
+  readonly aleatorio?: (bytes: Uint8Array) => Uint8Array;
   /**
    * O `vPag` do único `detPag` passa a ser o `vNF` calculado na mesma montagem, e o valor informado nele é ignorado.
    * Serve a quem recebe à vista o total da nota e não quer calcular o `vNF` antes de montar. Mais de um `detPag`,
@@ -128,7 +137,7 @@ export interface BuildNfeOptions {
   readonly urlChave?: string;
 }
 
-export interface BuiltNfe {
+export interface NfeMontada {
   /** Chave de acesso (44 posições). */
   readonly chave: string;
   /** `Id` do `infNFe` (`NFe` + chave): é o que a assinatura referencia. */
@@ -140,21 +149,21 @@ export interface BuiltNfe {
   readonly tpEmis: string;
   readonly dhEmi: string;
   /**
-   * Só NFC-e: o `infNFeSupl` a acrescentar (`comQrCode`, `signNfe`). Na versão 3 em contingência off-line, falta a
+   * Só NFC-e: o `infNFeSupl` a acrescentar (`comQrCode`, `assinarNfe`). Na versão 3 em contingência off-line, falta a
    * assinatura dos parâmetros, que só o certificado faz (`assinaturaQrCode`).
    */
   readonly nfce?: NfceSupl;
   /** Pacote de liberação usado (escolhido pela vigência). */
-  readonly pl: VigenciaEntry;
+  readonly pl: EntradaDeVigencia;
   /** O objeto tipado, na forma do PL_010f (o mais novo que o pacote conhece). */
   readonly infNFe: TNFe_infNFe;
   /** `<NFe xmlns="...">` com o `infNFe` canônico, sem assinatura, já validado contra o schema. */
   readonly xml: string;
 }
 
-export type BuildNfeResult =
-  | { readonly ok: true; readonly value: BuiltNfe }
-  | { readonly ok: false; readonly issues: readonly ValidationIssue[] };
+export type ResultadoMontagemNfe =
+  | { readonly ok: true; readonly valor: NfeMontada }
+  | { readonly ok: false; readonly ocorrencias: readonly Ocorrencia[] };
 
 const MODES: Record<Familia, RoundingMode> = Object.fromEntries(
   Object.entries(arredondamento.familias).map(([k, v]) => [k, v.modo as RoundingMode]),
@@ -164,7 +173,7 @@ const SEM_GTIN = 'SEM GTIN';
 const BRASILIA = -180;
 
 function diaBrasilia(d: Instante): string {
-  return formatDh(d, BRASILIA).slice(0, 10);
+  return formatarDh(d, BRASILIA).slice(0, 10);
 }
 
 /** Exigência de infRespTec ou CSRT para a UF no ambiente e na data (tabela `data/resp-tec.json`). */
@@ -192,29 +201,29 @@ export function exigenciaRespTec(
 /** `hashCSRT`: Base64(SHA-1(CSRT + chave de acesso)) (NT 2018.005, campo ZD09). */
 export async function hashCsrt(csrt: string, chave: string): Promise<string> {
   const d = await globalThis.crypto.subtle.digest('SHA-1', new TextEncoder().encode(csrt + chave));
-  return base64Encode(new Uint8Array(d));
+  return codificarBase64(new Uint8Array(d));
 }
 
 /** Normaliza CNPJ ou CPF, apontando a ocorrência do validador. */
 function documento(doc: DocumentoPessoa, path: string, issues: Issues): { CNPJ: string } | { CPF: string } {
   if (doc.CNPJ !== undefined) {
-    const r = parseCnpj(doc.CNPJ, { path: `${path}.CNPJ` });
-    if (!r.ok) issues.list.push(r.error);
-    return { CNPJ: r.ok ? r.value : doc.CNPJ };
+    const r = lerCnpj(doc.CNPJ, { caminho: `${path}.CNPJ` });
+    if (!r.ok) issues.list.push(r.erro);
+    return { CNPJ: r.ok ? r.valor : doc.CNPJ };
   }
-  const r = parseCpf(doc.CPF ?? '', { path: `${path}.CPF` });
-  if (!r.ok) issues.list.push(r.error);
-  return { CPF: r.ok ? r.value : (doc.CPF ?? '') };
+  const r = lerCpf(doc.CPF ?? '', { caminho: `${path}.CPF` });
+  if (!r.ok) issues.list.push(r.erro);
+  return { CPF: r.ok ? r.valor : (doc.CPF ?? '') };
 }
 
 function ie(value: string | undefined, uf: Uf, path: string, issues: Issues, allowIsento: boolean): string | undefined {
   if (value === undefined) return undefined;
-  const r = parseIe(value, uf, { path, allowIsento });
+  const r = lerIe(value, uf, { caminho: path, aceitarIsento: allowIsento });
   if (!r.ok) {
-    issues.list.push(r.error);
+    issues.list.push(r.erro);
     return value;
   }
-  return r.value.value;
+  return r.valor.valor;
 }
 
 function endereco(e: Endereco): Record<string, string | undefined> {
@@ -242,10 +251,10 @@ function gerarChave(
   random: (b: Uint8Array) => Uint8Array,
   issues: Issues,
 ): { chave: string; cNF: string } | undefined {
-  const tentar = (cNF: string): { chave: string; ok: boolean; issue?: ValidationIssue } => {
-    const chave = buildChaveAcesso({ ...parts, cNF });
-    const r = parseChaveAcesso(chave, { emissao: true, path: 'chave' });
-    return r.ok ? { chave, ok: true } : { chave, ok: false, issue: r.error };
+  const tentar = (cNF: string): { chave: string; ok: boolean; issue?: Ocorrencia } => {
+    const chave = montarChaveAcesso({ ...parts, cNF });
+    const r = lerChaveAcesso(chave, { emissao: true, caminho: 'chave' });
+    return r.ok ? { chave, ok: true } : { chave, ok: false, issue: r.erro };
   };
   if (cNFInformado !== undefined) {
     if (!/^\d{8}$/.test(cNFInformado)) {
@@ -259,9 +268,9 @@ function gerarChave(
       const doCnf = r.issue.code === 'chave_cnf_invalido';
       issues.list.push({
         ...r.issue,
-        path: doCnf ? 'cNF' : r.issue.path,
+        caminho: doCnf ? 'cNF' : r.issue.caminho,
         code: 'chave_invalida',
-        message: `${r.issue.message} (${r.issue.code})`,
+        mensagem: `${r.issue.mensagem} (${r.issue.code})`,
         origem: doCnf ? 'entrada' : 'montagem',
       });
     }
@@ -279,7 +288,7 @@ function gerarChave(
       issues.list.push({
         ...r.issue,
         code: 'chave_invalida',
-        message: `${r.issue.message} (${r.issue.code})`,
+        mensagem: `${r.issue.mensagem} (${r.issue.code})`,
         origem: 'montagem',
       });
       return undefined;
@@ -291,9 +300,9 @@ function gerarChave(
 
 function referencia(ref: Referenciada, path: string, issues: Issues): TNFe_infNFe_ide_NFref {
   const chave = (c: string, p: string): string => {
-    const r = parseChaveAcesso(c, { path: p });
-    if (!r.ok) issues.list.push(r.error);
-    return r.ok ? r.value.chave : c;
+    const r = lerChaveAcesso(c, { caminho: p });
+    if (!r.ok) issues.list.push(r.erro);
+    return r.ok ? r.valor.chave : c;
   };
   if ('refNFe' in ref) return { refNFe: chave(ref.refNFe, `${path}.refNFe`) };
   if ('refNFeSig' in ref) {
@@ -312,7 +321,7 @@ function referencia(ref: Referenciada, path: string, issues: Issues): TNFe_infNF
   // Nota de produtor em papel (modelo 04) extinta: só referência a nota emitida antes do fim na UF dela.
   if (nfp.mod === '04') {
     const porUf = produtorRural.refNFP.ufs as Readonly<Record<string, { readonly vedadaDesde: string }>>;
-    const cUfSigla = Object.keys(porUf).find((k) => ufBySigla(k)?.cUF === nfp.cUF);
+    const cUfSigla = Object.keys(porUf).find((k) => ufPorSigla(k)?.cUF === nfp.cUF);
     const vedadaDesde = cUfSigla ? (porUf[cUfSigla]?.vedadaDesde ?? '') : produtorRural.refNFP.modelo04.vedadaDesde;
     if (nfp.AAMM >= vedadaDesde) {
       issues.add(
@@ -336,25 +345,10 @@ function referencia(ref: Referenciada, path: string, issues: Issues): TNFe_infNF
   } as TNFe_infNFe_ide_NFref;
 }
 
-/** Produção `Char` do XML 1.0: tab, LF, CR, U+0020 a U+D7FF, U+E000 a U+FFFD e U+10000 a U+10FFFF. */
-function textoXmlValido(texto: string): boolean {
-  for (const ch of texto) {
-    const c = ch.codePointAt(0) ?? 0;
-    const ok =
-      c === 0x9 ||
-      c === 0xa ||
-      c === 0xd ||
-      (c >= 0x20 && c <= 0xd7ff) ||
-      (c >= 0xe000 && c <= 0xfffd) ||
-      (c >= 0x10000 && c <= 0x10ffff);
-    if (!ok) return false;
-  }
-  return true;
-}
-
 /**
- * Texto com caractere que o XML não representa (vindo, por exemplo, de uma descrição importada) vira ocorrência com o
- * caminho do campo, em vez de falhar no parse do documento montado.
+ * Texto com caractere que o XML não representa vira ocorrência com o caminho do campo, em vez de falhar no parse do
+ * documento montado. Os textos da entrada já foram conferidos com o caminho dela (`conferirTextosDaEntrada`): aqui só
+ * sobra o que veio das opções da montagem.
  */
 function textosForaDoXml(value: unknown, path: string, issues: Issues): void {
   if (typeof value === 'string') {
@@ -576,10 +570,10 @@ function montarItem(ctx: Ctx, item: Item, n: number, normal: boolean): ItemMonta
   if (item.infAdProd !== undefined) det.infAdProd = item.infAdProd;
   if (item.obsItem !== undefined) det.obsItem = item.obsItem;
   if (item.DFeReferenciado !== undefined) {
-    const r = parseChaveAcesso(item.DFeReferenciado.chaveAcesso, { path: `${path}.DFeReferenciado.chaveAcesso` });
-    if (!r.ok) ctx.issues.list.push(r.error);
+    const r = lerChaveAcesso(item.DFeReferenciado.chaveAcesso, { caminho: `${path}.DFeReferenciado.chaveAcesso` });
+    if (!r.ok) ctx.issues.list.push(r.erro);
     det.DFeReferenciado = clean({
-      chaveAcesso: r.ok ? r.value.chave : item.DFeReferenciado.chaveAcesso,
+      chaveAcesso: r.ok ? r.valor.chave : item.DFeReferenciado.chaveAcesso,
       nItem: item.DFeReferenciado.nItem === undefined ? undefined : String(item.DFeReferenciado.nItem),
     });
   }
@@ -616,44 +610,44 @@ function composicao(m: ItemMontado, incluirProd: boolean): Decimal {
 }
 
 /** Monta, calcula e valida. Nunca lança por dado do chamador: devolve as ocorrências. */
-export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promise<BuildNfeResult> {
+export async function montarNfe(entrada: DadosNfe, opcoes: MontarNfeOpcoes): Promise<ResultadoMontagemNfe> {
   const issues = new Issues();
-  const finNFeIn = input.finNFe ?? '1';
-  const mod = input.modelo ?? '55';
+  const finNFeIn = entrada.finNFe ?? '1';
+  const mod = entrada.modelo ?? '55';
   if (mod !== '55' && mod !== '65') {
     issues.add('modelo', 'modelo_nao_suportado', `modelo ${String(mod)}: o builder monta NF-e (55) e NFC-e (65)`);
-    return { ok: false, issues: issues.classificadas };
+    return { ok: false, ocorrencias: issues.classificadas };
   }
   const nfce = mod === '65';
   // Padrões da identificação resolvidos uma vez: o mesmo valor vai para o ide e para a calculadora de IBS/CBS. A NFC-e
   // é presencial e para consumidor final (MOC 7.0 Anexo I, B25a-10 e B25b-20).
-  const indPres = input.indPres ?? (nfce ? '1' : finNFeIn === '2' || finNFeIn === '3' ? '0' : '9');
-  const indFinal = input.indFinal ?? (nfce || input.destinatario?.indIEDest === '9' ? '1' : '0');
-  const ctx = new Ctx(issues, { ...MODES, ...options.arredondamento }, finNFeIn !== '2' && finNFeIn !== '3');
-  const pRedutorGov = input.gCompraGov && ctx.req(input.gCompraGov.pRedutor, 'gCompraGov.pRedutor', D0302A04);
-  const emitUf = input.emitente.endereco.UF;
-  if (!isUf(emitUf)) {
+  const indPres = entrada.indPres ?? (nfce ? '1' : finNFeIn === '2' || finNFeIn === '3' ? '0' : '9');
+  const indFinal = entrada.indFinal ?? (nfce || entrada.destinatario?.indIEDest === '9' ? '1' : '0');
+  const ctx = new Ctx(issues, { ...MODES, ...opcoes.arredondamento }, finNFeIn !== '2' && finNFeIn !== '3');
+  const pRedutorGov = entrada.gCompraGov && ctx.req(entrada.gCompraGov.pRedutor, 'gCompraGov.pRedutor', D0302A04);
+  const emitUf = entrada.emitente.endereco.UF;
+  if (!ehUf(emitUf)) {
     issues.add('emitente.endereco.UF', 'campo_invalido', 'UF do emitente inválida');
-    return { ok: false, issues: issues.classificadas };
+    return { ok: false, ocorrencias: issues.classificadas };
   }
-  const cUF = ufBySigla(emitUf)?.cUF ?? '';
-  const offset = options.offsetMinutes ?? offsetDaUf(emitUf);
-  const agora = options.time.emissao.now();
+  const cUF = ufPorSigla(emitUf)?.cUF ?? '';
+  const offset = opcoes.deslocamentoMin ?? deslocamentoDaUf(emitUf);
+  const agora = opcoes.tempo.emissao.agora();
   // Um instante de fato gerador por montagem: o mesmo vai para a calculadora e para a regra de composição do vItem.
-  const fatoGerador = options.time.fatoGerador.now();
-  const dhEmi = formatDh(agora, offset);
+  const fatoGerador = opcoes.tempo.fatoGerador.agora();
+  const dhEmi = formatarDh(agora, offset);
   const aamm = dhEmi.slice(2, 4) + dhEmi.slice(5, 7);
-  const tpAmb = tpAmbOf(options.ambiente);
+  const tpAmb = tpAmbDoAmbiente(opcoes.ambiente);
 
-  // PL vigente (VigenciaError do schemas propaga: data fora de toda vigência é erro de configuração, não de dado).
+  // PL vigente (ErroVigencia do schemas propaga: data fora de toda vigência é erro de configuração, não de dado).
   // O PL sai do mesmo instante do dhEmi: reler o relógio numa virada de vigência escolheria outro PL.
-  const pl = escolherPl(options.ambiente, fixedClock(agora));
+  const pl = escolherPl(opcoes.ambiente, relogioFixo(agora));
 
   // Emitente (grupo C)
-  const e: Emitente = input.emitente;
+  const e: Emitente = entrada.emitente;
   const emitDoc = documento(e, 'emitente', issues);
-  const serie = Number(input.serie);
-  const nNF = Number(input.nNF);
+  const serie = Number(entrada.serie);
+  const nNF = Number(entrada.nNF);
   if (!Number.isInteger(serie) || serie < 0 || serie > 999) issues.add('serie', 'serie_invalida', 'série de 0 a 999');
   if (!Number.isInteger(nNF) || nNF < 1 || nNF > 999_999_999)
     issues.add('nNF', 'campo_invalido', 'nNF de 1 a 999999999');
@@ -687,7 +681,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
 
   // Destinatário (grupo E): obrigatório na NF-e (RV E01-10); na NFC-e, só na entrega a domicílio (E01-20, conferida
   // com as demais regras da NFC-e).
-  const d: Destinatario | undefined = input.destinatario;
+  const d: Destinatario | undefined = entrada.destinatario;
   let dest: Record<string, unknown> | undefined;
   let destUf: Uf | 'EX' | undefined;
   if (d === undefined) {
@@ -723,7 +717,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
         : d.IE;
     dest = clean({
       ...docDest,
-      xNome: options.ambiente === 'homologacao' ? XNOME_HOMOLOGACAO : d.xNome,
+      xNome: opcoes.ambiente === 'homologacao' ? XNOME_HOMOLOGACAO : d.xNome,
       enderDest,
       indIEDest: d.indIEDest,
       IE: destIe,
@@ -734,7 +728,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   }
 
   // Identificação: contingência e forma de emissão
-  const cont = input.contingencia;
+  const cont = entrada.contingencia;
   const tpEmis = cont?.tpEmis ?? '1';
   if (cont !== undefined) {
     if (cont.xJust.length < 15 || cont.xJust.length > 256) {
@@ -766,25 +760,25 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   // Identificação que as regras do modelo conferem antes de montar.
   // Na NFC-e a operação é sempre interna (B11a-10, rejeição 707): o endereço do consumidor não a torna interestadual.
   const idDest =
-    input.idDest ?? (nfce ? '1' : destUf === 'EX' ? '3' : destUf !== undefined && destUf !== emitUf ? '2' : '1');
-  const tpImp = input.tpImp ?? (nfce ? '4' : '1');
+    entrada.idDest ?? (nfce ? '1' : destUf === 'EX' ? '3' : destUf !== undefined && destUf !== emitUf ? '2' : '1');
+  const tpImp = entrada.tpImp ?? (nfce ? '4' : '1');
   conferirDestinatario(
-    input,
+    entrada,
     {
       mod,
-      tpNF: input.tpNF,
+      tpNF: entrada.tpNF,
       idDest,
-      idDestInformado: input.idDest !== undefined,
+      idDestInformado: entrada.idDest !== undefined,
       indFinal,
-      producao: options.ambiente === 'producao',
+      producao: opcoes.ambiente === 'producao',
     },
     issues,
   );
   if (nfce) {
     conferirNfce(
-      input,
+      entrada,
       {
-        tpNF: input.tpNF,
+        tpNF: entrada.tpNF,
         idDest,
         tpImp,
         finNFe: finNFeIn,
@@ -796,7 +790,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   } else if (tpImp === '4' || tpImp === '5') {
     issues.add('tpImp', 'campo_invalido', 'tpImp 4 e 5 (DANFC-e) são da NFC-e (B21-20, rejeição 710)');
   }
-  const qr: QrCodeNfceOpcoes = options.qrCode ?? { versao: '3' };
+  const qr: QrCodeNfceOpcoes = opcoes.qrCode ?? { versao: '3' };
   if (nfce && qr.versao === '2') {
     // O CSC e o idCSC são opções do montador, não da nota: as ocorrências são da montagem (ADR 0011).
     if (!/^\d{1,6}$/.test(qr.idCSC) || Number(qr.idCSC) === 0) {
@@ -824,12 +818,13 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
 
   // Chave de acesso e cNF
   const random =
-    options.random ?? ((b: Uint8Array): Uint8Array => globalThis.crypto.getRandomValues(b as Uint8Array<ArrayBuffer>));
+    opcoes.aleatorio ??
+    ((b: Uint8Array): Uint8Array => globalThis.crypto.getRandomValues(b as Uint8Array<ArrayBuffer>));
   const emitente14 = 'CNPJ' in emitDoc ? emitDoc.CNPJ : emitDoc.CPF;
   const gerada = issues.empty
     ? gerarChave(
         { cUF, aamm, emitente: emitente14, mod, serie: String(serie), nNF: String(nNF), tpEmis },
-        input.cNF,
+        entrada.cNF,
         random,
         issues,
       )
@@ -839,24 +834,24 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   const cDV = chave.slice(43);
 
   // Itens
-  if (input.itens.length === 0 || input.itens.length > 990) {
+  if (entrada.itens.length === 0 || entrada.itens.length > 990) {
     issues.add('itens', 'itens_limite', 'a NF-e tem de 1 a 990 itens');
   }
-  const itens = input.itens.map((it, n) => montarItem(ctx, it, n, finNFeIn === '1'));
+  const itens = entrada.itens.map((it, n) => montarItem(ctx, it, n, finNFeIn === '1'));
   // Na NFC-e em homologação, a descrição do primeiro item é a literal da RV I04-10, como o nome do destinatário da
   // E04-20: o builder a põe, e a descrição informada fica fora do XML de teste.
   const primeiro = itens[0];
-  if (nfce && options.ambiente === 'homologacao' && primeiro !== undefined) {
+  if (nfce && opcoes.ambiente === 'homologacao' && primeiro !== undefined) {
     (primeiro.det.prod as unknown as Record<string, unknown>).xProd = XPROD_HOMOLOGACAO_NFCE;
   }
 
   // IBS/CBS pela calculadora das opções, ou pelo motor do sinete
-  const classificados = input.itens
+  const classificados = entrada.itens
     .map((it, n) => ({ it, n }))
     .filter(({ it }) => it.impostos.ibsCbs?.classificacao !== undefined);
   if (classificados.length > 0) {
-    const calculadora = options.ibsCbs ?? calculadoraPadrao();
-    const reqs: IbsCbsItemRequest[] = classificados.map(({ it, n }) => {
+    const calculadora = opcoes.ibsCbs ?? calculadoraPadrao();
+    const reqs: PedidoIbsCbsItem[] = classificados.map(({ it, n }) => {
       const c = it.impostos.ibsCbs?.classificacao as NonNullable<
         NonNullable<typeof it.impostos.ibsCbs>['classificacao']
       >;
@@ -894,29 +889,29 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
       };
     });
     const destino =
-      input.entrega !== undefined
-        ? { UF: input.entrega.UF, cMun: input.entrega.cMun }
+      entrada.entrega !== undefined
+        ? { UF: entrada.entrega.UF, cMun: entrada.entrega.cMun }
         : d?.endereco !== undefined
           ? isExterior(d.endereco)
             ? { UF: 'EX' as const, cMun: '9999999' }
             : { UF: d.endereco.UF, cMun: d.endereco.cMun }
           : undefined;
-    const compra = input.gCompraGov;
+    const compra = entrada.gCompraGov;
     const resp = await calculadora.calcular({
       nota: {
         fatoGerador,
         emissao: agora,
-        ambiente: options.ambiente,
+        ambiente: opcoes.ambiente,
         mod,
-        tpNF: input.tpNF,
+        tpNF: entrada.tpNF,
         finNFe: finNFeIn,
-        ...(input.tpNFDebito ? { tpNFDebito: input.tpNFDebito } : {}),
-        ...(input.tpNFCredito ? { tpNFCredito: input.tpNFCredito } : {}),
+        ...(entrada.tpNFDebito ? { tpNFDebito: entrada.tpNFDebito } : {}),
+        ...(entrada.tpNFCredito ? { tpNFCredito: entrada.tpNFCredito } : {}),
         indFinal,
         indPres,
         emitente: { UF: emitUf, cMun: e.endereco.cMun, CRT: e.CRT },
         ...(destino ? { destino } : {}),
-        ...(input.cMunFGIBS ? { cMunFGIBS: input.cMunFGIBS } : {}),
+        ...(entrada.cMunFGIBS ? { cMunFGIBS: entrada.cMunFGIBS } : {}),
         ...(compra && pRedutorGov
           ? {
               compraGov: {
@@ -929,7 +924,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
       },
       itens: reqs,
     });
-    issues.addAll(resp.issues ?? [], 'montagem');
+    issues.addAll(resp.ocorrencias ?? [], 'montagem');
     for (const { n } of classificados) {
       const g = resp.itens.find((x) => x.nItem === n + 1);
       if (g === undefined) {
@@ -951,7 +946,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
     const ib = `itens[${n}].impostos.ibsCbs`;
     const is = `itens[${n}].impostos.is`;
     // O IBSCBS pronto (ibsCbs.grupo) é da entrada; o que a calculadora devolveu é da montagem (ADR 0011).
-    const ibsDaCalculadora = input.itens[n]?.impostos.ibsCbs?.grupo === undefined;
+    const ibsDaCalculadora = entrada.itens[n]?.impostos.ibsCbs?.grupo === undefined;
     const antes = issues.list.length;
     decimaisInvalidos(imp.IBSCBS, ib, issues);
     if (ibsDaCalculadora) issues.reclassificarDesde(antes, 'montagem');
@@ -962,7 +957,14 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
       grupoInvalido(TISCt as ComplexType, 'IS', imp.IS, is, issues);
     }
   });
-  if (!issues.empty) return { ok: false, issues: issues.classificadas };
+  // Texto e tamanho dos campos de texto pelo tipo do PL, com o caminho da entrada (ADR 0011); o campo que outra
+  // conferência já recusou fica só com a ocorrência dela.
+  // Em homologação, o nome do destinatário e, na NFC-e, a descrição do primeiro item são as literais da E04-20 e da I04-10:
+  // o texto informado não vai ao XML.
+  const substituidos =
+    opcoes.ambiente === 'homologacao' ? ['destinatario.xNome', ...(nfce ? ['itens[0].produto.xProd'] : [])] : [];
+  conferirTextosDaEntrada(entrada, pl.infNFe as ComplexType, issues, new Set(substituidos));
+  if (!issues.empty) return { ok: false, ocorrencias: issues.classificadas };
 
   // Totais (grupo W)
   const gruposIbsCbs = itens
@@ -1096,43 +1098,43 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   const ide = clean({
     cUF,
     cNF,
-    natOp: input.natOp,
+    natOp: entrada.natOp,
     mod,
     serie: String(serie),
     nNF: String(nNF),
     dhEmi,
-    dhSaiEnt: input.dhSaiEnt === undefined ? undefined : formatDh(input.dhSaiEnt, offset),
-    dPrevEntrega: input.dPrevEntrega,
-    tpNF: input.tpNF,
+    dhSaiEnt: entrada.dhSaiEnt === undefined ? undefined : formatarDh(entrada.dhSaiEnt, offset),
+    dPrevEntrega: entrada.dPrevEntrega,
+    tpNF: entrada.tpNF,
     idDest,
-    cMunFG: input.cMunFG ?? e.endereco.cMun,
-    cMunFGIBS: input.cMunFGIBS,
+    cMunFG: entrada.cMunFG ?? e.endereco.cMun,
+    cMunFGIBS: entrada.cMunFGIBS,
     tpImp,
     tpEmis,
     cDV,
     tpAmb,
     finNFe,
-    tpNFDebito: input.tpNFDebito,
-    tpNFCredito: input.tpNFCredito,
+    tpNFDebito: entrada.tpNFDebito,
+    tpNFCredito: entrada.tpNFCredito,
     indFinal,
     indPres,
     // NT 2020.006: indIntermed obrigatório com indPres 2, 3, 4 e 9.
-    indIntermed: input.indIntermed ?? (['2', '3', '4', '9'].includes(indPres) ? '0' : undefined),
+    indIntermed: entrada.indIntermed ?? (['2', '3', '4', '9'].includes(indPres) ? '0' : undefined),
     procEmi: '0',
-    verProc: options.verProc ?? formatarVerProc('sinete', VERSAO_PACOTE),
-    dhCont: cont === undefined ? undefined : formatDh(cont.dhCont, offset),
+    verProc: opcoes.verProc ?? formatarVerProc('sinete', VERSAO_PACOTE),
+    dhCont: cont === undefined ? undefined : formatarDh(cont.dhCont, offset),
     xJust: cont?.xJust,
-    NFref: input.referenciadas?.map((r, n) => referencia(r, `referenciadas[${n}]`, issues)),
+    NFref: entrada.referenciadas?.map((r, n) => referencia(r, `referenciadas[${n}]`, issues)),
     gCompraGov:
-      input.gCompraGov === undefined
+      entrada.gCompraGov === undefined
         ? undefined
         : clean({
-            tpEnteGov: input.gCompraGov.tpEnteGov,
+            tpEnteGov: entrada.gCompraGov.tpEnteGov,
             pRedutor: ctx.s(pRedutorGov ?? Decimal.ZERO, D0302A04),
-            tpOperGov: input.gCompraGov.tpOperGov,
-            refDFeAnt: input.gCompraGov.refDFeAnt as string[] | undefined,
+            tpOperGov: entrada.gCompraGov.tpOperGov,
+            refDFeAnt: entrada.gCompraGov.refDFeAnt as string[] | undefined,
           }),
-    gPagAntecipado: input.gPagAntecipado === undefined ? undefined : { refNFe: [...input.gPagAntecipado] },
+    gPagAntecipado: entrada.gPagAntecipado === undefined ? undefined : { refNFe: [...entrada.gPagAntecipado] },
   });
 
   // Locais, autorizados, transporte, cobrança, pagamento, informações adicionais
@@ -1148,10 +1150,10 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
           email: l.email,
           IE: l.IE,
         });
-  if ((input.autXML?.length ?? 0) > 10) issues.add('autXML', 'campo_invalido', 'no máximo 10 autorizados');
-  const autXML = input.autXML?.map((a, n) => documento(a, `autXML[${n}]`, issues));
+  if ((entrada.autXML?.length ?? 0) > 10) issues.add('autXML', 'campo_invalido', 'no máximo 10 autorizados');
+  const autXML = entrada.autXML?.map((a, n) => documento(a, `autXML[${n}]`, issues));
 
-  const tr = input.transporte;
+  const tr = entrada.transporte;
   const transp: Record<string, unknown> = { modFrete: tr?.modFrete ?? '9' };
   if (tr?.transportador !== undefined) {
     const t = tr.transportador;
@@ -1194,8 +1196,8 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   }
 
   let cobr: Record<string, unknown> | undefined;
-  if (input.cobranca !== undefined) {
-    const c = input.cobranca;
+  if (entrada.cobranca !== undefined) {
+    const c = entrada.cobranca;
     cobr = {};
     if (c.fatura !== undefined) {
       const f = c.fatura;
@@ -1225,10 +1227,10 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
     }
   }
 
-  const pagIn = input.pagamento ?? { detPag: [{ tPag: '90' as const, vPag: '0' }] };
-  const igualTotal = options.pagamentoIgualTotal === true;
+  const pagIn = entrada.pagamento ?? { detPag: [{ tPag: '90' as const, vPag: '0' }] };
+  const igualTotal = opcoes.pagamentoIgualTotal === true;
   if (igualTotal) {
-    const unico = input.pagamento?.detPag.length === 1 ? input.pagamento.detPag[0] : undefined;
+    const unico = entrada.pagamento?.detPag.length === 1 ? entrada.pagamento.detPag[0] : undefined;
     if (unico === undefined) {
       issues.add('pagamento.detPag', 'pagamento_igual_total', 'pagamentoIgualTotal pede exatamente um detPag');
     } else if (unico.tPag === '90') {
@@ -1253,7 +1255,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   }) as unknown as PagMontado;
   // Pagamentos e troco contra o vNF (W16), não o vNFTot: é o total que a YA03-10 (NT 2025.001 v1.03) e a YA09-10 (MOC 7.0
   // Anexo I) citam, e a NT 2025.002 (até a v1.51) não mudou essas regras nem o W16.
-  if (nfce && input.pagamento !== undefined && input.pagamento.detPag.length > 0 && issues.empty) {
+  if (nfce && entrada.pagamento !== undefined && entrada.pagamento.detPag.length > 0 && issues.empty) {
     pagamentoNfce(pag, vNF, issues);
   }
   // W16-40 (rejeição 750): acima do limite, a NFC-e identifica o destinatário por CNPJ, CPF ou idEstrangeiro.
@@ -1264,7 +1266,7 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
       `NFC-e acima de R$ ${NFCE_LIMITE_SEM_DESTINATARIO} identifica o destinatário (W16-40, rejeição 750)`,
     );
   }
-  const ia = input.informacoesAdicionais;
+  const ia = entrada.informacoesAdicionais;
   const infAdic =
     ia === undefined || Object.values(ia).every((x) => x === undefined)
       ? undefined
@@ -1277,18 +1279,18 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
         });
 
   // Responsável técnico e CSRT (NT 2018.005), com a exigência por UF como dado
-  const exig = { ...exigenciaRespTec(emitUf, options.ambiente, agora), ...options.exigencias };
-  const rt = input.respTec ?? options.respTec;
+  const exig = { ...exigenciaRespTec(emitUf, opcoes.ambiente, agora), ...opcoes.exigencias };
+  const rt = entrada.respTec ?? opcoes.respTec;
   let infRespTec: Record<string, unknown> | undefined;
   if (rt === undefined) {
     if (exig.infRespTec === 'obrigatorio') {
       issues.add('respTec', 'resp_tec_obrigatorio', `a UF ${emitUf} exige o responsável técnico (rejeição 972)`);
     }
   } else {
-    const cnpjRt = parseCnpj(rt.CNPJ, { path: 'respTec.CNPJ' });
-    if (!cnpjRt.ok) issues.list.push(cnpjRt.error);
+    const cnpjRt = lerCnpj(rt.CNPJ, { caminho: 'respTec.CNPJ' });
+    if (!cnpjRt.ok) issues.list.push(cnpjRt.erro);
     infRespTec = {
-      CNPJ: cnpjRt.ok ? cnpjRt.value : rt.CNPJ,
+      CNPJ: cnpjRt.ok ? cnpjRt.valor : rt.CNPJ,
       xContato: rt.xContato,
       email: rt.email,
       fone: digits(rt.fone),
@@ -1307,51 +1309,54 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
     ide,
     emit,
     dest,
-    retirada: local(input.retirada, 'retirada'),
-    entrega: local(input.entrega, 'entrega'),
+    retirada: local(entrada.retirada, 'retirada'),
+    entrega: local(entrada.entrega, 'entrega'),
     autXML,
     det: itens.map((m) => m.det),
     total,
     transp,
     cobr,
     pag,
-    infIntermed: input.infIntermed,
+    infIntermed: entrada.infIntermed,
     infAdic,
-    exporta: input.exporta,
-    compra: input.compra,
-    cana: input.cana,
+    exporta: entrada.exporta,
+    compra: entrada.compra,
+    cana: entrada.cana,
     infRespTec,
-    agropecuario: input.agropecuario,
+    agropecuario: entrada.agropecuario,
   }) as unknown as TNFe_infNFe;
 
   // Regras da SEFAZ que só dependem do documento (ADR 0012).
-  cstComIsento(input, idDest, issues);
-  vencimentos(input, { dhEmi, instante: agora }, issues);
+  cstComIsento(entrada, idDest, issues);
+  vencimentos(entrada, { dhEmi, instante: agora }, issues);
 
   camposForaDoPl(pl.infNFe, inf, 'infNFe', pl.vigencia.pl, issues);
   textosForaDoXml(inf, 'infNFe', issues);
-  if (!issues.empty) return { ok: false, issues: issues.classificadas };
+  if (!issues.empty) return { ok: false, ocorrencias: issues.classificadas };
 
   // Serialização canônica e validação estrita contra o schema do PL vigente, antes de qualquer assinatura.
-  // O serializer recusa com SerializeError o que não cabe no modelo (escolhas exclusivas informadas juntas, por
+  // O serializer recusa com ErroSerializacao o que não cabe no modelo (escolhas exclusivas informadas juntas, por
   // exemplo vagao e balsa): vira ocorrência com o caminho do XML, nunca exceção.
   let xml: string;
   try {
-    xml = `<NFe xmlns="${NFE_NS}">${serialize(pl.infNFe, 'infNFe', inf, NFE_NS)}</NFe>`;
+    xml = `<NFe xmlns="${NFE_NS}">${serializar(pl.infNFe, 'infNFe', inf, NFE_NS)}</NFe>`;
   } catch (e) {
-    if (!(e instanceof SerializeError)) throw e;
-    return { ok: false, issues: [{ path: e.path, code: 'schema', message: e.message, origem: 'montagem' }] };
+    if (!(e instanceof ErroSerializacao)) throw e;
+    return {
+      ok: false,
+      ocorrencias: [{ caminho: e.caminho, code: 'schema', mensagem: e.message, origem: 'montagem' }],
+    };
   }
-  const doc = parseXml(xml);
-  const infEl = firstChild(doc.root, 'infNFe', NFE_NS);
-  const schemaIssues = infEl === undefined ? [] : validate(pl.infNFe, infEl);
+  const doc = lerXml(xml);
+  const infEl = primeiroFilho(doc.raiz, 'infNFe', NFE_NS);
+  const schemaIssues = infEl === undefined ? [] : validar(pl.infNFe, infEl);
   if (schemaIssues.length > 0) {
     return {
       ok: false,
-      issues: schemaIssues.map((i) => ({
-        path: i.path,
+      ocorrencias: schemaIssues.map((i) => ({
+        caminho: i.caminho,
         code: 'schema',
-        message: `${i.code}: ${i.message}`,
+        mensagem: `${i.code}: ${i.mensagem}`,
         origem: 'montagem',
       })),
     };
@@ -1359,14 +1364,14 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
   let supl: NfceSupl | undefined;
   if (nfce) {
     // infNFeSupl (grupo ZX, NT 2025.001 item 04): endereços da UF no dia da emissão, pelo horário de Brasília.
-    const tabela = urlsNfce(emitUf, options.ambiente, diaBrasilia(agora));
-    const urlQr = options.urlQrCode ?? tabela.qrCode;
-    const urlChave = options.urlChave ?? tabela.urlChave;
+    const tabela = urlsNfce(emitUf, opcoes.ambiente, diaBrasilia(agora));
+    const urlQr = opcoes.urlQrCode ?? tabela.qrCode;
+    const urlChave = opcoes.urlChave ?? tabela.urlChave;
     if (urlQr === undefined || !/^https?:\/\//i.test(urlQr)) {
       issues.montagem(
         'urlQrCode',
         'qrcode_invalido',
-        `sem endereço completo do QR Code da NFC-e para ${emitUf} em ${options.ambiente}: informe urlQrCode (data/nfce-urls.json)`,
+        `sem endereço completo do QR Code da NFC-e para ${emitUf} em ${opcoes.ambiente}: informe urlQrCode (data/nfce-urls.json)`,
       );
     }
     if (urlChave === undefined) {
@@ -1377,11 +1382,11 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
       );
     }
     if (urlQr === undefined || urlChave === undefined || !issues.empty)
-      return { ok: false, issues: issues.classificadas };
+      return { ok: false, ocorrencias: issues.classificadas };
     const p = await parametrosQrCode(
       {
         chave,
-        ambiente: options.ambiente,
+        ambiente: opcoes.ambiente,
         tpEmis,
         dhEmi,
         vNF: (inf.total as { ICMSTot: { vNF: string } }).ICMSTot.vNF,
@@ -1395,13 +1400,13 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
     // off-line, com uma assinatura do tamanho da de uma chave RSA de 2048 bits no lugar da que o certificado ainda vai
     // fazer; o `comQrCode` confere de novo com a assinatura verdadeira.
     const suplIssues = conferirSupl(
-      inserirSupl({ xml, nfce: supl } as BuiltNfe, supl.assinar ? ASSINATURA_2048 : undefined),
+      inserirSupl({ xml, nfce: supl } as NfeMontada, supl.assinar ? ASSINATURA_2048 : undefined),
     );
-    if (suplIssues.length > 0) return { ok: false, issues: suplIssues };
+    if (suplIssues.length > 0) return { ok: false, ocorrencias: suplIssues };
   }
   return {
     ok: true,
-    value: {
+    valor: {
       chave,
       id: `NFe${chave}`,
       cNF,
@@ -1418,13 +1423,18 @@ export async function buildNfe(input: NfeInput, options: BuildNfeOptions): Promi
 }
 
 /** Base64 de uma assinatura RSA de 2048 bits (256 bytes): a forma da assinatura do QR Code off-line na montagem. */
-const ASSINATURA_2048 = base64Encode(new Uint8Array(256));
+const ASSINATURA_2048 = codificarBase64(new Uint8Array(256));
 
 /** Ocorrências do `infNFeSupl` do XML contra o schema (`TNFe_infNFeSupl`), como de montagem. */
-function conferirSupl(xml: string): ValidationIssue[] {
-  const el = firstChild(parseXml(xml).root, 'infNFeSupl', NFE_NS);
-  const erros = el === undefined ? [] : validate(TNFe_infNFeSupl as ComplexType, el);
-  return erros.map((i) => ({ path: i.path, code: 'schema', message: `${i.code}: ${i.message}`, origem: 'montagem' }));
+function conferirSupl(xml: string): Ocorrencia[] {
+  const el = primeiroFilho(lerXml(xml).raiz, 'infNFeSupl', NFE_NS);
+  const erros = el === undefined ? [] : validar(TNFe_infNFeSupl as ComplexType, el);
+  return erros.map((i) => ({
+    caminho: i.caminho,
+    code: 'schema',
+    mensagem: `${i.code}: ${i.mensagem}`,
+    origem: 'montagem',
+  }));
 }
 
 const escapeXml = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -1434,43 +1444,43 @@ const escapeXml = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g,
  * certificado que assina a nota; Manual do DANFE NFC-e 6.0, 4.4.2). `undefined` quando o QR Code não leva assinatura
  * (NF-e, emissão normal, versão 2).
  */
-export async function assinaturaQrCode(built: BuiltNfe, signer: Signer): Promise<string | undefined> {
-  return built.nfce?.assinar === true ? assinarParametros(built.nfce.parametros, signer) : undefined;
+export async function assinaturaQrCode(nota: NfeMontada, assinador: Assinador): Promise<string | undefined> {
+  return nota.nfce?.assinar === true ? assinarParametros(nota.nfce.parametros, assinador) : undefined;
 }
 
 /**
  * A NFC-e montada com o `infNFeSupl` (QR Code e `urlChave`) inserido por splice antes do fechamento de `NFe`, pronta
  * para a assinatura. Na versão 3 em contingência off-line, informe a `assinatura` (`assinaturaQrCode`); nos demais
  * casos ela não existe (ZX02-330, rejeição 445; ZX02-334, rejeição 474). Para assinar em três fases (A3, HSM), passe
- * este texto ao `prepareSignature` do `@sinete/core/xml` com o `id` da nota. Na NF-e (modelo 55), devolve o XML como
+ * este texto ao `prepararAssinatura` do `@sinete/core/xml` com o `id` da nota. Na NF-e (modelo 55), devolve o XML como
  * veio: ela não tem `infNFeSupl` (ZX01-10, rejeição 393).
  */
-export function comQrCode(built: BuiltNfe, assinatura?: string): string {
-  const xml = inserirSupl(built, assinatura);
+export function comQrCode(nota: NfeMontada, assinatura?: string): string {
+  const xml = inserirSupl(nota, assinatura);
   // Com a assinatura verdadeira, o qrCode pode passar do tamanho que a montagem conferiu (chave maior que 2048 bits).
   if (assinatura !== undefined) {
     const issues = conferirSupl(xml);
-    if (issues.length > 0) throw new ValidationError('o QR Code da NFC-e não passou no schema', issues);
+    if (issues.length > 0) throw new ErroDeValidacao('o QR Code da NFC-e não passou no schema', issues);
   }
   return xml;
 }
 
-function inserirSupl(built: BuiltNfe, assinatura: string | undefined): string {
+function inserirSupl(built: NfeMontada, assinatura: string | undefined): string {
   const s = built.nfce;
   if (s === undefined) {
-    if (assinatura !== undefined) throw new ConfigError('a NF-e (modelo 55) não tem QR Code');
+    if (assinatura !== undefined) throw new ErroDeConfiguracao('a NF-e (modelo 55) não tem QR Code');
     return built.xml;
   }
   if (s.assinar && assinatura === undefined) {
-    throw new ConfigError(
+    throw new ErroDeConfiguracao(
       'NFC-e em contingência off-line com QR Code versão 3 precisa da assinatura (ZX02-334, rejeição 474)',
     );
   }
   if (!s.assinar && assinatura !== undefined) {
-    throw new ConfigError('este QR Code não leva assinatura (ZX02-330, rejeição 445)');
+    throw new ErroDeConfiguracao('este QR Code não leva assinatura (ZX02-330, rejeição 445)');
   }
   const fim = '</NFe>';
-  if (!built.xml.endsWith(fim)) throw new ConfigError('NFC-e montada fora da forma esperada');
+  if (!built.xml.endsWith(fim)) throw new ErroDeConfiguracao('NFC-e montada fora da forma esperada');
   const qrCode = `${s.base}${s.parametros}${assinatura === undefined ? '' : `|${assinatura}`}`;
   const supl = `<infNFeSupl><qrCode>${escapeXml(qrCode)}</qrCode><urlChave>${escapeXml(s.urlChave)}</urlChave></infNFeSupl>`;
   return built.xml.slice(0, -fim.length) + supl + fim;
@@ -1481,6 +1491,6 @@ function inserirSupl(built: BuiltNfe, assinatura: string | undefined): string {
  * contingência off-line pede); depois, a `Signature` como último filho de `NFe`, tudo por splice, e devolve a string
  * final. É essa string que vai para a SEFAZ e para o banco; nada depois deve reparseá-la para reescrever.
  */
-export async function signNfe(built: BuiltNfe, signer: Signer): Promise<string> {
-  return signXml(comQrCode(built, await assinaturaQrCode(built, signer)), { id: built.id }, signer);
+export async function assinarNfe(nota: NfeMontada, assinador: Assinador): Promise<string> {
+  return assinarXml(comQrCode(nota, await assinaturaQrCode(nota, assinador)), { id: nota.id }, assinador);
 }