@useinvio/nfse-sdk 3.0.0 → 3.2.0

package/docs/guias/cancelar.md

@@ -0,0 +1,70 @@
+# Cancelar uma NFS-e
+
+## Cancelamento (e101101)
+
+```ts
+import { cancelarNfse, RegistrarEventoError } from '@useinvio/nfse-sdk';
+
+try {
+  const evento = await cancelarNfse(
+    {
+      ambiente: 'restrita',
+      chaveAcesso,
+      cMotivo: '1', // 1 = erro na emissão, 2 = serviço não prestado, 9 = outros
+      xMotivo: 'Nota emitida com valor incorreto', // 15 a 255 caracteres
+      // autor: { CNPJ: '...' } // padrão: CNPJ/CPF do titular do certificado
+    },
+    certificado,
+  );
+  console.log(evento.pedRegEventoId, evento.eventoXml);
+} catch (error) {
+  if (error instanceof RegistrarEventoError) console.error(error.status, error.erros);
+  else throw error;
+}
+```
+
+O SDK monta o `pedRegEvento` v1.01, valida contra o XSD oficial, assina
+`infPedReg`, compacta e envia em `pedidoRegistroEventoXmlGZipB64`. Guarde
+`evento.pedRegEventoXml` (o pedido assinado) junto com a resposta.
+
+As constantes `MOTIVO_CANCELAMENTO` e `MOTIVO_SUBSTITUICAO` têm os códigos com
+nomes legíveis, por exemplo `MOTIVO_CANCELAMENTO.servicoNaoPrestado`.
+
+## Cancelamento por substituição (e105102)
+
+Emita primeiro a nota substituta, depois cancele a original apontando para ela:
+
+```ts
+import { cancelarNfsePorSubstituicao, MOTIVO_SUBSTITUICAO } from '@useinvio/nfse-sdk';
+
+await cancelarNfsePorSubstituicao(
+  {
+    chaveAcesso: chaveOriginal,
+    chaveSubstituta,
+    cMotivo: MOTIVO_SUBSTITUICAO.outros,
+    xMotivo: 'Correcao do valor do servico prestado', // opcional
+  },
+  certificado,
+);
+```
+
+## Consultar eventos
+
+- `consultarEvento(chave, TP_EVENTO.cancelamento, certificado)`: SEFIN,
+  `GET /nfse/{chave}/eventos/{tpEvento}/{nSeqEvento}` (`nSeqEvento` padrão 1).
+- `consultarEventosPorChaveAdn(chave, certificado)`: ADN, todos os eventos da nota.
+
+## Montar sem enviar
+
+`buildCancelamentoFromJson(...)` e `buildCancelamentoPorSubstituicaoFromJson(...)`
+devolvem `{ id, xml }` não assinado. `validatePedRegEventoXmlAgainstXsd(xml)`
+confere contra o XSD; `registrarEvento(built, certificado)` assina e envia.
+
+## No cliente
+
+```ts
+await client.invoices.cancel({ chaveAcesso, cMotivo: '2', xMotivo: 'Servico nao foi prestado ao tomador' });
+await client.invoices.cancelBySubstitution({ chaveAcesso, chaveSubstituta, cMotivo: '99' });
+```
+
+Eventos são POSTs e nunca são repetidos automaticamente, mesmo com `retries`.

package/docs/guias/certificado.md

