@useinvio/nfse-sdk 3.0.0 → 3.2.0

package/docs/referencia/ambientes.md

@@ -0,0 +1,35 @@
+# Ambientes
+
+| Chave | Alias no `NfseClient` | SEFIN (emissão, consulta, eventos) | ADN (DANFSe, distribuição, parâmetros) |
+|---|---|---|---|
+| `restrita` (padrão) | `sandbox` | `https://sefin.producaorestrita.nfse.gov.br/SefinNacional` | `https://adn.producaorestrita.nfse.gov.br` |
+| `producao` | `production` | `https://sefin.nfse.gov.br/SefinNacional` | `https://adn.nfse.gov.br` |
+
+```ts
+import { resolveAdnBaseUrl, resolveSefinBaseUrl, TP_AMB } from '@useinvio/nfse-sdk';
+
+resolveSefinBaseUrl('restrita'); // URL da SEFIN
+resolveAdnBaseUrl('producao');   // URL do ADN
+TP_AMB.restrita;                 // '2', valor de <tpAmb> no XML
+```
+
+- `restrita` é a produção restrita oficial: as notas não têm validade jurídica,
+  mas passam pelas mesmas validações. Use-a para testes e homologação.
+- O `tpAmb` dentro do XML precisa coincidir com o ambiente de envio; o SDK
+  recusa a divergência antes de transmitir.
+- No `NfseClient`, o ambiente segue: opção da chamada → `defaults.ambiente` →
+  `environment` do construtor. O cliente não lembra o ambiente da última emissão.
+
+## Endpoints usados
+
+| Operação | Método e caminho | Serviço |
+|---|---|---|
+| Emitir | `POST /nfse` | SEFIN |
+| Consultar NFS-e | `GET /nfse/{chave}` | SEFIN |
+| Consultar DPS | `GET /dps/{id}` | SEFIN |
+| Registrar evento | `POST /nfse/{chave}/eventos` | SEFIN |
+| Consultar evento | `GET /nfse/{chave}/eventos/{tpEvento}/{nSeqEvento}` | SEFIN |
+| DANFSe | `GET /danfse/{chave}` | ADN |
+| Distribuição | `GET /contribuintes/DFe/{nsu}` | ADN |
+| Eventos por chave | `GET /contribuintes/NFSe/{chave}/Eventos` | ADN |
+| Parâmetros municipais | `GET /parametrizacao/...` | ADN |

package/docs/referencia/api.md

