Docs: páginas do portal conferidas contra o código (pós-6.0.1)

CHANGELOG.md

@@ -7,6 +7,15 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR
 
 ## [Não lançado]
 
+### Documentação
+
+- **As páginas de `docs/` que o portal espelha foram conferidas contra o código.** Havia
+  assinaturas e retornos de antes da 6.0.0 nas páginas de NF-e, NFS-e, inscrição estadual,
+  consulta de CNPJ e pessoas, e em `downloads.md`, que ainda prometia "Buffer sempre" e "ZIP por
+  empresa". Também foram corrigidos exemplos que não compilavam em modo estrito. `docs/API.md`,
+  `docs/EXTENDING.md` e `docs/EXTENSIBILITY_SUMMARY.md` são da v3 e ganharam aviso de legado no
+  topo, sem reescrever o conteúdo.
+
 ## [6.0.1] - 2026-10-16
 
 > **Patch de contrato e de documentação.** Dois bugs de código, provados por sonda ao vivo

docs/API.md

@@ -1,5 +1,12 @@
 # NFE.io SDK v3 - API Reference
 
+> ⚠️ **Legacy reference (v3), not maintained.** This file was written for the 3.x SDK and is no
+> longer checked against the code. Several sections (service invoice `list`, `cancel` and
+> `sendEmail`, certificates, downloads) describe signatures and return types that changed in v5
+> and v6. The maintained reference is the [resource pages](./README.md) (Portuguese), the
+> [published skill](https://github.com/nfe/client-nodejs/tree/master/skills/nfeio-node-sdk) and the
+> type declarations shipped with the package (`dist/index.d.ts`), which editors show on hover.
+
 Complete API reference for the NFE.io Node.js SDK v3.
 
 ## Table of Contents

docs/EXTENDING.md

@@ -1,5 +1,10 @@
 # Extending the NFE.io SDK
 
+> ⚠️ **Legacy guide (v3), not maintained.** Written for the 3.x SDK. The extension patterns may
+> still apply, but class names, signatures and examples are not checked against the current
+> code. For the current API, see the [resource pages](./README.md) and the type declarations
+> shipped with the package (`dist/index.d.ts`).
+
 Guide for extending the NFE.io SDK with custom functionality, adapters, and integrations.
 
 ## Table of Contents

docs/EXTENSIBILITY_SUMMARY.md

@@ -1,5 +1,10 @@
 # NFE.io SDK v3 - Extensibility & Documentation Summary
 
+> ⚠️ **Documento legado (v3), não mantido.** Resumo de trabalho da época da 3.x, guardado como
+> registro histórico. Para a API atual, veja o [índice da documentação](./README.md), a
+> [skill publicada](https://github.com/nfe/client-nodejs/tree/master/skills/nfeio-node-sdk) e os
+> tipos que acompanham o pacote (`dist/index.d.ts`).
+
 ## ✅ Completed: JSDoc Documentation & API Reference
 
 ### 1. Comprehensive JSDoc Documentation

docs/README.md

@@ -59,7 +59,7 @@ O fluxo completo (retorno discriminado + polling) está em
 - [Emissão assíncrona e polling](./async-and-polling.md) — retorno discriminado e `createAndWait`.
 - [Roteamento multi-host / multi-chave](./multi-host-routing.md) — quais recursos usam qual host e chave.
 - [Paginação](./pagination.md) — listas page-style e cursor.
-- [Downloads (PDF/XML)](./downloads.md) — bytes binários e ZIPs.
+- [Downloads (PDF/XML)](./downloads.md) — bytes (`Buffer`) ou link, conforme o recurso.
 - [Webhooks](./webhooks.md) — assinatura, eventos e webhooks de conta.
 - [Erros](./errors.md) — hierarquia de erros e type guards.
 - [Emissão RTC (Reforma Tributária)](./rtc-emission.md) — leiautes IBS/CBS/IS.

docs/downloads.md

@@ -3,24 +3,27 @@ title: Downloads de PDF e XML no SDK Node.js da NFE.io
 sidebar_label: Downloads (PDF/XML)
 sidebar_position: 6
 slug: downloads-pdf-xml
-description: Baixe DANFE/PDF e XML como Buffer, individualmente ou em ZIP por empresa, com o Accept correto.
+description: Baixe DANFE/PDF e XML de uma nota identificada, em bytes (Buffer) ou por link, conforme o recurso.
 ---
 
 # Downloads (PDF/XML)
 
-Os métodos de download retornam um **`Buffer`** com os bytes do arquivo, sempre
-de uma nota identificada — o `invoiceId` é obrigatório.
+O formato do retorno depende do recurso. A NFS-e e a consulta de NF-e por chave devolvem os
+**bytes** do arquivo (`Buffer`); os demais devolvem um **link** para ele, e baixá-lo fica com a
+aplicação. Em todos, o download é de uma nota identificada.
 
 ```typescript
 import { writeFileSync } from 'node:fs';
 
-// PDF
+// NFS-e: bytes
 const pdf = await nfe.serviceInvoices.downloadPdf(companyId, invoiceId);
 writeFileSync('nota.pdf', pdf);
 
-// XML
 const xml = await nfe.serviceInvoices.downloadXml(companyId, invoiceId);
 writeFileSync('nota.xml', xml);
+
+// NF-e: link para o arquivo
+const { uri } = await nfe.productInvoices.downloadPdf(companyId, productInvoiceId);
 ```
 
 > **Não existe download em lote por empresa.** Até a versão 5.2.0 o `invoiceId`
@@ -37,20 +40,24 @@ O PDF/XML só existe após a nota atingir um **estado terminal**
 (`Issued`/`Cancelled`). Antes disso, o download pode retornar `404` — use
 [polling ou webhooks](./async-and-polling.md) para aguardar a emissão.
 
-## Outros downloads
+## Por recurso
+
+| Recurso | Métodos | Retorno |
+|---|---|---|
+| `serviceInvoices` | `downloadPdf`, `downloadXml` | `Buffer` |
+| `serviceInvoicesRtc` | `downloadCancellationXml` (XML do evento de cancelamento) | `Buffer` |
+| `productInvoices` | `downloadPdf` (`force?`), `downloadXml`, `downloadRejectionXml`, `downloadEpecXml`, `downloadCorrectionLetterPdf`, `downloadCorrectionLetterXml` | `NfeFileResource` (`{ uri }`) |
+| `consumerInvoices` (NFC-e) | `downloadPdf` (`force?`), `downloadXml`, `downloadRejectionXml` | `ConsumerInvoiceFileResource` (`{ uri }`) |
+| `inboundProductInvoices` | `getXml`, `getPdf`, `getEventXml` | `InboundFileResource` (`{ publicTemporaryUri }`) |
+| `transportationInvoices` | `downloadXml`, `downloadEventXml` | `InboundFileResource` (`{ publicTemporaryUri }`) |
+| `productInvoiceQuery` | `downloadPdf`, `downloadXml`, por chave de acesso | `Buffer` |
 
-| Recurso | Métodos |
-|---|---|
-| `serviceInvoices` | `downloadPdf`, `downloadXml` |
-| `serviceInvoicesRtc` | `downloadCancellationXml` (XML do evento de cancelamento) |
-| `consumerInvoices` (NFC-e) | `downloadPdf`, `downloadXml`, `downloadRejectionXml` (aceitam `environment`) |
-| `productInvoices` | `downloadPdf`, `downloadXml` |
-| `productInvoiceQuery` / `consumerInvoiceQuery` | `downloadPdf`/`downloadXml` por chave de acesso |
+O `publicTemporaryUri` é um link pré-assinado e temporário. A consulta de cupom CFe-SAT
+(`consumerInvoiceQuery`) está descontinuada: a plataforma não serve a rota.
 
-:::tip Streaming para arquivos grandes
-Os métodos carregam o arquivo inteiro em memória (`Buffer`). Para lotes grandes
-(ZIP da empresa), considere baixar fora do horário de pico e persistir em disco
-logo após o retorno.
+:::tip Memória
+Os métodos que devolvem `Buffer` carregam o arquivo inteiro em memória. Para muitas notas,
+baixe uma a uma e grave em disco logo após cada retorno.
 :::
 
 ## Próximos passos

docs/recursos/legal-entity-lookup.md

@@ -16,16 +16,16 @@ inscrição estadual.
 
 | Método | Descrição | Retorno |
 |---|---|---|
-| `getBasicInfo(cnpj)` | Dados cadastrais (razão social, endereço, CNAE, etc.). | `{ legalEntity }` |
-| `getStateTaxInfo(cnpj)` | Inscrição estadual. | dados de IE |
-| `getStateTaxForInvoice(cnpj, ...)` | IE adequada para emissão. | dados de IE |
-| `getSuggestedStateTaxForInvoice(cnpj, ...)` | IE sugerida para emissão. | dados de IE |
+| `getBasicInfo(cnpj, options?)` | Dados cadastrais (razão social, endereço, CNAE, etc.). | `{ legalEntity }` |
+| `getStateTaxInfo(state, cnpj)` | Inscrição estadual na UF indicada (ex.: `'SP'`). | dados de IE |
+| `getStateTaxForInvoice(state, cnpj)` | IE adequada para emissão. | dados de IE |
+| `getSuggestedStateTaxForInvoice(state, cnpj)` | IE sugerida para emissão. | dados de IE |
 
 ## Exemplo
 
 ```typescript
 const { legalEntity } = await nfe.legalEntityLookup.getBasicInfo('06990590000123');
-console.log(legalEntity.name, legalEntity.address?.city?.name);
+console.log(legalEntity?.name, legalEntity?.address?.city?.name);
 ```
 
 ## Próximos passos

docs/recursos/legal-people.md

@@ -19,7 +19,7 @@ uma empresa (tomadores/clientes PJ).
 | `create(companyId, data)` | Cria uma PJ. | `LegalPerson` |
 | `retrieve(companyId, personId)` / `update(...)` / `delete(...)` | CRUD. | `LegalPerson` / `void` |
 | `createBatch(companyId, data)` | Criação em lote. | resultado do lote |
-| `findByTaxNumber(companyId, cnpj)` | Busca por CNPJ. | `LegalPerson` |
+| `findByTaxNumber(companyId, cnpj)` | Busca por CNPJ. | `LegalPerson \| undefined` |
 
 ## Exemplo
 

docs/recursos/natural-people.md

@@ -19,7 +19,7 @@ uma empresa (tomadores/clientes PF).
 | `create(companyId, data)` | Cria uma PF. | `NaturalPerson` |
 | `retrieve(companyId, personId)` / `update(...)` / `delete(...)` | CRUD. | `NaturalPerson` / `void` |
 | `createBatch(companyId, data)` | Criação em lote. | resultado do lote |
-| `findByTaxNumber(companyId, cpf)` | Busca por CPF. | `NaturalPerson` |
+| `findByTaxNumber(companyId, cpf)` | Busca por CPF. | `NaturalPerson \| undefined` |
 
 ## Exemplo
 

docs/recursos/product-invoices.md

@@ -17,15 +17,15 @@ e a conclusão é notificada por [webhook](../webhooks.md) (sem polling).
 | Método | Descrição | Retorno |
 |---|---|---|
 | `create(companyId, data)` | Emite a NF-e (webhook-driven). | `NfeProductInvoiceIssueData` |
-| `createWithStateTax(companyId, data)` | Emite garantindo a inscrição estadual. | `NfeProductInvoiceIssueData` |
+| `createWithStateTax(companyId, stateTaxId, data)` | Emite pela inscrição estadual indicada. | `NfeProductInvoiceIssueData` |
 | `list(companyId, options)` | Lista NF-e. **Requer `environment`** (`Production`/`Test`). | envelope `{ productInvoices, hasMore }` |
 | `retrieve(companyId, invoiceId)` | Consulta por id. | dados da NF-e |
-| `cancel(companyId, invoiceId)` | Cancela a NF-e. | dados da NF-e |
+| `cancel(companyId, invoiceId, reason?)` | Cancela a NF-e (assíncrono). | `NfeRequestCancellationResource` |
 | `listItems` / `listEvents` | Itens e eventos da nota. | respostas específicas |
-| `downloadPdf` / `downloadXml` / `downloadRejectionXml` / `downloadEpecXml` | Downloads (Buffer). | `Buffer` |
-| `sendCorrectionLetter(companyId, id, data)` | Emite carta de correção (CC-e). | evento |
-| `downloadCorrectionLetterPdf` / `downloadCorrectionLetterXml` | Downloads da CC-e. | `Buffer` |
-| `disable` / `disableRange` | Inutilização de numeração. | resultado |
+| `downloadPdf` / `downloadXml` / `downloadRejectionXml` / `downloadEpecXml` | Link do arquivo, não os bytes; `downloadPdf` aceita `force?` para regenerar. | `NfeFileResource` (`{ uri }`) |
+| `sendCorrectionLetter(companyId, invoiceId, reason)` | Emite carta de correção (CC-e). `reason` é texto de 15 a 1.000 caracteres, sem acento. | `NfeRequestCancellationResource` |
+| `downloadCorrectionLetterPdf` / `downloadCorrectionLetterXml` | Link do arquivo da CC-e. | `NfeFileResource` (`{ uri }`) |
+| `disable(companyId, invoiceId, reason?)` / `disableRange(companyId, data)` | Inutilização de uma nota ou de uma faixa de numeração. | `NfeRequestCancellationResource` / `NfeDisablementResource` |
 
 :::warning `environment` obrigatório na listagem
 `list` exige `environment` (`'Production'` ou `'Test'`). Chamar sem o parâmetro
@@ -45,9 +45,12 @@ const invoice = await nfe.productInvoices.create(companyId, {
 ## Carta de correção (CC-e)
 
 ```typescript
-await nfe.productInvoices.sendCorrectionLetter(companyId, invoiceId, {
-  correction: 'Correção da descrição do item 1',
-});
+// texto de 15 a 1.000 caracteres, sem acento
+await nfe.productInvoices.sendCorrectionLetter(
+  companyId,
+  invoiceId,
+  'Correcao da descricao do item 1',
+);
 ```
 
 ## Próximos passos

docs/recursos/service-invoices.md

@@ -25,8 +25,8 @@ e-mail e download de PDF/XML.
 | `cancel(companyId, invoiceId)` | Cancela (assíncrono). | `CancelInvoiceResponse` (união discriminada) |
 | `cancelAndWait(companyId, invoiceId, options?)` | Cancela e faz polling até concluir. | `ServiceInvoiceData` |
 | `sendEmail(companyId, invoiceId)` | Reenvia a nota por e-mail ao tomador. | `{ sent, message }` |
-| `downloadPdf(companyId, invoiceId?)` | PDF da nota; sem `invoiceId`, baixa o ZIP da empresa. | `Buffer` |
-| `downloadXml(companyId, invoiceId?)` | XML da nota; sem `invoiceId`, baixa o ZIP da empresa. | `Buffer` |
+| `downloadPdf(companyId, invoiceId)` | PDF da nota. | `Buffer` |
+| `downloadXml(companyId, invoiceId)` | XML da nota. Não há download em lote: `invoiceId` é obrigatório desde a 6.0.0. | `Buffer` |
 
 As opções de `list` são `pageIndex`, `pageCount`, `issuedBegin`, `issuedEnd`,
 `createdBegin`, `createdEnd` e `hasTotals`.
@@ -84,9 +84,8 @@ import { writeFileSync } from 'node:fs';
 const pdf = await nfe.serviceInvoices.downloadPdf(companyId, invoiceId);
 writeFileSync('nota.pdf', pdf);
 
-// ZIP de todas as notas da empresa (sem invoiceId):
-const zip = await nfe.serviceInvoices.downloadXml(companyId);
-writeFileSync('notas-xml.zip', zip);
+const xml = await nfe.serviceInvoices.downloadXml(companyId, invoiceId);
+writeFileSync('nota.xml', xml);
 ```
 
 ## Cancelar e reenviar por e-mail

docs/recursos/state-taxes.md

@@ -15,21 +15,22 @@ empresa — **pré-requisito para emissão de NF-e**.
 
 | Método | Descrição | Retorno |
 |---|---|---|
-| `list(companyId)` | Lista as inscrições. | `{ stateTaxes, hasMore }` |
-| `create(companyId, data)` | Cria uma inscrição. | `StateTax` |
-| `retrieve(companyId, stateTaxId)` | Consulta por id. | `StateTax` |
-| `update(companyId, stateTaxId, data)` | Atualiza. | `StateTax` |
+| `list(companyId, options?)` | Lista as inscrições (paginação por cursor). | `{ stateTaxes, hasMore }` |
+| `create(companyId, data)` | Cria uma inscrição. | `NfeStateTax` |
+| `retrieve(companyId, stateTaxId)` | Consulta por id. | `NfeStateTax` |
+| `update(companyId, stateTaxId, data)` | Atualiza. | `NfeStateTax` |
 | `delete(companyId, stateTaxId)` | Remove. | `void` |
-| `switchAuthorizer(companyId, stateTaxId, data?)` | Troca o autorizador NF-e (ex.: SVRS). | `StateTax` |
+| `switchAuthorizer(companyId, stateTaxId, data?)` | Troca o autorizador NF-e (ex.: SVRS). | `NfeStateTax` |
 
 ## Exemplo
 
 ```typescript
 const { stateTaxes = [] } = await nfe.stateTaxes.list(companyId);
 
-await nfe.stateTaxes.switchAuthorizer(companyId, stateTaxes[0].id, {
-  authorizer: 'SVRS',
-});
+const primeira = stateTaxes[0];
+if (primeira?.id) {
+  await nfe.stateTaxes.switchAuthorizer(companyId, primeira.id, { authorizer: 'SVRS' });
+}
 ```
 
 ## Próximos passos