@@ -0,0 +1,88 @@
+# Configurar o certificado A1
+
+Use `NfseCertificate`. Ele lê o `.pfx`/`.p12` uma vez, mantém a chave privada
+fora do objeto e descarta a senha e os bytes do arquivo. `console.log(certificado)`
+e `JSON.stringify(certificado)` mostram só CNPJ/CPF, validade e fingerprint.
+
+## Variáveis de ambiente (recomendado)
+
+```bash
+NFSE_CERT_PATH=./certificado.pfx   # ou NFSE_CERT_BASE64=<PFX em base64>
+NFSE_CERT_PASSWORD=sua-senha       # ou NFSE_CERT_PASSWORD_FILE=/run/secrets/nfse_cert_password
+```
+
+```ts
+import { NfseCertificate } from '@useinvio/nfse-sdk';
+
+const certificado = NfseCertificate.fromEnv();
+console.log(certificado.cnpj, certificado.notAfter, certificado.daysUntilExpiry());
+```
+
+`NFSE_CERT_PASSWORD_FILE` lê a senha de um arquivo, o formato de secrets do
+Docker e do Kubernetes. Nunca versione o `.pfx` nem a senha: o `.gitignore` do
+projeto já ignora `*.pfx`, `*.p12` e `.env*`.
+
+Para gerar o base64 do PFX:
+
+```bash
+base64 -i certificado.pfx | tr -d '\n'
+```
+
+## Outras origens
+
+```ts
+NfseCertificate.fromFile('./certificado.pfx', senha);
+NfseCertificate.fromBase64(pfxBase64, senha);        // aceita quebras de linha e data: URLs
+NfseCertificate.fromPfx(pfxBuffer, senha);           // ex.: PFX vindo do seu cofre de segredos
+NfseCertificate.fromPem({ key, cert, passphrase });  // par extraído com openssl
+```
+
+## Vários emitentes (multi-tenant)
+
+Crie um `NfseCertificate` por emitente e reaproveite-o. Cada certificado tem o
+próprio agente mTLS, então conexões nunca são compartilhadas entre emitentes.
+Guarde o PFX cifrado (KMS, Vault, Secrets Manager) e a senha em um segredo
+separado, e descriptografe só ao criar o objeto.
+
+```ts
+import { assertCertificateForProvider, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const cache = new Map<string, NfseCertificate>();
+
+async function certificadoDoEmitente(cnpj: string): Promise<NfseCertificate> {
+  const cached = cache.get(cnpj);
+  if (cached?.isValidAt()) return cached;
+  const { pfx, senha } = await cofre.buscarCertificado(cnpj); // seu secret manager
+  const certificado = NfseCertificate.fromPfx(pfx, senha);
+  assertCertificateForProvider(certificado, cnpj);
+  cache.set(cnpj, certificado);
+  return certificado;
+}
+```
+
+## Vigência e titular
+
+- A vigência é verificada antes de assinar e de novo antes de enviar.
+- `certificado.daysUntilExpiry()` ajuda a alertar antes do vencimento.
+- `assertCertificateForProvider(certificado, documento)` confere se o CNPJ/CPF do
+  titular (campos ICP-Brasil ou sufixo `NOME:DOCUMENTO` do CN) é o do emitente.
+  É uma chamada explícita: o SDK não resolve procuração nem representação fiscal.
+
+## Erros
+
+Todos lançam `CertificateValidationError` com um `code` estável:
+
+| `code` | Quando |
+|---|---|
+| `CERTIFICATE_INVALID_PASSWORD` | Senha incorreta. |
+| `CERTIFICATE_UNREADABLE` | O conteúdo não é um PFX/PEM válido. |
+| `CERTIFICATE_MISSING`, `CERTIFICATE_PASSWORD_MISSING` | Variáveis de ambiente ausentes em `fromEnv`. |
+| `CERTIFICATE_NOT_YET_VALID`, `CERTIFICATE_EXPIRED` | Fora da vigência. |
+| `CERTIFICATE_HOLDER_MISMATCH` | `assertCertificateForProvider` com CPF/CNPJ diferente do titular. |
+
+## Legado
+
+`loadPfx` e `loadPfxFromBuffer` continuam funcionando, mas retornam a chave
+privada em PEM dentro de um objeto comum. Prefira `NfseCertificate`. Em
+`NfseClient`, `certificate: { content, password }` também é aceito e é
+convertido para `NfseCertificate`.

package/docs/guias/cli.md