@@ -0,0 +1,137 @@
+# Referência da API
+
+Tudo é importado da raiz do pacote, exceto as ferramentas de agente
+(`@useinvio/nfse-sdk/agent`). `certificado` é um `NfseCertificate` (ou o legado
+`PfxMaterial`); `ambiente` é `'restrita' | 'producao'` e o padrão é `restrita`;
+`options` é [`SefinRequestOptions`](../guias/timeouts.md).
+
+## Cliente
+
+| API | Descrição |
+|---|---|
+| `new NfseClient({ environment?, certificate, defaults?, request? })` | Configura certificado, ambiente, defaults do JSON e opções de transporte uma vez. |
+| `client.invoices.create(input)` / `.buildDpsJson(input)` | Emite, ou só combina o JSON com os defaults. |
+| `client.invoices.retrieve(chave)` / `.get(chave)` | Consulta tipada / crua. |
+| `client.invoices.getByDpsId(dpsId)` / `.recover(dpsId)` | Consulta pela DPS / recuperação após timeout. |
+| `client.invoices.cancel(input)` / `.cancelBySubstitution(input)` | Eventos e101101 / e105102. |
+| `client.invoices.danfse(chave)` | PDF do DANFSe. |
+| `client.events.get(chave, tpEvento, nSeq?)` / `.listByAccessKey(chave)` | Eventos (SEFIN / ADN). |
+| `client.distribution.byNsu(nsu, opts?)` | Distribuição por NSU (ADN). |
+| `client.municipalParameters.agreement/rate/rateHistory/specialRegimes/withholdings/benefit` | Parâmetros municipais (ADN). |
+
+## Emissão
+
+| Função | Descrição |
+|---|---|
+| `emitirNfse(input, certificado, options?)` | Emite a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
+| `prepararNota(input, certificado, options?)` | Valida, assina e verifica a assinatura, sem enviar. Retorna `NotaPreparada`. |
+| `transmitirNotaPreparada(nota, certificado, options?)` | Envia uma `NotaPreparada`. |
+| `buildDpsFromJson(nota)` / `buildDpsId(...)` | Monta o XML não assinado / o Id de 45 caracteres. |
+| `validateDpsJsonRequest(nota)` / `assertValidDpsJsonRequest(nota)` | Valida o JSON, sem lançar / lançando `DpsFiscalValidationError`. |
+| `validateDpsXmlAgainstXsd(xml)` | Valida a DPS contra o XSD oficial v1.01. |
+| `DPS_JSON_REQUEST_SCHEMA` | JSON Schema 2020-12 do `DpsJsonRequest`. |
+
+## Consulta
+
+| Função | Descrição |
+|---|---|
+| `obterNfse(chave, certificado, ambiente?, options?)` | `GET /nfse/{chave}` decodificado: `{ chaveAcesso, nfseXml, resumo }`. |
+| `recuperarNfsePorDps(dpsId, certificado, ambiente?, options?)` | `GET /dps/{id}` + `GET /nfse/{chave}`; `null` se a DPS não existe. |
+| `lerNfse(xml)` | Lê um XML de NFS-e autorizada em `NfseResumo`. |
+| `decodificarRespostaNfse(status, body)` | Decodifica uma resposta crua de `GET /nfse/{chave}`. |
+| `consultarNfse(...)` / `consultarDps(...)` | Respostas cruas `{ status, body }`. |
+| `baixarDanfse(chave, certificado, ambiente?, options?)` | PDF do DANFSe (ADN). |
+
+## Eventos
+
+| Função | Descrição |
+|---|---|
+| `cancelarNfse(input, certificado, options?)` | Cancelamento e101101. |
+| `cancelarNfsePorSubstituicao(input, certificado, options?)` | Cancelamento por substituição e105102. |
+| `buildCancelamentoFromJson(input)` / `buildCancelamentoPorSubstituicaoFromJson(input)` | Monta o pedido sem assinar. |
+| `registrarEvento(built, certificado, options?)` | Valida, assina e envia um pedido montado. |
+| `validatePedRegEventoXmlAgainstXsd(xml)` | Valida um pedido de evento contra o XSD. |
+| `consultarEvento(chave, tpEvento, certificado, ambiente?, { nSeqEvento? })` | Consulta um evento (SEFIN). |
+| `enviarEvento(xmlGZipB64, certificado, chave, ambiente?)` | Envia um pedido já assinado e compactado. |
+| `TP_EVENTO`, `MOTIVO_CANCELAMENTO`, `MOTIVO_SUBSTITUICAO` | Códigos com nomes legíveis. |
+
+## ADN
+
+`distribuirDfePorNsu`, `consultarEventosPorChaveAdn`, `consultarConvenio`,
+`consultarAliquota`, `consultarHistoricoAliquotas`, `consultarRegimesEspeciais`,
+`consultarRetencoes`, `consultarBeneficio`. Assinaturas e endpoints em
+[Distribuição e parâmetros municipais](../guias/adn.md).
+
+## Linha de comando
+
+`nfse` (bin): `init`, `doctor`, `cert`, `validate`, `xml`, `emit`, `get`, `danfse`,
+`cancel`, `recover`, `explain`, `mcp`. Veja [Usar pelo terminal](../guias/cli.md).
+
+## Rejeições
+
+| Função | Descrição |
+|---|---|
+| `explicarRejeicao(codigoOuErro)` | Mensagem, regra, campo e nível oficiais de um código, ou `conhecida: false`. |
+| `explicarErros(erros)` | Explica todos os erros de uma rejeição. |
+| `buscarRejeicao(codigo)` / `listarRejeicoes()` | Acesso direto ao catálogo oficial. |
+| `REJEICOES_FONTES` | Anexos oficiais usados no catálogo, com URL. |
+
+Uma página por código: [docs/rejeicoes](../rejeicoes/README.md).
+
+## Testes (`@useinvio/nfse-sdk/testing`)
+
+| Função | Descrição |
+|---|---|
+| `createTestCertificate(opts?)` | Certificado A1 de teste com CNPJ/CPF nos campos ICP-Brasil. |
+| `installMockSefin(opts?)` | SEFIN e ADN simulados no processo; `rejectNext`, `failNext`, `dropResponseNext`, `route`, `restore`. |
+
+Guia: [Testar sem certificado](../guias/testes.md).
+
+## Agentes e MCP
+
+| API | Descrição |
+|---|---|
+| `nfseAgentTools` (`/agent`) | Ferramentas só de leitura. |
+| `createNfseAgentToolkit({ allowWrite?, confirmationTtlMs? })` (`/agent`) | Leitura + emissão e cancelamento em duas etapas. |
+| `toAgentIssues(error)` (`/agent`) | Converte erros do SDK em issues para o modelo. |
+| `createNfseMcpServer(opts)` / `runNfseMcpStdio(opts?)` (`/mcp`) | Servidor MCP sem dependências. |
+| `nfse-mcp` (bin) | `npx -y @useinvio/nfse-mcp` ou `npx -y -p @useinvio/nfse-sdk nfse-mcp`. |
+
+Guia: [Agentes de IA e MCP](../guias/agentes-ia.md).
+
+## Certificado
+
+| API | Descrição |
+|---|---|
+| `NfseCertificate.fromEnv/fromFile/fromBase64/fromPfx/fromPem` | Carrega o A1 sem expor a chave privada. |
+| `certificado.cnpj`, `.cpf`, `.notBefore`, `.notAfter`, `.fingerprintSha256` | Metadados públicos. |
+| `certificado.isValidAt(data?)`, `.daysUntilExpiry()`, `.destroy()` | Vigência e descarte do agente mTLS. |
+| `assertCertificateValidity(certificado, now?)` | Vigência; aplicada antes de assinar e de enviar. |
+| `assertCertificateForProvider(certificado, documento, now?)` | Vigência e titular. |
+| `NFSE_CERT_ENV` | Nomes das variáveis de ambiente lidas por `fromEnv`. |
+| `loadPfx`, `loadPfxFromBuffer` | Legado: retornam a chave em PEM. |
+
+## Baixo nível
+
+| Função | Descrição |
+|---|---|
+| `signDps(xml, dpsId, certificado)` / `signEnveloped(xml, id, elemento, certificado)` | Assinatura XMLDSIG. |
+| `verifyDps(xml, certPem)` | Verifica uma assinatura. |
+| `gzipBase64(xml)` / `gunzipBase64(b64)` / `gunzipBase64Flexivel(b64)` | Compactação. |
+| `transmitirDpsCompactada(b64, certificado, ambiente?, options?)` | `POST /nfse` cru. |
+| `extrairErros(body)` | Normaliza erros da SEFIN. |
+| `assertChaveAcesso(chave)` / `assertDpsId(id)` | Validação de identificadores. |
+| `resolveSefinBaseUrl(ambiente)` / `resolveAdnBaseUrl(ambiente)` | URLs base. |
+| `setSefinRequestObserver(fn)` / `createSefinLatencyTracker(opts?)` | Métricas de latência ([METRICS.md](../METRICS.md)). |
+
+## Constantes
+
+`SEFIN_BASE_URL`, `ADN_BASE_URL`, `TP_AMB`, `DEFAULT_AMBIENTE`, `DPS_SCHEMA_VERSION`.
+
+## Tipos
+
+Os tipos públicos estão em [`index.ts`](../../index.ts). Os principais:
+`DpsJsonRequest`, `ResultadoEmissaoNota`, `NotaPreparada`, `NfseConsultada`,
+`NfseResumo`, `ResultadoEvento`, `CancelamentoNfseInput`,
+`CancelamentoPorSubstituicaoInput`, `SefinRequestOptions`, `SefinResposta`,
+`SefinErro`, `CertificateInput`, `NfseClientOptions`.

