@bitize/bitmde 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 ## [Não publicado]
 
+## [0.20.0] / 2026-10-16
+
+> Acrescenta a NFS-e Nacional: distribuição pelo ADN e manifestação do tomador na SEFIN. Nada muda nas APIs de NF-e.
+
+### Adicionado
+
+- **`DistribuicaoNFSe`: distribuição de NFS-e Nacional pelo Ambiente de Dados Nacional (ADN)**, exportada nas três formas (`module.exports`, `.default`, `.mde`). Usa o mesmo certificado A1 da NF-e e consulta as NFS-e e os eventos em que o CNPJ figura:
+  - `consultaUltNSU(ultNSU)` — até 50 documentos depois do NSU informado, começando em `'0'`; fila vazia é HTTP 404 sem `error`
+  - `consultaNSU(nsu)` — o documento daquele NSU
+  - `consultaChNFSe(chNFSe)` — a NFS-e da chave de 50 dígitos e os eventos dela
+- Campo `papel` em cada NFS-e distribuída: `'tomador'`, `'prestador'` ou `'intermediario'`, conforme o CNPJ consultado apareça como `toma`, `prest` ou `interm` da DPS, nessa ordem; `''` se não aparecer e em eventos. A biblioteca marca, não filtra
+- Retorno próprio da NFS-e, `{ data, resBody, status, error?, transportError? }`: `resBody` é o corpo cru do ADN, e `status`, `error` e `transportError` têm o mesmo significado das APIs de NF-e. Ver [ADR 0016](https://github.com/bitize/bitmde/blob/main/.docs/arquitetura/decisoes/0016-retorno-proprio-da-nfse.md)
+- Hosts do ADN, de produção e produção restrita, no `test/tls-sefaz.test.js` e com isso no workflow semanal `cadeia-tls.yml`
+- **`ManifestacaoNFSe`: manifestação do tomador da NFS-e Nacional na SEFIN Nacional**, exportada nas três formas. Com o mesmo certificado A1, registra um evento por chamada:
+  - `confirmar(chNFSe)` — Confirmação do Tomador (`e203202`)
+  - `rejeitar(chNFSe, { cMotivo, xMotivo? })` — Rejeição do Tomador (`e203206`), com `cMotivo` `'1'` a `'5'` ou `'9'`; `xMotivo` de 15 a 255 caracteres, obrigatório no motivo `'9'`
+- Retorno da manifestação `{ data, reqXml, resBody, status, error?, transportError? }`, no formato da ADR 0016: `reqXml` é o `pedRegEvento` assinado e `data.evento` traz o evento registrado, em `xml` e `json`
+- Hosts da SEFIN Nacional, de produção e produção restrita, no `test/tls-sefaz.test.js` e no `cadeia-tls.yml`
+
+Nada muda em `DistribuicaoDFe` nem em `RecepcaoEvento`: o XML assinado da recepção de evento sai byte a byte igual, conferido por teste.
+
+### Modificado
+
+- Workflow `testes.yml` deixa de rodar em push e PR que só mexem em documentação (`**/*.md`, `.docs/**`, `.claude/**`, `LICENSE`). O `qualidade.yml`, com o Prettier que valida o Markdown, continua rodando sempre, e o `publicar.yml` roda a suíte antes de todo release
+
+## [0.19.0] / 2026-10-03
+
+> Muda o comportamento padrão de transporte e deixa de suportar o Node 20; leia [Compatibilidade](#compatibilidade) antes de atualizar.
+
+### Modificado
+
+- **O certificado do servidor da SEFAZ passa a ser validado por padrão** (`rejectUnauthorized: true`). Até a 0.18.0 o padrão era `false`: a biblioteca aceitava qualquer servidor, inclusive um intermediário malicioso, e apresentava a ele o certificado A1 no mTLS
+- **A cadeia padrão passa a somar as raízes do Node à ICP-Brasil, em vez de substituí-las.** A cadeia embarcada (AC Raiz Brasileira v10 e AC SERPRO SSLv1) não valida mais o Ambiente Nacional, que hoje serve `AC SERPRO AR46 OV TLS CA 2025 ← GlobalSign Root R46`, e a opção `ca` do Node descarta as raízes padrão. Quem ligava `rejectUnauthorized: true`, como esta documentação recomendava, recebia sempre `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`. As raízes respeitam `NODE_EXTRA_CA_CERTS` e `--use-system-ca` quando o Node oferece `tls.getCACertificates`
+- **Erro de transporte deixa de se disfarçar de status HTTP.** Sem resposta da SEFAZ, o retorno vinha com `status` 500, 502 ou 504 sintético e `resXml: '<error>mensagem</error>'`, e o código do erro se perdia. Agora vem com `status: 0`, `resXml: ''`, `transportError: { code, message }` e `error: 'Falha de transporte (<code>): <message>'`. Resposta HTTP real da SEFAZ, inclusive 5xx, não muda. Ver [ADR 0014](https://github.com/bitize/bitmde/blob/main/.docs/arquitetura/decisoes/0014-tls-validado-por-padrao-e-erro-de-transporte-explicito.md)
+
+### Adicionado
+
+- `CA_PADRAO` e `CA_ICP_BRASIL` exportados na raiz do pacote, nas três formas (`module.exports`, `.default`, `.mde`): a cadeia que a biblioteca usa por padrão e só a ICP-Brasil embarcada. São arrays de PEM congelados, para compor como `httpsOptions: { ca: [...CA_PADRAO, minhaCa] }`
+- Campo `transportError?: { code, message }` no retorno dos três métodos de consulta e do `enviarEvento`
+- `engines: { node: ">=22" }` no `package.json`
+- Workflow `cadeia-tls.yml`, que confere toda semana o handshake TLS com `www1` e `hom1` usando `CA_PADRAO`, para a próxima troca de cadeia do Ambiente Nacional aparecer antes de chegar a quem consome
+
+### Removido
+
+- **Node 20 deixa de ser suportado**: sem suporte do projeto Node.js desde abril de 2026, sai da matriz de testes da CI. A biblioteca passa a exigir Node 22 ou posterior
+
+### Compatibilidade
+
+Nenhuma assinatura muda, mas dois comportamentos padrão mudam, daí o bump de minor (`^0.18.0` não resolve para a 0.19.0):
+
+1. **Servidor cuja cadeia não fecha em `CA_PADRAO` passa a ser recusado.** Para os endpoints do Ambiente Nacional, que são os únicos que a biblioteca chama, nada muda. Atrás de um proxy que reassina TLS, acrescente a CA dele com `NODE_EXTRA_CA_CERTS` ou com `httpsOptions: { ca: [...CA_PADRAO, caDoProxy] }`. Quem já passava `ca` próprio continua no controle, porque `httpsOptions` sobrescreve o padrão.
+2. **Erro de transporte muda de forma.** Quem testa só `if (retorno.error)` não precisa mudar nada. Quem lia `status` 500/502/504 ou procurava `<error>` em `resXml` passa a usar `transportError`:
+
+```diff
+-if (retorno.status === 502 && /^<error>/.test(retorno.resXml)) {
++if (retorno.transportError) {
++  log(retorno.transportError.code, retorno.transportError.message)
+ }
+```
+
+Voltar ao comportamento antigo de TLS ainda é possível com `httpsOptions: { rejectUnauthorized: false }`, e não é recomendado.
+
+Quem ainda roda Node 20 recebe um aviso de `engines` na instalação e deve atualizar para o Node 22 ou o 24, ambos LTS.
+
 ## [0.18.0] / 2026-10-01
 
 ### Corrigido

package/README.md

@@ -5,9 +5,9 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bitize/bitmde/blob/main/LICENSE)
 [![Mantido pelo BitERP](https://img.shields.io/badge/mantido%20por-BitERP-0b5fff.svg)](https://www.biterp.ai)
 
-Biblioteca para consumo dos Web Services da Sefaz de Distribuição de DF-e e Evento de Manifestação do Destinatário.
+Biblioteca para consumo dos Web Services da Sefaz de Distribuição de DF-e e Evento de Manifestação do Destinatário, e da NFS-e Nacional: distribuição pelo Ambiente de Dados Nacional (ADN) e manifestação do tomador na SEFIN Nacional.
 
-Essa biblioteca permite consultar a relação das notas fiscais emitidas contra um determinado CNPJ/CPF e realizar o envio do evento de manifestação, podendo assim, baixar o XML da NF-e.
+Essa biblioteca permite consultar a relação das notas fiscais emitidas contra um determinado CNPJ/CPF e realizar o envio do evento de manifestação, podendo assim, baixar o XML da NF-e. Com o mesmo certificado, consulta as NFS-e em que o CNPJ é tomador, prestador ou intermediário, e registra a Confirmação ou a Rejeição do tomador.
 
 Desenvolvida e mantida pela equipe do **[BitERP](https://www.biterp.ai)**, onde é usada em produção para a automação da manifestação do destinatário e do download de XML de NF-e de entrada.
 
@@ -25,6 +25,7 @@ npm i @bitize/bitmde
 
 - Possuir um **Certificado A1** válido emitido por uma Autoridade Certificadora credenciada pela Infraestrutura de Chaves Públicas Brasileira – **ICP-Brasil**.
 - O certificado pode ser usando no formato **PFX** e **Senha** _OU_ **cert.pem** e **key.pem**
+- **Node.js 22 ou posterior.** O Node 20, sem suporte desde abril de 2026, deixou de ser testado na 0.19.0.
 
 ## Funcionalidades
 
@@ -36,6 +37,10 @@ npm i @bitize/bitmde
   - Retorna o Documento Fiscal referente ao NSU informado, podendo ser um `Resumo`, uma `NF-e` ou um `Evento`
 - Envio de evento
   - Registra o evento de manifestação na nota informada (`Confirmação da Operação`, `Ciência da Operação`, `Desconhecimento da Operação` ou `Operação não Realizada`)
+- Distribuição de NFS-e Nacional
+  - Consulta por último NSU, por NSU e por chave de acesso no ADN, com o papel do CNPJ (`tomador`, `prestador` ou `intermediario`) em cada NFS-e
+- Manifestação do tomador da NFS-e Nacional
+  - Registra a `Confirmação do Tomador` ou a `Rejeição do Tomador` na SEFIN Nacional
 
 ## Distribuição de DF-e
 
@@ -56,7 +61,7 @@ new DistribuicaoDFe(config)
   - `tpAmb` `<String>` - [OBRIGATÓRIO] - Identificação de Ambiente. Informar `'1'` para **Produção** ou `'2'` para **Homologação**.
   - `options` `<Object>` - [OPCIONAL]
     - `requestOptions` `<AxiosRequestConfig>` - [OPCIONAL]
-    - `httpsOptions` `<AgentOptions>` - [OPCIONAL]
+    - `httpsOptions` `<AgentOptions>` - [OPCIONAL] - Opções do `https.Agent`, mescladas por cima do padrão `{ ca: CA_PADRAO, rejectUnauthorized: true }`. Ver [Conexão com a SEFAZ](#conexão-com-a-sefaz).
 
 ### Consulta por ultNSU
 
@@ -255,7 +260,7 @@ new RecepcaoEvento(config)
   - `timezone` `<String>` - [OPCIONAL] - Fuso horário do autor. É utilizado `'America/Sao_Paulo'` como valor padrão. Consulte a tabela [lista de timezones](#lista-de-timezones) válidos para o Brasil.
   - `options` `<Object>` - [OPCIONAL]
     - `requestOptions` `<AxiosRequestConfig>` - [OPCIONAL]
-    - `httpsOptions` `<AgentOptions>` - [OPCIONAL]
+    - `httpsOptions` `<AgentOptions>` - [OPCIONAL] - Opções do `https.Agent`, mescladas por cima do padrão `{ ca: CA_PADRAO, rejectUnauthorized: true }`. Ver [Conexão com a SEFAZ](#conexão-com-a-sefaz).
 
 ### Enviar Lote de Eventos
 
@@ -347,6 +352,306 @@ console.log(manifestacao)
 // }
 ```
 
+## Distribuição de NFS-e Nacional
+
+Consulta, no Ambiente de Dados Nacional (ADN), as NFS-e e os eventos em que o CNPJ figura. A fila traz o histórico inteiro do CNPJ desde a primeira nota no ADN e mistura notas recebidas, notas emitidas e eventos de terceiros sobre umas e outras. A biblioteca **não filtra**: cada NFS-e vem com o `papel` do CNPJ consultado.
+
+> **Cobertura.** Só aparece a NFS-e que chegou ao ADN: as emitidas no Emissor Nacional e as de município cujo sistema próprio compartilha com o ADN. Nota de município que ainda não compartilha não está na distribuição, mesmo com a obrigatoriedade da LC 214/2025.
+
+### Construtor
+
+```js
+new DistribuicaoNFSe(config)
+```
+
+- `config` `<Object>`
+  - `pfx` `<Buffer>` - [OPCIONAL] - Arquivo **.pfx**. Se o `pfx` não for informado, as propriedades `cert` e `key` passam a ser obrigatórias.
+  - `passphrase` `<String>` - [OPCIONAL] - Senha do arquivo **.pfx**.
+  - `cert` `<Buffer | String>` - [OPCIONAL] - Conteúdo do _cert.pem_. Essa propriedade fica obrigatória se o `pfx` não for informado.
+  - `key` `<Buffer | String>` - [OPCIONAL] - Conteúdo do _key.pem_. Essa propriedade fica obrigatória se o `pfx` não for informado.
+  - `cnpj` `<String>` - [OBRIGATÓRIO] - CNPJ consultado, com 14 caracteres e sem pontuação (aceita o alfanumérico). Pode ser o do certificado ou o de outro estabelecimento com a mesma raiz.
+  - `tpAmb` `<String>` - [OBRIGATÓRIO] - Informar `'1'` para **Produção** ou `'2'` para **Produção restrita**.
+  - `options` `<Object>` - [OPCIONAL]
+    - `requestOptions` `<AxiosRequestConfig>` - [OPCIONAL]
+    - `httpsOptions` `<AgentOptions>` - [OPCIONAL] - Opções do `https.Agent`, mescladas por cima do padrão `{ ca: CA_PADRAO, rejectUnauthorized: true }`. Ver [Conexão com a SEFAZ](#conexão-com-a-sefaz).
+
+### Consultas
+
+| Método                   | Argumento                          | Devolve                                        |
+| :----------------------- | :--------------------------------- | :--------------------------------------------- |
+| `consultaUltNSU(ultNSU)` | NSU, 1-15 dígitos; começa em `'0'` | Até 50 documentos **depois** do NSU informado  |
+| `consultaNSU(nsu)`       | NSU, 1-15 dígitos, maior que zero  | O documento daquele NSU                        |
+| `consultaChNFSe(chNFSe)` | Chave de acesso, 50 dígitos        | A NFS-e da chave e os eventos vinculados a ela |
+
+No ADN o NSU é um inteiro, sem zeros à esquerda: `'00051'` e `51` viram `'51'`.
+
+#### Exemplo: drenar a fila
+
+```js
+const { DistribuicaoNFSe } = require('@bitize/bitmde')
+const fs = require('fs')
+
+const distribuicao = new DistribuicaoNFSe({
+  pfx: fs.readFileSync('./certificado.pfx'),
+  passphrase: 'senha',
+  cnpj: '12345678000190',
+  tpAmb: '1',
+})
+
+let ultNSU = '0' // ou o último NSU guardado
+
+while (true) {
+  const consulta = await distribuicao.consultaUltNSU(ultNSU)
+
+  if (consulta.error) {
+    throw new Error(consulta.error)
+  }
+
+  const { documentos, documentosErros } = consulta.data
+
+  // Fim da fila: HTTP 404, NENHUM_DOCUMENTO_LOCALIZADO, sem error.
+  if (documentos.length === 0 && documentosErros.length === 0) {
+    break
+  }
+
+  for (const doc of documentos) {
+    if (doc.tipoDocumento === 'NFSE' && doc.papel === 'tomador') {
+      // NFS-e recebida: doc.xml e doc.json
+    }
+  }
+
+  ultNSU = [...documentos, ...documentosErros]
+    .map((doc) => doc.nsu)
+    .sort((a, b) => Number(a) - Number(b))
+    .pop()
+}
+```
+
+O próximo pedido usa o **último NSU recebido**, sem somar 1. O ADN não bloqueia quem volta a um NSU anterior, como faz a distribuição de NF-e, mas guardar o ponteiro e escolher o intervalo entre as consultas continua sendo de quem consome.
+
+#### Retorno
+
+```js
+console.log(consulta)
+// {
+//   data: {
+//     statusProcessamento: 'DOCUMENTOS_LOCALIZADOS',
+//     tipoAmbiente: 'PRODUCAO',
+//     versaoAplicativo: '1.0.0.0',
+//     dataHoraProcessamento: '2026-10-15T10:35:14.5687887-03:00',
+//     alertas: [],
+//     erros: [],
+//     documentos: [
+//       {
+//         nsu: '1',
+//         chaveAcesso: '41000000000000000000000000000000000000000000000001',
+//         tipoDocumento: 'NFSE',
+//         tipoEvento: '',
+//         dataHoraGeracao: '2026-10-01T09:12:00',
+//         papel: 'tomador',
+//         xml: '<?xml version="1.0" encoding="utf-8"?><NFSe versao="1.01" ... </NFSe>',
+//         json: { NFSe: { ... } },
+//       },
+//       {
+//         nsu: '2',
+//         chaveAcesso: '41000000000000000000000000000000000000000000000001',
+//         tipoDocumento: 'EVENTO',
+//         tipoEvento: 'CANCELAMENTO',
+//         dataHoraGeracao: '2026-10-02T15:40:00',
+//         papel: '',
+//         xml: '<?xml version="1.0" encoding="utf-8"?><evento versao="1.01" ... </evento>',
+//         json: { evento: { ... } },
+//       },
+//     ],
+//     documentosErros: [],
+//   },
+//   resBody: '{"StatusProcessamento":"DOCUMENTOS_LOCALIZADOS", ... }',
+//   status: 200,
+// }
+```
+
+- `papel` vale `'tomador'`, `'prestador'` ou `'intermediario'` quando o `cnpj` da config é o `toma`, o `prest` ou o `interm` da DPS, testados nessa ordem; `''` quando não é nenhum, e sempre `''` em eventos. Para ficar só com as recebidas, filtre por `tipoDocumento === 'NFSE' && papel === 'tomador'`.
+- `resBody` é o corpo cru da resposta do ADN, como veio. Não há `reqXml` nem `resXml`: a consulta é um `GET` sem corpo e a resposta é JSON.
+- `documentosErros` traz, com `nsu`, `chaveAcesso`, `tipoDocumento` e `error`, os itens cujo XML não abriu: `ArquivoXml sem conteúdo.`, `Falha ao descompactar o ArquivoXml: <motivo>` ou `Falha ao interpretar o XML do ArquivoXml: <motivo>`. Eles não derrubam o lote nem preenchem o `error` de topo.
+
+#### Quando há `error`
+
+| Situação                                          | `status` | `data`                       | `error`                                            |
+| :------------------------------------------------ | :------: | :--------------------------- | :------------------------------------------------- |
+| Fila vazia, chave ou NSU sem documento            |   404    | preenchido, `documentos: []` | —                                                  |
+| Rejeição do ADN (ex.: `cnpj` de outra raiz)       |   400    | preenchido, com `erros`      | `E2243: O CNPJ informado na consulta deve ter ...` |
+| Resposta que não é do ADN (ex.: HTML de um proxy) |   real   | `{}`                         | `Resposta inesperada do ADN (HTTP 502).`           |
+| Sem resposta HTTP                                 |    0     | `{}`                         | `Falha de transporte (<code>): <message>`          |
+
+Na rejeição, `data` **não** é esvaziado: `data.erros` traz o diagnóstico em `{ codigo, descricao, complemento }`. `error` e `transportError` têm o mesmo significado da distribuição de DF-e — ver [Erro de transporte](#erro-de-transporte).
+
+## Manifestação do tomador da NFS-e Nacional
+
+Registra, na SEFIN Nacional, a Confirmação (`e203202`) ou a Rejeição (`e203206`) do tomador sobre uma NFS-e que exista no ADN. Cada chamada é **um** pedido de registro de evento, assinado com o A1 da config — não há lote.
+
+> **Evento fiscal não se desfaz.** Em produção (`tpAmb: '1'`), cada chamada aceita registra um evento vinculado à nota. Depois da Confirmação, o prestador não consegue mais cancelar a NFS-e, só substituí-la; a Rejeição só é anulada pelo município de incidência. Teste em produção restrita (`tpAmb: '2'`).
+
+### Construtor
+
+```js
+new ManifestacaoNFSe(config)
+```
+
+- `config` `<Object>`
+  - `pfx` `<Buffer>` - [OPCIONAL] - Arquivo **.pfx**. Se o `pfx` não for informado, as propriedades `cert` e `key` passam a ser obrigatórias.
+  - `passphrase` `<String>` - [OPCIONAL] - Senha do arquivo **.pfx**.
+  - `cert` `<Buffer | String>` - [OPCIONAL] - Conteúdo do _cert.pem_. Essa propriedade fica obrigatória se o `pfx` não for informado.
+  - `key` `<Buffer | String>` - [OPCIONAL] - Conteúdo do _key.pem_. Essa propriedade fica obrigatória se o `pfx` não for informado.
+  - `cnpj` `<String>` - [OBRIGATÓRIO] - CNPJ do tomador, enviado como `CNPJAutor`, com 14 caracteres e sem pontuação. Precisa ter a mesma raiz do CNPJ do certificado.
+  - `tpAmb` `<String>` - [OBRIGATÓRIO] - Informar `'1'` para **Produção** ou `'2'` para **Produção restrita**.
+  - `timezone` `<String>` - [OPCIONAL] - Fuso do `dhEvento`. Padrão `'America/Sao_Paulo'`. Ver [Lista de Timezones](#lista-de-timezones).
+  - `options` `<Object>` - [OPCIONAL]
+    - `requestOptions` `<AxiosRequestConfig>` - [OPCIONAL]
+    - `httpsOptions` `<AgentOptions>` - [OPCIONAL] - Opções do `https.Agent`, mescladas por cima do padrão `{ ca: CA_PADRAO, rejectUnauthorized: true }`. Ver [Conexão com a SEFAZ](#conexão-com-a-sefaz).
+
+### Métodos
+
+| Método                     | Argumentos                                         | Evento                             |
+| :------------------------- | :------------------------------------------------- | :--------------------------------- |
+| `confirmar(chNFSe)`        | Chave de acesso, 50 dígitos                        | `e203202` — Confirmação do Tomador |
+| `rejeitar(chNFSe, motivo)` | Chave de acesso e `motivo` `{ cMotivo, xMotivo? }` | `e203206` — Rejeição do Tomador    |
+
+Códigos de `cMotivo`:
+
+| `cMotivo` | Motivo                                                                                        |
+| :-------: | :-------------------------------------------------------------------------------------------- |
+|   `'1'`   | NFS-e em duplicidade                                                                          |
+|   `'2'`   | NFS-e já emitida pelo tomador                                                                 |
+|   `'3'`   | Não ocorrência do fato gerador                                                                |
+|   `'4'`   | Erro quanto à responsabilidade tributária                                                     |
+|   `'5'`   | Erro quanto ao valor do serviço, valor das deduções, serviço prestado ou data do fato gerador |
+|   `'9'`   | Outros — **exige `xMotivo`**                                                                  |
+
+`xMotivo` é opcional nos demais motivos e, quando informado, tem de 15 a 255 caracteres.
+
+Cada NFS-e aceita uma Confirmação e uma Rejeição do tomador. A Rejeição é aceita depois da Confirmação, e a Confirmação depois da Rejeição; repetir o mesmo evento é rejeitado (`E0861` e `E0866`).
+
+#### Exemplo
+
+```js
+const { ManifestacaoNFSe } = require('@bitize/bitmde')
+const fs = require('fs')
+
+const manifestacao = new ManifestacaoNFSe({
+  pfx: fs.readFileSync('./certificado.pfx'),
+  passphrase: 'senha',
+  cnpj: '12345678000190',
+  tpAmb: '2',
+})
+
+const confirmacao = await manifestacao.confirmar(
+  '41000000000000000000000000000000000000000000000001'
+)
+
+const rejeicao = await manifestacao.rejeitar(
+  '41000000000000000000000000000000000000000000000002',
+  { cMotivo: '9', xMotivo: 'Serviço não foi prestado.' }
+)
+
+if (rejeicao.error) {
+  console.error(rejeicao.error) // ex.: 'E0866: ...'
+}
+```
+
+#### Retorno
+
+```js
+console.log(confirmacao)
+// {
+//   data: {
+//     tipoAmbiente: '2',
+//     versaoAplicativo: 'SefinNacional_1.6.0',
+//     dataHoraProcessamento: '2026-10-16T09:26:06-03:00',
+//     alertas: [],
+//     erros: [],
+//     evento: {
+//       xml: '<evento versao="1.01" ... </evento>',
+//       json: { evento: { ... } },
+//     },
+//   },
+//   reqXml: '<?xml version="1.0" encoding="UTF-8"?><pedRegEvento xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01"> ... </pedRegEvento>',
+//   resBody: '{"tipoAmbiente":2, ... }',
+//   status: 201,
+// }
+```
+
+- `reqXml` é o `pedRegEvento` assinado, antes do gzip — é o que se audita numa rejeição.
+- `data.evento` traz o evento registrado pela SEFIN, em `xml` e `json`.
+- `status`, `error` e `transportError` têm o mesmo significado das outras APIs.
+
+#### Quando há `error`
+
+| Situação                                            | `status` | `data`                   | `error`                                                |
+| :-------------------------------------------------- | :------: | :----------------------- | :----------------------------------------------------- |
+| Evento registrado e devolvido                       |   201    | preenchido, com `evento` | —                                                      |
+| Evento registrado, mas o retorno não abre           |   201    | preenchido, `evento: {}` | `Falha ao abrir o evento retornado: <motivo>`          |
+| Rejeição da SEFIN (ex.: nota fora do ADN)           |   400    | preenchido, com `erros`  | `E1831: O evento não pode ser recepcionado pois a ...` |
+| Resposta que não é da SEFIN (ex.: HTML de um proxy) |   real   | `{}`                     | `Resposta inesperada da SEFIN (HTTP 502).`             |
+| Sem resposta HTTP                                   |    0     | `{}`                     | `Falha de transporte (<code>): <message>`              |
+
+Na segunda linha o evento **foi registrado**: não repita o pedido; consulte a nota pela [Distribuição de NFS-e Nacional](#distribuição-de-nfs-e-nacional). `reqXml` vem em todos os casos.
+
+## Conexão com a SEFAZ
+
+### Validação do certificado do servidor
+
+O certificado do servidor da SEFAZ é **validado por padrão**. Sem `httpsOptions`, o agente HTTPS usa:
+
+```js
+{ ca: CA_PADRAO, rejectUnauthorized: true }
+```
+
+A biblioteca exporta as duas cadeias que usa:
+
+- `CA_PADRAO` — as raízes que o Node usaria por padrão, somadas à cadeia ICP-Brasil. Inclui `NODE_EXTRA_CA_CERTS` e `--use-system-ca` quando o Node oferece `tls.getCACertificates` (22.15 ou posterior); nas versões do Node 22 anteriores a ela, usa o bundle da Mozilla (`tls.rootCertificates`). É montada uma vez, quando o pacote é carregado.
+- `CA_ICP_BRASIL` — só a cadeia ICP-Brasil embarcada (AC Raiz Brasileira v10 e AC SERPRO SSLv1).
+
+As duas são arrays de PEM congelados. Informar `ca` em `httpsOptions` **substitui** a cadeia inteira. Para acrescentar uma AC, por exemplo a de um proxy corporativo, some à cadeia padrão:
+
+```js
+const { CA_PADRAO, DistribuicaoDFe } = require('@bitize/bitmde')
+
+const distribuicao = new DistribuicaoDFe({
+  // ...
+  options: {
+    httpsOptions: {
+      ca: [...CA_PADRAO, fs.readFileSync('./minha-ca.pem', 'utf8')],
+    },
+  },
+})
+```
+
+Desligar a validação ainda é possível com `httpsOptions: { rejectUnauthorized: false }`, mas **não é recomendado**: assim a biblioteca aceita qualquer servidor e apresenta a ele o certificado A1 no mTLS.
+
+### Erro de transporte
+
+Quando não há resposta HTTP (falha na cadeia TLS, DNS, conexão recusada, timeout), a biblioteca não lança. O retorno vem com `status: 0` e o motivo em `transportError`:
+
+```js
+// {
+//   data: {},
+//   reqXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap12:Body></soap12:Envelope>',
+//   resXml: '',
+//   status: 0,
+//   error: 'Falha de transporte (UNABLE_TO_GET_ISSUER_CERT_LOCALLY): unable to get local issuer certificate',
+//   transportError: {
+//     code: 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+//     message: 'unable to get local issuer certificate',
+//   },
+// }
+```
+
+`transportError.code` é o código do Node ou do axios, sem tradução: `ECONNREFUSED`, `ENOTFOUND`, `ECONNRESET`, `ECONNABORTED` (timeout), `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` (cadeia), entre outros. Sem código, vem `ERR_DESCONHECIDO`. `error` continua preenchido, então `if (retorno.error)` cobre esse caso como antes.
+
+Uma resposta HTTP de erro da SEFAZ, como um `502` ou um `503`, chega com o status real, o corpo em `resXml` e **sem** `transportError`. Então `status: 0` significa sempre "a SEFAZ não respondeu".
+
+Na `DistribuicaoNFSe` o erro de transporte tem a mesma forma, com `resBody: ''` no lugar de `reqXml` e `resXml`. As mesmas regras de `CA_PADRAO` e `httpsOptions` valem para os hosts do ADN, que hoje servem certificado Let's Encrypt.
+
 ## Sobre o BitERP
 
 O `@bitize/bitmde` é mantido pela equipe do **[BitERP](https://www.biterp.ai)**, um ERP online que automatiza a rotina fiscal, financeira e comercial de empresas brasileiras.

package/dist/apis/distribuicaoDFe-api.d.ts

@@ -12,7 +12,7 @@ declare class DistribuicaoDFe {
      * @param {'1' | '2'} config.tpAmb
      * @param {Object} [config.options]
      * @param {import('axios').AxiosRequestConfig} [config.options.requestOptions]
-     * @param {import('https').AgentOptions} [config.options.httpsOptions]
+     * @param {import('https').AgentOptions} [config.options.httpsOptions] Mesclado por cima do padrão `{ ca: CA_PADRAO, rejectUnauthorized: true }`. Informar `ca` substitui a cadeia inteira; para somar uma AC, use `[...CA_PADRAO, minhaCa]`.
      */
     constructor(config: {
         pfx?: Buffer;
@@ -63,6 +63,10 @@ declare class DistribuicaoDFe {
             }];
         };
         error: string;
+        transportError?: {
+            code: string;
+            message: string;
+        };
         reqXml: string;
         resXml: string;
         status: number;
@@ -92,6 +96,10 @@ declare class DistribuicaoDFe {
             }];
         };
         error: string;
+        transportError?: {
+            code: string;
+            message: string;
+        };
         reqXml: string;
         resXml: string;
         status: number;
@@ -121,6 +129,10 @@ declare class DistribuicaoDFe {
             }];
         };
         error: string;
+        transportError?: {
+            code: string;
+            message: string;
+        };
         reqXml: string;
         resXml: string;
         status: number;

package/dist/apis/distribuicaoNFSe-api.d.ts

@@ -0,0 +1,176 @@
+export = DistribuicaoNFSe;
+declare class DistribuicaoNFSe {
+    /**
+     * Distribuição de NFS-e Nacional pelo Ambiente de Dados Nacional (ADN).
+     *
+     * @param {Object} config
+     * @param {Buffer} [config.pfx]
+     * @param {string} [config.passphrase]
+     * @param {Buffer | string} [config.cert]
+     * @param {Buffer | string} [config.key]
+     * @param {string} config.cnpj CNPJ consultado, enviado como `cnpjConsulta`. Precisa ter a mesma raiz do CNPJ do certificado.
+     * @param {'1' | '2'} config.tpAmb `'1'` produção, `'2'` produção restrita.
+     * @param {Object} [config.options]
+     * @param {import('axios').AxiosRequestConfig} [config.options.requestOptions]
+     * @param {import('https').AgentOptions} [config.options.httpsOptions] Mesclado por cima do padrão `{ ca: CA_PADRAO, rejectUnauthorized: true }`. Informar `ca` substitui a cadeia inteira; para somar uma AC, use `[...CA_PADRAO, minhaCa]`.
+     */
+    constructor(config: {
+        pfx?: Buffer;
+        passphrase?: string;
+        cert?: Buffer | string;
+        key?: Buffer | string;
+        cnpj: string;
+        tpAmb: "1" | "2";
+        options?: {
+            requestOptions?: import("axios").AxiosRequestConfig;
+            httpsOptions?: import("https").AgentOptions;
+        };
+    });
+    config: Readonly<{
+        cnpj: string;
+        tpAmb: "1" | "2";
+        cert: string;
+        key: string;
+        requestOptions: Readonly<import("axios").AxiosRequestConfig<any, any>>;
+        httpsOptions: Readonly<import("node:https").AgentOptions>;
+    }>;
+    /**
+     * A NFS-e da chave e os eventos vinculados a ela.
+     *
+     * @param {string} chNFSe Chave de acesso de 50 dígitos.
+     */
+    consultaChNFSe(chNFSe: string): Promise<{
+        data: {
+            statusProcessamento: string;
+            tipoAmbiente: string;
+            versaoAplicativo: string;
+            dataHoraProcessamento: string;
+            alertas: Array<{
+                codigo: string;
+                descricao: string;
+                complemento: string;
+            }>;
+            erros: Array<{
+                codigo: string;
+                descricao: string;
+                complemento: string;
+            }>;
+            documentos: Array<{
+                nsu: string;
+                chaveAcesso: string;
+                tipoDocumento: string;
+                tipoEvento: string;
+                dataHoraGeracao: string;
+                papel: "" | "tomador" | "prestador" | "intermediario";
+                xml: string;
+                json: any;
+            }>;
+            documentosErros: Array<{
+                nsu: string;
+                chaveAcesso: string;
+                tipoDocumento: string;
+                error: string;
+            }>;
+        };
+        error?: string;
+        transportError?: {
+            code: string;
+            message: string;
+        };
+        resBody: string;
+        status: number;
+    }>;
+    /**
+     * O documento daquele NSU.
+     *
+     * @param {string | number} nsu Maior que zero.
+     */
+    consultaNSU(nsu: string | number): Promise<{
+        data: {
+            statusProcessamento: string;
+            tipoAmbiente: string;
+            versaoAplicativo: string;
+            dataHoraProcessamento: string;
+            alertas: Array<{
+                codigo: string;
+                descricao: string;
+                complemento: string;
+            }>;
+            erros: Array<{
+                codigo: string;
+                descricao: string;
+                complemento: string;
+            }>;
+            documentos: Array<{
+                nsu: string;
+                chaveAcesso: string;
+                tipoDocumento: string;
+                tipoEvento: string;
+                dataHoraGeracao: string;
+                papel: "" | "tomador" | "prestador" | "intermediario";
+                xml: string;
+                json: any;
+            }>;
+            documentosErros: Array<{
+                nsu: string;
+                chaveAcesso: string;
+                tipoDocumento: string;
+                error: string;
+            }>;
+        };
+        error?: string;
+        transportError?: {
+            code: string;
+            message: string;
+        };
+        resBody: string;
+        status: number;
+    }>;
+    /**
+     * Até 50 documentos depois do NSU informado. Começa em `'0'`; o pedido
+     * seguinte usa o último NSU recebido. Fila vazia é `status` 404, sem `error`.
+     *
+     * @param {string | number} ultNSU
+     */
+    consultaUltNSU(ultNSU: string | number): Promise<{
+        data: {
+            statusProcessamento: string;
+            tipoAmbiente: string;
+            versaoAplicativo: string;
+            dataHoraProcessamento: string;
+            alertas: Array<{
+                codigo: string;
+                descricao: string;
+                complemento: string;
+            }>;
+            erros: Array<{
+                codigo: string;
+                descricao: string;
+                complemento: string;
+            }>;
+            documentos: Array<{
+                nsu: string;
+                chaveAcesso: string;
+                tipoDocumento: string;
+                tipoEvento: string;
+                dataHoraGeracao: string;
+                papel: "" | "tomador" | "prestador" | "intermediario";
+                xml: string;
+                json: any;
+            }>;
+            documentosErros: Array<{
+                nsu: string;
+                chaveAcesso: string;
+                tipoDocumento: string;
+                error: string;
+            }>;
+        };
+        error?: string;
+        transportError?: {
+            code: string;
+            message: string;
+        };
+        resBody: string;
+        status: number;
+    }>;
+}