@@ -0,0 +1,68 @@
+# Usar pelo terminal
+
+O pacote traz o comando `nfse`. No seu projeto, depois de
+`npm install @useinvio/nfse-sdk`, rode com `npx nfse`. Sem instalar:
+`npx -p @useinvio/nfse-sdk nfse`.
+
+## Em um minuto, sem certificado
+
+```bash
+npx nfse init                    # cria nota.json com valores ilustrativos
+npx nfse validate nota.json      # regras do SDK + XSD oficial, sem enviar
+npx nfse emit nota.json --mock   # emite numa SEFIN simulada, com certificado de teste
+```
+
+Troque CNPJ, municípios, código de serviço e tributação pelos do seu prestador
+antes de emitir de verdade.
+
+## Com o seu certificado
+
+```bash
+export NFSE_CERT_PATH=./certificado.pfx
+export NFSE_CERT_PASSWORD_FILE=./senha.txt   # ou deixe que o nfse pergunte a senha
+
+npx nfse doctor                  # Node.js, motor XSD, certificado e vencimento
+npx nfse emit nota.json          # mostra o resumo e pede confirmação
+npx nfse get <chave> -o nfse.xml
+npx nfse danfse <chave>
+npx nfse cancel <chave> --motivo 1 --justificativa "Nota emitida com valor incorreto"
+```
+
+O ambiente padrão é a produção restrita. `--producao` (ou `NFSE_AMBIENTE=producao`)
+emite notas com validade jurídica e exige digitar `emitir` para confirmar.
+
+## Comandos
+
+| Comando | O que faz |
+|---|---|
+| `init [nota.json]` | Cria um JSON de nota de exemplo. Nunca sobrescreve. |
+| `doctor` | Confere Node.js, motor XSD, certificado e dias até o vencimento. |
+| `cert [arquivo.pfx]` | Titular, CNPJ/CPF, emissor, validade e fingerprint. Nunca mostra a chave. |
+| `validate <nota.json>` | Valida o JSON e o XML contra o XSD oficial. |
+| `xml <nota.json>` | Gera o XML da DPS não assinado (`-o` para salvar). |
+| `emit <nota.json>` | Assina, mostra o resumo, confirma e envia. Após timeout, consulta a DPS antes de qualquer reenvio. |
+| `get <chave>` | Resumo da NFS-e (`-o` salva o XML). |
+| `danfse <chave>` | Salva o PDF do DANFSe. |
+| `cancel <chave>` | Cancela (`--motivo 1\|2\|9 --justificativa "..."`), mostrando a nota antes. |
+| `recover <dpsId>` | Diz se a SEFIN gerou NFS-e para uma DPS. |
+| `explain <código...>` | Mensagem, regra e campo oficiais de códigos de rejeição. |
+| `mcp` | Inicia o [servidor MCP](agentes-ia.md). |
+
+## Opções
+
+| Opção | |
+|---|---|
+| `--producao` | Ambiente de produção. |
+| `--mock` | SEFIN simulada e certificado de teste. Não combina com `--producao`. |
+| `--cert <arquivo>` / `--password-file <arquivo>` | Certificado e senha, no lugar das variáveis de ambiente. |
+| `-o, --output <arquivo>` | Onde salvar XML ou PDF. |
+| `-y, --yes` | Confirma sem perguntar (para scripts). Sem terminal interativo, `emit` e `cancel` exigem `--yes`. |
+| `--json` | Saída em JSON, para scripts e CI. |
+
+## Códigos de saída
+
+| Código | Significado |
+|---|---|
+| `0` | Sucesso (ou cancelado por você na confirmação). |
+| `1` | Erro de entrada, certificado, validação ou rede. |
+| `2` | A SEFIN rejeitou; a explicação oficial de cada código é impressa. |

package/docs/guias/consultar.md