package/docs/referencia/erros.md

@@ -0,0 +1,55 @@
+# Erros
+
+Todos os erros estendem `Error` e têm `name` igual ao nome da classe. Como
+tratar cada um: [Tratar rejeições e erros](../guias/rejeicoes.md).
+
+## Antes de enviar (nada chegou à SEFIN)
+
+| Classe | Campos | Quando |
+|---|---|---|
+| `DpsFiscalValidationError` | `issues`, `report` | O JSON da DPS é inválido. Cada issue tem `code`, `path`, `severity`, `source`, `message`, `suggestion?`. |
+| `DpsXsdValidationError` | `details` | O XML da DPS viola o XSD oficial v1.01. |
+| `PedRegEventoXsdValidationError` | `details` | O pedido de evento viola o XSD oficial. |
+| `EventoInvalidoError` | `code = 'EVENTO_INVALID'`, `field` | Entrada de evento inválida (chave, motivo, autor). |
+| `CertificateValidationError` | `code` | Problema no A1; códigos abaixo. |
+| `ChaveAcessoInvalidaError` | `code = 'CHAVE_ACESSO_INVALID_FORMAT'`, `chaveAcesso` | Chave sem exatamente 50 dígitos. |
+| `SefinParametroInvalidoError` | `code = 'SEFIN_PARAMETER_INVALID'`, `field`, `value` | Id da DPS, tipo de evento, NSU, município ou outro parâmetro de caminho com formato errado. |
+| `XsdEngineUnavailableError` | `cause` | O motor XSD (WebAssembly) falhou. Infraestrutura, não rejeição fiscal. |
+
+### Códigos de `CertificateValidationError`
+
+| `code` | Quando |
+|---|---|
+| `CERTIFICATE_INVALID_PASSWORD` | Senha incorreta. |
+| `CERTIFICATE_UNREADABLE` | O conteúdo não é um PFX/PEM válido. |
+| `CERTIFICATE_MISSING` | `fromEnv` sem `NFSE_CERT_PATH` nem `NFSE_CERT_BASE64`. |
+| `CERTIFICATE_PASSWORD_MISSING` | `fromEnv` sem `NFSE_CERT_PASSWORD` nem `NFSE_CERT_PASSWORD_FILE`. |
+| `CERTIFICATE_NOT_YET_VALID` | Antes de `notBefore`. |
+| `CERTIFICATE_EXPIRED` | Depois de `notAfter`. |
+| `CERTIFICATE_HOLDER_MISMATCH` | O titular não é o CPF/CNPJ informado. |
+
+## Depois de enviar (a SEFIN respondeu)
+
+| Classe | Campos | Quando |
+|---|---|---|
+| `EmitirNotaError` | `status`, `erros`, `dpsId`, `body` | Emissão rejeitada, ou HTTP 2xx sem XML autorizado (`INVALID_AUTHORIZATION_RESPONSE`). |
+| `RegistrarEventoError` | `status`, `erros`, `pedRegEventoId`, `body` | Evento rejeitado. |
+| `ConsultaNfseError` | `status`, `erros`, `body`, `notFound` | Consulta falhou; `notFound` para HTTP 404. |
+
+`erros` é uma lista de `SefinErro` (`Codigo`, `Descricao`, `Complemento?`) com o
+código oficial da SEFIN preservado.
+
+## Erros de rede
+
+Timeouts e falhas de conexão chegam como o `Error` original do Node (por exemplo
+`ECONNRESET` ou `SEFIN request timed out after 60000ms`). Depois de um desses
+numa emissão, o resultado é incerto: [recupere pela DPS](../guias/recuperar-emissao.md).
+
+## Ferramentas de agente
+
+`toAgentIssues(error)` converte os erros acima em issues com `code`, `path`,
+`severity`, `source` e `suggestion`. Códigos próprios das ferramentas:
+`UNSUPPORTED_FIELD`, `AMBIENTE_NOT_ALLOWED`, `CERTIFICATE_REQUIRED`,
+`XSD_INVALID` e `SEFIN_REJECTED`. As ferramentas de escrita acrescentam
+`CONFIRMATION_NOT_FOUND` (id desconhecido, usado ou expirado) e
+`TRANSMISSION_UNCERTAIN` (falha de rede no envio; repita o confirm).

