diff --git a/CHANGELOG.md b/CHANGELOG.md index be065b2..ee740cb 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/API.md b/docs/API.md index a10c86a..565a8e2 100644 --- a/docs/API.md +++ b/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 diff --git a/docs/EXTENDING.md b/docs/EXTENDING.md index 71d1da9..1b49988 100644 --- a/docs/EXTENDING.md +++ b/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 diff --git a/docs/EXTENSIBILITY_SUMMARY.md b/docs/EXTENSIBILITY_SUMMARY.md index 2cbe763..0eeeb5b 100644 --- a/docs/EXTENSIBILITY_SUMMARY.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 070fb87..54d6457 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/downloads.md b/docs/downloads.md index 195477f..866b102 100644 --- a/docs/downloads.md +++ b/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 diff --git a/docs/recursos/legal-entity-lookup.md b/docs/recursos/legal-entity-lookup.md index 258c200..23d48ec 100644 --- a/docs/recursos/legal-entity-lookup.md +++ b/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 diff --git a/docs/recursos/legal-people.md b/docs/recursos/legal-people.md index 1fcc86c..778d8df 100644 --- a/docs/recursos/legal-people.md +++ b/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 diff --git a/docs/recursos/natural-people.md b/docs/recursos/natural-people.md index 5942c29..6325ec1 100644 --- a/docs/recursos/natural-people.md +++ b/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 diff --git a/docs/recursos/product-invoices.md b/docs/recursos/product-invoices.md index 56552ed..df595c9 100644 --- a/docs/recursos/product-invoices.md +++ b/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 diff --git a/docs/recursos/service-invoices.md b/docs/recursos/service-invoices.md index 8cfa1fb..1765947 100644 --- a/docs/recursos/service-invoices.md +++ b/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 diff --git a/docs/recursos/state-taxes.md b/docs/recursos/state-taxes.md index 17f44aa..f9fd33d 100644 --- a/docs/recursos/state-taxes.md +++ b/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