@@ -0,0 +1,54 @@
+# Consultar uma NFS-e e baixar o DANFSe
+
+## Pela chave de acesso
+
+```ts
+import { ConsultaNfseError, obterNfse } from '@useinvio/nfse-sdk';
+
+try {
+  const nota = await obterNfse(chaveAcesso, certificado, 'restrita');
+  console.log(nota.resumo.nNFSe, nota.resumo.cStat, nota.resumo.valores.vLiq);
+  console.log(nota.nfseXml); // XML autorizado, já descompactado
+} catch (error) {
+  if (error instanceof ConsultaNfseError && error.notFound) console.log('NFS-e não existe neste ambiente');
+  else throw error;
+}
+```
+
+`resumo` (`NfseResumo`) traz:
+
+| Campo | Conteúdo |
+|---|---|
+| `chaveAcesso`, `nNFSe`, `nDFSe` | Identificação da nota. |
+| `cStat`, `dhProc` | Situação e data/hora de processamento. |
+| `ambiente` | `restrita` ou `producao`, lido do `tpAmb` da DPS. |
+| `emitente`, `tomador` | `CNPJ`/`CPF`/`NIF`, `IM`, `xNome`. |
+| `dps` | `id`, `serie`, `nDPS`, `dhEmi`, `dCompet` da DPS de origem. |
+| `valores` | `vServ`, `vBC`, `pAliqAplic`, `vISSQN`, `vTotalRet`, `vLiq`. |
+| `xLocEmi`, `xLocPrestacao`, `cLocIncid`, `xLocIncid`, `xTribNac` | Locais e descrição da tributação. |
+
+Os valores ficam como strings, exatamente como no XML. Para ler um XML que você
+já tem, use `lerNfse(xml)`. No cliente: `client.invoices.retrieve(chave)`.
+
+A resposta crua (`{ status, body }`) continua em `consultarNfse(...)` e
+`client.invoices.get(...)`.
+
+## Pelo Id da DPS
+
+`consultarDps(dpsId, certificado)` chama `GET /dps/{id}` e devolve a chave de
+acesso gerada. Para o fluxo completo depois de um timeout, use
+[`recuperarNfsePorDps`](recuperar-emissao.md).
+
+## DANFSe em PDF
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import { baixarDanfse } from '@useinvio/nfse-sdk';
+
+const danfse = await baixarDanfse(chaveAcesso, certificado, 'restrita');
+if (danfse.pdf) await writeFile(`danfse-${chaveAcesso}.pdf`, danfse.pdf);
+else console.error(danfse.status, danfse.body);
+```
+
+O PDF oficial vem do ADN (`GET /danfse/{chave}`). No cliente:
+`client.invoices.danfse(chave)`.

package/docs/guias/emitir.md

@@ -0,0 +1,172 @@
+# Emitir uma NFS-e
+
+Há três entradas. Todas assinam, compactam, enviam por mTLS e devolvem
+`ResultadoEmissaoNota` (`chaveAcesso`, `dpsId`, `nfseXml`, `status`, `body`).
+
+| Situação | Use |
+|---|---|
+| Você monta os dados e quer que o SDK gere o XML | `emitirNfse(notaJson, certificado)` |
+| Prefere configurar certificado, ambiente e defaults uma vez | `new NfseClient(...)` e `client.invoices.create(...)` |
+| Outro sistema já gera o XML da DPS | `emitirNfse(xmlString, certificado)` |
+
+## A partir de JSON declarativo
+
+A referência de campos está em [JSON_MAPPING.md](../../JSON_MAPPING.md) e as
+combinações fiscais aceitas em [FISCAL_MATRIX.md](../FISCAL_MATRIX.md). O
+builder valida formatos e combinações mínimas antes de gerar XML, mas não
+escolhe códigos fiscais por você.
+
+```ts
+import { emitirNfse, NfseCertificate, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+
+const nota: DpsJsonRequest = {
+  ambiente: 'restrita',
+  prestador: {
+    cnpj: '12345678000195',
+    cLocEmi: '4106902',
+    serie: '1601',
+    opSimpNac: '1',
+    regEspTrib: '0',
+  },
+  servico: {
+    cTribNac: '010201',
+    xDescServ: 'Desenvolvimento de software',
+    cLocPrestacao: '4106902',
+    cNBS: '115022000',
+  },
+  emissao: {
+    nDPS: '1',
+    dhEmi: '2026-06-15T10:30:00-03:00',
+    dCompet: '2026-06-01',
+    valores: { vServ: '1500.00' },
+    tributacaoMunicipal: {
+      tribISSQN: '1',
+      tpRetISSQN: '1',
+    },
+    tributacaoFederal: {
+      piscofins: { CST: '07' },
+    },
+    totTrib: {
+      pTotTribFed: '0.00',
+      pTotTribEst: '0.00',
+      pTotTribMun: '5.00',
+    },
+  },
+};
+
+const resultado = await emitirNfse(nota, NfseCertificate.fromEnv());
+```
+
+> `pTotTribFed`, `pTotTribEst` e `pTotTribMun` são percentuais com duas casas
+> (ex.: `"5.00"`), diferentes das alíquotas com quatro casas (`pAliq`). O shape
+> simplificado legado de `tribNac` é rejeitado: IBS/CBS exige o bloco RTC
+> `IBSCBS`, ainda não implementado.
+
+## Com o cliente
+
+O `NfseClient` usa os mesmos campos (`prestador`, `servico`, `emissao`). Os
+`defaults` seguem o mesmo formato e podem ser sobrescritos em cada chamada.
+
+```ts
+import { NfseCertificate, NfseClient } from '@useinvio/nfse-sdk';
+
+const client = new NfseClient({
+  environment: 'sandbox',
+  certificate: NfseCertificate.fromEnv(),
+  defaults: {
+    prestador: {
+      cnpj: '12345678000195',
+      cLocEmi: '4106902',
+      serie: '1601',
+      opSimpNac: '1',
+      regEspTrib: '0',
+    },
+    servico: {
+      cTribNac: '010201',
+      xDescServ: 'Servico ficticio de desenvolvimento de software',
+      cLocPrestacao: '4106902',
+    },
+  },
+});
+
+const invoice = await client.invoices.create({
+  emissao: {
+    nDPS: '1',
+    valores: { vServ: '1000.00' },
+    tomador: {
+      CPF: '00000000000',
+      xNome: 'Cliente Exemplo',
+      end: {
+        endNac: { cMun: '4106902', CEP: '80010000' },
+        xLgr: 'Rua Exemplo', nro: '100', xBairro: 'Centro',
+      },
+    },
+    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
+    tributacaoFederal: { piscofins: { CST: '07' } },
+    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
+  },
+});
+```
+
+`environment: 'sandbox'` é alias de `restrita`; `production`, de `producao`.
+`client.invoices.buildDpsJson(...)` devolve o JSON combinado sem assinar nem enviar.
+
+## A partir de XML pronto
+
+```ts
+const resultado = await emitirNfse(dpsXml, certificado, { ambiente: 'restrita' });
+```
+
+O XML precisa ter `Id` válido em `<infDPS>` e `tpAmb` igual ao ambiente de envio.
+`options.dpsId` só seleciona a referência da assinatura; não corrige um XML
+incompleto nem dispensa o XSD.
+
+## Inspecionar o XML antes de enviar
+
+```ts
+import { buildDpsFromJson, validateDpsXmlAgainstXsd } from '@useinvio/nfse-sdk';
+
+const { id, xml } = buildDpsFromJson(nota); // XML não assinado
+validateDpsXmlAgainstXsd(xml);               // lança DpsXsdValidationError se violar o XSD
+```
+
+Para validar o JSON sem lançar erro, use `validateDpsJsonRequest(nota)`: retorna
+`valid`, `issues`, `warnings` e uma cópia `normalizedPayload`.
+
+## Preparar e transmitir separadamente
+
+Salve a DPS assinada antes de enviar; assim uma queda de conexão nunca deixa
+você sem saber o que foi transmitido.
+
+```ts
+import { prepararNota, transmitirNotaPreparada } from '@useinvio/nfse-sdk';
+
+const preparada = prepararNota(nota, certificado); // valida, assina e verifica a assinatura
+await salvar(preparada.dpsId, preparada.signedXml);
+const resultado = await transmitirNotaPreparada(preparada, certificado);
+```
+
+## Série e número da DPS
+
+A SEFIN identifica uma DPS por prestador, município, `serie` e `nDPS`. Mantenha
+uma `serie` fixa (em `prestador.serie` ou por emissão em `emissao.serie`) e
+incremente `nDPS` a cada nova DPS: `1601/1`, `1601/2`, `1601/3`...
+
+O Emissor Web usa séries como `70000`. Para emissão via API, use uma série
+válida para API (ex.: `1601`) e controle o `nDPS` na sua aplicação.
+
+## Regras que o SDK aplica
+
+- Campos opcionais devem ser omitidos ou `undefined`; string vazia, `null` e
+  tipos incorretos são rejeitados.
+- Valores monetários são arredondados para duas casas; valores de serviço que
+  arredondam para zero são rejeitados.
+- Divergências entre `vServ` e a conversão cambial viram `warnings`, preservando
+  o valor explícito.
+- Ambiente para JSON: `options.ambiente` → `request.ambiente` → `restrita`.
+- HTTP 2xx sem XML autorizado e chave de 50 dígitos consistente gera
+  `EmitirNotaError` com `INVALID_AUTHORIZATION_RESPONSE`. Concilie antes de
+  reenviar (veja [Recuperar uma emissão](recuperar-emissao.md)).
+
+Exemplos testados: [`examples/payloads.ts`](../../examples/payloads.ts) traz um
+cenário nacional e um de exportação.

package/docs/guias/recuperar-emissao.md

@@ -0,0 +1,33 @@
+# Recuperar uma emissão após timeout
+
+`POST /nfse` não é idempotente, por isso o SDK **nunca** repete uma emissão
+automaticamente. Se a conexão cair sem resposta, a nota pode ter sido
+autorizada ou não. Pergunte à SEFIN antes de reenviar:
+
+```ts
+import { prepararNota, recuperarNfsePorDps, transmitirNotaPreparada } from '@useinvio/nfse-sdk';
+
+const nota = prepararNota(dps, certificado); // persista nota.dpsId e nota.signedXml antes de enviar
+try {
+  return await transmitirNotaPreparada(nota, certificado, { timeoutMs: 30_000 });
+} catch (error) {
+  if (error instanceof Error && error.name === 'EmitirNotaError') throw error; // rejeição real
+  const existente = await recuperarNfsePorDps(nota.dpsId, certificado, nota.ambiente, { retries: 3 });
+  return existente ?? transmitirNotaPreparada(nota, certificado); // null: a DPS não chegou à SEFIN
+}
+```
+
+`recuperarNfsePorDps` chama `GET /dps/{id}` e, se a DPS foi processada,
+`GET /nfse/{chave}`. O resultado é o mesmo de [`obterNfse`](consultar.md):
+
+| Resultado | Significado | O que fazer |
+|---|---|---|
+| `NfseConsultada` | A nota foi autorizada antes da queda. | Use o resultado; não reenvie. |
+| `null` | A SEFIN não conhece a DPS. | Reenvie a **mesma** DPS assinada (mesmo `Id`). |
+| `ConsultaNfseError` | A consulta falhou. | Tente de novo mais tarde; não reenvie às cegas. |
+
+Reenvie sempre a mesma DPS assinada, nunca uma DPS nova: o `Id` (prestador,
+série e número) identifica a DPS na SEFIN, e um número novo geraria outra nota.
+
+No cliente: `client.invoices.recover(dpsId)`. Exemplo completo em
+[`examples/recover-emission.ts`](../../examples/recover-emission.ts).

package/docs/guias/rejeicoes.md

@@ -0,0 +1,70 @@
+# Tratar rejeições e erros
+
+Cada etapa lança um erro tipado. Use `instanceof` para decidir o que fazer.
+
+```ts
+import {
+  CertificateValidationError,
+  DpsFiscalValidationError,
+  DpsXsdValidationError,
+  EmitirNotaError,
+  emitirNfse,
+} from '@useinvio/nfse-sdk';
+
+try {
+  await emitirNfse(nota, certificado);
+} catch (error) {
+  if (error instanceof DpsFiscalValidationError) {
+    // JSON inválido antes de gerar XML: corrija a entrada
+    for (const issue of error.issues) console.log(issue.code, issue.path, issue.message);
+  } else if (error instanceof DpsXsdValidationError) {
+    // XML viola o XSD oficial: error.details traz o diagnóstico do libxml2
+  } else if (error instanceof CertificateValidationError) {
+    // senha, leitura ou vigência do A1: error.code
+  } else if (error instanceof EmitirNotaError) {
+    // a SEFIN respondeu com rejeição (ou com resposta 2xx incompleta)
+    for (const rejeicao of error.erros) {
+      console.log(rejeicao.Codigo, rejeicao.Descricao, rejeicao.Complemento);
+    }
+  } else {
+    throw error; // rede, timeout, XsdEngineUnavailableError: o resultado é incerto
+  }
+}
+```
+
+## Rejeição da SEFIN ou resultado incerto?
+
+| Erro | A nota foi emitida? | Ação |
+|---|---|---|
+| `DpsFiscalValidationError`, `DpsXsdValidationError`, `CertificateValidationError` | Não: nada foi enviado. | Corrija a entrada ou o certificado. |
+| `EmitirNotaError` com `status` 4xx | Não. | Corrija conforme `erros` e envie de novo. |
+| `EmitirNotaError` com `INVALID_AUTHORIZATION_RESPONSE` | Talvez. | [Recupere pela DPS](recuperar-emissao.md) antes de reenviar. |
+| Erro de rede ou timeout | Talvez. | [Recupere pela DPS](recuperar-emissao.md) antes de reenviar. |
+| `XsdEngineUnavailableError` | Não: falha local de infraestrutura. | Tente de novo; não é rejeição fiscal. |
+
+## Explicar um código
+
+```ts
+import { explicarErros, explicarRejeicao } from '@useinvio/nfse-sdk';
+
+explicarRejeicao('E0014');
+// { codigo: 'E0014', conhecida: true, mensagemOficial: 'Conjunto de Série, Número, ...',
+//   regra: '...', campo: 'NFSe/infNFSe/DPS/infDPS/serie', nivel: 1, fonte: { documento, url } }
+
+explicarErros(error.erros); // uma explicação por erro de EmitirNotaError ou RegistrarEventoError
+```
+
+O catálogo tem as regras de rejeição dos anexos oficiais publicados em
+gov.br/nfse (Anexo I v1.01 de 09/02/2026, DPS e NFS-e; Anexo II v1.01 de
+22/01/2026, eventos), com o texto oficial sem alterações. Um código fora do
+catálogo volta com `conhecida: false`: não há causa inventada.
+`buscarRejeicao(codigo)` e `listarRejeicoes()` dão acesso direto às regras.
+Cada código também tem uma página: [docs/rejeicoes](../rejeicoes/README.md). No
+terminal: `npx nfse explain E0014`.
+
+## Normalizar o corpo da resposta
+
+`extrairErros(body)` normaliza os formatos de erro da SEFIN (`erros`, `Erros`,
+`erro`, objeto único) para `{ Codigo, Descricao, Complemento? }`.
+
+A lista completa de classes e códigos está em [Erros](../referencia/erros.md).

package/docs/guias/testes.md

@@ -0,0 +1,79 @@
+# Testar sem certificado e sem rede
+
+`@useinvio/nfse-sdk/testing` traz duas peças para testar a sua integração de
+ponta a ponta, no CI, sem certificado A1 real e sem chamar a SEFIN:
+
+- `createTestCertificate()`: um certificado A1 autoassinado com o CNPJ (ou CPF)
+  nos mesmos campos ICP-Brasil de um certificado real;
+- `installMockSefin()`: uma SEFIN e um ADN simulados dentro do processo. Toda
+  chamada do SDK é respondida localmente até `restore()`.
+
+```ts
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { cancelarNfse, emitirNfse, obterNfse } from '@useinvio/nfse-sdk';
+import { createTestCertificate, installMockSefin } from '@useinvio/nfse-sdk/testing';
+
+const { certificate } = createTestCertificate({ cnpj: '12345678000195' });
+
+test('emite e cancela', async (t) => {
+  const mock = installMockSefin();
+  t.after(() => mock.restore());
+
+  const { chaveAcesso } = await emitirNfse(minhaNota, certificate);
+  const { resumo } = await obterNfse(chaveAcesso, certificate);
+  assert.equal(resumo.emitente.CNPJ, '12345678000195');
+
+  await cancelarNfse({ chaveAcesso, cMotivo: '1', xMotivo: 'Teste de cancelamento' }, certificate);
+  assert.equal(mock.notas.get(chaveAcesso)?.cancelada, true);
+});
+```
+
+## O que a SEFIN simulada verifica
+
+- A DPS e o pedido de evento contra o XSD oficial (como a SEFIN, responde `E1235`).
+- A assinatura XMLDSIG com o certificado da chamada (`E0714`).
+- O ambiente do XML contra o ambiente de envio (`E0006`, `E1845`).
+- DPS repetida (`E0014`) e cancelamento repetido (`E0840`, `E0845`).
+
+As mensagens vêm do catálogo oficial, como na SEFIN. A simulação **não** aplica
+regras fiscais nem municipais: uma nota aceita pelo mock ainda pode ser rejeitada
+na produção restrita.
+
+Rotas simuladas: emissão, consulta por chave e por DPS, registro e consulta de
+eventos, DANFSe (um PDF mínimo), distribuição por NSU, eventos por chave e
+parâmetros municipais (respostas genéricas).
+
+## Simular falhas
+
+```ts
+mock.rejectNext('E0312');          // próxima chamada rejeitada com a mensagem oficial do código
+mock.rejectNext([{ Codigo: 'E0001', Descricao: '...' }], { status: 400, path: /^\/nfse$/ });
+mock.failNext();                   // erro de rede antes de a SEFIN processar
+mock.dropResponseNext();           // a SEFIN processa, mas a resposta se perde
+mock.route('GET', /^\/parametrizacao\/.+\/aliquota$/, () => ({ status: 200, body: '{"aliquota":2}' }));
+```
+
+`dropResponseNext` é o cenário de [recuperação após timeout](recuperar-emissao.md):
+a nota existe na SEFIN, mas a sua aplicação não recebeu a chave.
+
+## Inspecionar
+
+- `mock.notas`: notas emitidas, por chave (`nfseXml`, `dpsId`, `cancelada`, `eventos`).
+- `mock.requests`: cada chamada recebida, com método, host, caminho e status.
+
+## Certificados de teste
+
+```ts
+createTestCertificate({ cpf: '39053344705' });     // e-CPF
+createTestCertificate({ validDays: -1 });          // vencido: testa CERTIFICATE_EXPIRED
+const { pfx, password } = createTestCertificate(); // bytes do PFX para testar fromPfx/fromEnv
+```
+
+O certificado é autoassinado e não é ICP-Brasil: a SEFIN real o recusa.
+
+## No servidor MCP
+
+`NFSE_MCP_MOCK=1` liga a mesma SEFIN simulada dentro do servidor MCP, para
+experimentar as ferramentas de emissão sem certificado. Veja
+[Agentes de IA e MCP](agentes-ia.md).

package/docs/guias/timeouts.md

@@ -0,0 +1,33 @@
+# Timeouts, novas tentativas e cancelamento
+
+Toda função de rede aceita um último argumento `SefinRequestOptions`:
+
+| Opção | Padrão | Efeito |
+|---|---|---|
+| `timeoutMs` | `60000` | Tempo máximo de cada requisição. |
+| `retries` | `0` | Novas tentativas com backoff exponencial (0,5 s, 1 s, 2 s, até 4 s, com jitter). |
+| `signal` | – | `AbortSignal` que cancela a requisição e as tentativas pendentes. |
+
+`retries` vale só para GETs e só para falhas transitórias: erro de rede e HTTP
+429, 502, 503 ou 504. Emissão (`POST /nfse`) e eventos nunca são repetidos,
+mesmo que você passe `retries`, porque não são idempotentes. Para emissão, veja
+[Recuperar uma emissão após timeout](recuperar-emissao.md).
+
+```ts
+import { obterNfse } from '@useinvio/nfse-sdk';
+
+const nota = await obterNfse(chaveAcesso, certificado, 'producao', {
+  timeoutMs: 15_000,
+  retries: 3,
+  signal: AbortSignal.timeout(60_000),
+});
+```
+
+No cliente, configure uma vez para todas as chamadas:
+`new NfseClient({ ..., request: { timeoutMs: 30_000, retries: 2 } })`.
+
+## Métricas de latência
+
+Com `NFSE_SEFIN_LATENCY_METRICS=1`, o SDK emite uma métrica por requisição
+(operação, ambiente, status e duração) para o observador registrado em
+`setSefinRequestObserver`. O guia completo está em [METRICS.md](../METRICS.md).