package/docs/tutoriais/primeira-nfse.md

@@ -0,0 +1,130 @@
+# Tutorial: sua primeira NFS-e na produção restrita
+
+Neste tutorial você emite, consulta, baixa o DANFSe e cancela uma NFS-e na
+produção restrita, o ambiente oficial de testes. Nada aqui tem validade jurídica.
+Leva uns 15 minutos.
+
+**Você vai precisar de:**
+
+- Node.js 20.6 ou mais recente (para `--env-file`);
+- um certificado A1 (`.pfx`) ICP-Brasil do prestador e a senha;
+- o prestador habilitado no Emissor Nacional, com o município conveniado.
+
+## 1. Crie o projeto
+
+```bash
+mkdir minha-nfse && cd minha-nfse
+npm init -y && npm pkg set type=module
+npm install @useinvio/nfse-sdk
+```
+
+## 2. Configure o certificado
+
+Copie o `.pfx` para a pasta e crie um `.env` (não versione nenhum dos dois):
+
+```bash
+NFSE_CERT_PATH=./certificado.pfx
+NFSE_CERT_PASSWORD=sua-senha
+```
+
+Confira se o SDK lê o certificado:
+
+```bash
+node --env-file=.env -e "import('@useinvio/nfse-sdk').then(({ NfseCertificate }) => console.log(NfseCertificate.fromEnv()))"
+```
+
+A saída mostra só o CNPJ, a validade e o fingerprint, como
+`NfseCertificate { cnpj=12345678000195, notAfter=..., fingerprintSha256=... }`.
+Se aparecer `CERTIFICATE_INVALID_PASSWORD`, revise a senha.
+
+## 3. Emita a nota
+
+Crie `emitir.mjs`. Troque o CNPJ, os municípios (código IBGE) e os códigos de
+serviço pelos do seu prestador; os valores abaixo são ilustrativos.
+
+```js
+import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const certificado = NfseCertificate.fromEnv();
+
+const nota = {
+  ambiente: 'restrita',
+  prestador: {
+    cnpj: '12345678000195', // o CNPJ do certificado: certificado.cnpj
+    cLocEmi: '4106902',
+    serie: '1601',
+    opSimpNac: '1',
+    regEspTrib: '0',
+  },
+  servico: {
+    cTribNac: '010201',
+    xDescServ: 'Desenvolvimento de software',
+    cLocPrestacao: '4106902',
+  },
+  emissao: {
+    nDPS: '1',
+    valores: { vServ: '10.00' },
+    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
+    tributacaoFederal: { piscofins: { CST: '07' } },
+    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
+  },
+};
+
+try {
+  const resultado = await emitirNfse(nota, certificado);
+  console.log('Chave de acesso:', resultado.chaveAcesso);
+} catch (error) {
+  if (!(error instanceof EmitirNotaError)) throw error;
+  for (const rejeicao of error.erros) console.error(rejeicao.Codigo, rejeicao.Descricao);
+}
+```
+
+```bash
+node --env-file=.env emitir.mjs
+```
+
+Se a SEFIN rejeitar, a mensagem traz o código oficial da rejeição.
+Corrija o campo indicado e rode de novo. Depois de uma emissão autorizada,
+**incremente `nDPS`** para a próxima nota: cada número de DPS gera uma nota só.
+
+## 4. Consulte e baixe o DANFSe
+
+Crie `consultar.mjs` e passe a chave de acesso como argumento:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { baixarDanfse, NfseCertificate, obterNfse } from '@useinvio/nfse-sdk';
+
+const certificado = NfseCertificate.fromEnv();
+const chave = process.argv[2];
+
+const nota = await obterNfse(chave, certificado, 'restrita');
+console.log(nota.resumo.nNFSe, nota.resumo.cStat, nota.resumo.valores.vLiq);
+
+const danfse = await baixarDanfse(chave, certificado, 'restrita');
+if (danfse.pdf) await writeFile('danfse.pdf', danfse.pdf);
+```
+
+```bash
+node --env-file=.env consultar.mjs <chave-de-acesso>
+```
+
+## 5. Cancele
+
+```js
+import { cancelarNfse, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const evento = await cancelarNfse(
+  { ambiente: 'restrita', chaveAcesso: process.argv[2], cMotivo: '1', xMotivo: 'Teste de integracao do SDK' },
+  NfseCertificate.fromEnv(),
+);
+console.log('Cancelada:', evento.pedRegEventoId);
+```
+
+## Próximos passos
+
+- Leve o fluxo para a sua aplicação: [Emitir uma NFS-e](../guias/emitir.md).
+- Proteja-se de timeouts: [Recuperar uma emissão](../guias/recuperar-emissao.md).
+- Entenda o que acontece por baixo: [Como o SDK funciona](../conceitos/como-funciona.md).
+- Antes de ir para `producao`, revise a [matriz fiscal](../FISCAL_MATRIX.md) com
+  quem cuida da parte tributária.

package/examples/README.md

@@ -11,5 +11,7 @@ The payloads in `payloads.ts` are shared by these examples and exercised by the
 - [`emit-homologation.ts`](./emit-homologation.ts): emit in the restricted/sandbox SEFIN environment.
 - [`client-resource.ts`](./client-resource.ts): use `NfseClient` with certificate and defaults configured once.
 - [`handle-errors.ts`](./handle-errors.ts): normalize SEFIN rejection details for your application.
+- [`cancel-nfse.ts`](./cancel-nfse.ts): download the DANFSe PDF and cancel an NFS-e (event e101101).
+- [`recover-emission.ts`](./recover-emission.ts): recover an emission after a timeout with `GET /dps/{id}` instead of resending.
 
-The examples assume Node.js 20+ and a valid A1/PFX certificate. They are intentionally explicit about fiscal fields; the SDK does not infer municipal taxation, withholding, CST or total tax burden.
+The examples assume Node.js 20+ and a valid A1/PFX certificate, loaded with `NfseCertificate.fromEnv()` from `NFSE_CERT_PATH` (or `NFSE_CERT_BASE64`) and `NFSE_CERT_PASSWORD` (or `NFSE_CERT_PASSWORD_FILE`). They are intentionally explicit about fiscal fields; the SDK does not infer municipal taxation, withholding, CST or total tax burden.

package/examples/cancel-nfse.ts

@@ -0,0 +1,29 @@
+import { writeFile } from 'node:fs/promises';
+import { NfseCertificate, NfseClient, RegistrarEventoError } from '@useinvio/nfse-sdk';
+
+async function archiveAndCancel(chaveAcesso: string) {
+  const client = new NfseClient({
+    environment: 'sandbox',
+    certificate: NfseCertificate.fromEnv(), // NFSE_CERT_PATH + NFSE_CERT_PASSWORD
+    request: { timeoutMs: 30_000, retries: 2 }, // retries apply to GETs only
+  });
+
+  // Keep the official DANFSe PDF before cancelling.
+  const danfse = await client.invoices.danfse(chaveAcesso);
+  if (danfse.pdf) await writeFile(`danfse-${chaveAcesso}.pdf`, danfse.pdf);
+
+  try {
+    // `autor` defaults to the certificate holder's CNPJ/CPF.
+    const evento = await client.invoices.cancel({
+      chaveAcesso,
+      cMotivo: '1', // 1 = erro na emissao, 2 = servico nao prestado, 9 = outros
+      xMotivo: 'Nota emitida com valor incorreto',
+    });
+    console.log('Evento registrado:', evento.pedRegEventoId);
+  } catch (error) {
+    if (!(error instanceof RegistrarEventoError)) throw error;
+    console.error('Cancelamento rejeitado:', error.status, error.erros);
+  }
+}
+
+void archiveAndCancel(process.argv[2] ?? '0'.repeat(50));

package/examples/client-resource.ts

@@ -1,12 +1,10 @@
-import { NfseClient } from '@useinvio/nfse-sdk';
+import { NfseCertificate, NfseClient } from '@useinvio/nfse-sdk';
 import { nationalInvoice } from './payloads.js';
 
 const client = new NfseClient({
   environment: 'sandbox',
-  certificate: {
-    content: process.env.NFSE_CERTIFICATE_BASE64!,
-    password: process.env.NFSE_CERTIFICATE_PASSWORD!,
-  },
+  // NFSE_CERT_PATH or NFSE_CERT_BASE64, plus NFSE_CERT_PASSWORD or NFSE_CERT_PASSWORD_FILE
+  certificate: NfseCertificate.fromEnv(),
   defaults: { prestador: nationalInvoice.prestador, servico: nationalInvoice.servico },
 });
 

package/examples/emit-homologation.ts

@@ -1,11 +1,10 @@
-import { EmitirNotaError, emitirNfse, loadPfx } from '@useinvio/nfse-sdk';
+import { EmitirNotaError, emitirNfse, NfseCertificate } from '@useinvio/nfse-sdk';
 import { nationalInvoice } from './payloads.js';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-
+const certificate = NfseCertificate.fromEnv(); // NFSE_CERT_PATH + NFSE_CERT_PASSWORD
 
 try {
-  const resultado = await emitirNfse(nationalInvoice, pfx);
+  const resultado = await emitirNfse(nationalInvoice, certificate);
   console.log(resultado.chaveAcesso);
   console.log(resultado.nfseXml);
 } catch (error) {

package/examples/handle-errors.ts

@@ -1,11 +1,11 @@
-import { EmitirNotaError, emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+import { EmitirNotaError, emitirNfse, NfseCertificate, type DpsJsonRequest } from '@useinvio/nfse-sdk';
 import { nationalInvoice } from './payloads.js';
 
 async function emitWithStructuredErrors(nota: DpsJsonRequest) {
-  const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+  const certificate = NfseCertificate.fromEnv(); // NFSE_CERT_PATH + NFSE_CERT_PASSWORD
 
   try {
-    return await emitirNfse(nota, pfx);
+    return await emitirNfse(nota, certificate);
   } catch (error) {
     if (!(error instanceof EmitirNotaError)) throw error;
 

package/examples/recover-emission.ts

@@ -0,0 +1,29 @@
+import {
+  NfseCertificate,
+  prepararNota,
+  recuperarNfsePorDps,
+  transmitirNotaPreparada,
+  type DpsJsonRequest,
+} from '@useinvio/nfse-sdk';
+import { nationalInvoice } from './payloads.js';
+
+/**
+ * Safe emission: persist the signed DPS before sending, and after a timeout ask
+ * SEFIN whether the DPS was processed instead of sending it again.
+ */
+async function emitIdempotently(nota: DpsJsonRequest) {
+  const certificate = NfseCertificate.fromEnv();
+  const prepared = prepararNota(nota, certificate);
+  // await db.save(prepared.dpsId, prepared.signedXml);
+
+  try {
+    return await transmitirNotaPreparada(prepared, certificate, { timeoutMs: 30_000 });
+  } catch (error) {
+    if (error instanceof Error && error.name === 'EmitirNotaError') throw error; // SEFIN answered: a real rejection
+    const existing = await recuperarNfsePorDps(prepared.dpsId, certificate, prepared.ambiente, { retries: 3 });
+    if (existing) return existing; // authorized before the connection dropped
+    return transmitirNotaPreparada(prepared, certificate); // never reached SEFIN: same DPS, same Id
+  }
+}
+
+void emitIdempotently(nationalInvoice);