n8n-nodes-nfe 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - Unreleased
+
+A rewrite of the NFE.io node with the NFS-e API V3 and the tax reform fields, plus a trigger node and lookups. See [Migrating from 0.1](README.md#migrating-from-01).
+
+### BREAKING CHANGES
+
+- The **NFE.io** node is now node version 2 and only version 2. Workflows built with 0.1 must replace each NFE.io node by a new one. A node saved by 0.1 stops the execution with "This node was created with version 0.1 of n8n-nodes-nfe" and sends nothing to NFE.io.
+- Service invoices use the NFS-e API V3 instead of V1. CPF and CNPJ values come back as strings.
+- **Issue** has new fields: borrower by fields or JSON, optional groups for ISS, federal withholdings and the tax reform (IBS/CBS). The 0.1 fields `borrowerSource`, `borrowerData`, `taxation`, `withholdings` and `advancedOptions` no longer exist.
+- **Issue** waits for the city to authorize the invoice by default (60 seconds, up to 300) and returns the authorized invoice. A rejected invoice fails the node; a timeout returns the invoice with `waitTimedOut: true`.
+- **Issue** always sends an External ID (yours or one created by the node). An External ID that already exists returns that invoice with `alreadyExisted: true`.
+- Operations that return invoices or companies return **Simplified** output by default. Choose **Raw** for the full object.
+- **Download PDF** and **Download XML** return binary files.
+- The **Company** field is a list of your companies (or an ID) instead of free text.
+
+### Added
+
+- **NFE.io Trigger** node: starts a workflow from NFE.io webhook events (every event type of the API or All Events), with an optional company filter and signature check. The webhook is registered and removed by the node. After the node replaces its webhook, deliveries signed with the previous secret are accepted on the same URL for 5 minutes (NFE.io keeps signing with it for a short time).
+- Tax reform group (IBS/CBS) in **Issue**: Operation Indicator and Classification Code, with optional overrides and recipient. NFE.io calculates IBS and CBS.
+- **Download Cancellation XML** operation (national environment).
+- **Company** resource: Get and Get Many.
+- **Lookup** resource: company by CNPJ (numeric and alphanumeric), state registration, address by postal code (billable, need the Data API Key) and IBGE city code by postal code (free).
+- **Data API Key** field in the NFE.io API credential, used only for the lookups.
+- **Output** option (Simplified, Raw, Selected Fields).
+- **Cancel** can wait for the cancellation.
+- Get Many filters by accrual date and creation date.
+- Safe issue: after a timeout, network failure or 5xx answer, the node looks for the invoice by External ID and never sends it again.
+- Error messages with the NFE.io Request ID.
+- Example workflows in `examples/`.
+
+### Changed
+
+- Taxes are sent only when you add them. Otherwise NFE.io calculates them from the company settings.
+- The credential test calls `GET https://api.nfse.io/v2/companies`.
+- Requests have finite timeouts. Read requests are retried on network failures, 429 and 502–504; issue, cancel, email and the billable lookups are never retried automatically.
+- Built with `@n8n/node-cli` and checked by the n8n community package scanner. Published from GitHub Actions with npm provenance.
+
+### Fixed
+
+- **Issue** sent every tax field, including the ones left at 0, which replaced the automatic tax calculation.
+- **Get by External ID** failed for every ID.
+- **Get Many** returned one item with the first page only.
+- **Download PDF** returned a corrupted PDF as text.
+
+### Removed
+
+- Node version 1 of the NFE.io node.
+
+## [0.1.0] - 2026-03-01
+
+### Added
+
+- Initial release of the **NFe.io** community nodes for n8n.
+- `NFe.io` node with **Service Invoice** resource.
+- Support for the following operations against the NFe.io API:
+	- **Issue** a new service invoice (NFS-e).
+	- **Get** a service invoice by ID.
+	- **Get Many** service invoices for a company.
+	- **Get by External ID**.
+	- **Cancel** a service invoice.
+	- **Download PDF** of a service invoice.
+	- **Download XML** of a service invoice.
+	- **Send Email** with the service invoice to the borrower.
+
+[0.2.0]: https://github.com/nfe/n8n-nodes-nfe/compare/v0.1.0...0.2.0
+[0.1.0]: https://github.com/nfe/n8n-nodes-nfe/tree/v0.1.0

package/README.md

@@ -1,229 +1,242 @@
-## NFe.io n8n Community Nodes
+# n8n-nodes-nfe
 
-Community nodes for integrating [NFe.io](https://nfe.io/) with [n8n](https://n8n.io/).
+[n8n](https://n8n.io/) community nodes for [NFE.io](https://nfe.io/): issue and manage Brazilian service invoices (NFS-e) with the tax reform fields (IBS/CBS), start workflows from NFE.io webhook events and look up CNPJ and postal codes (CEP).
 
-These nodes let you issue and manage Brazilian electronic service invoices (NFS-e) via the NFe.io API directly from your n8n workflows.
+| Node | What it does |
+|---|---|
+| **NFE.io** | Service invoices (issue, get, list, cancel, download PDF and XML, send by email), companies of your account, CNPJ, state registration, postal code and IBGE city code lookups. Can also be used as a tool by the n8n AI Agent. |
+| **NFE.io Trigger** | Starts a workflow when NFE.io sends a webhook event, for example "service invoice issued". |
 
-> Note: This is a community package. It is not officially maintained by n8n GmbH.
+This is a community package maintained by NFE.io. It is not maintained by n8n GmbH.
 
----
-
-## Features
-
-Current version focuses on the **Service Invoice** resource and supports:
-
-- **Issue** a new service invoice (NFS-e)
-- **Get** a specific service invoice by ID
-- **Get Many** service invoices for a company
-- **Get by External ID** using your own external identifier
-- **Cancel** an issued service invoice
-- **Download PDF** representation of an invoice
-- **Download XML** representation of an invoice
-- **Send Email** with the invoice to the borrower
-
-All requests are made against the official NFe.io REST API and use a shared error-handling layer to surface API errors clearly inside n8n.
-
----
+- [Installation](#installation)
+- [Credentials](#credentials)
+- [NFE.io node](#nfeio-node)
+- [NFE.io Trigger node](#nfeio-trigger-node)
+- [Examples](#examples)
+- [Limitations](#limitations)
+- [Migrating from 0.1](#migrating-from-01)
+- [Security](#security)
 
 ## Requirements
 
-Before using this package you will need:
+- An NFE.io account ([create one](https://nfe.io/docs/documentacao/nossa-plataforma/criar-conta/)) with at least one company. Issuing invoices also needs the company's digital certificate ([upload](https://nfe.io/docs/documentacao/nossa-plataforma/upload-do-certificado-digital/)).
+- n8n with community nodes enabled. The package is tested with n8n 2.43.
+- For the trigger: an n8n instance reachable from the internet over HTTPS.
 
-- A running **n8n instance** that supports Community Nodes (n8n v1+)
-- An active **NFe.io account**
-- At least one configured **company** in NFe.io
-- An **NFe.io API key** with permission to access the desired company
+## Installation
 
-Please refer to the official NFe.io documentation for details on account and company setup: <https://nfe.io/docs/>
+### From the n8n editor
 
----
+1. Go to **Settings > Community Nodes** and select **Install**.
+2. Enter `n8n-nodes-nfe`, accept the risk notice and select **Install**.
 
-## Installation
+The **NFE.io** and **NFE.io Trigger** nodes then show up in the nodes panel. See the n8n guide: [Install community nodes from the GUI](https://docs.n8n.io/integrations/community-nodes/installation-and-management/gui-installation/).
 
-### Install via n8n Community Nodes (recommended)
+### Self-hosted, manual installation
 
-1. Open your n8n editor UI.
-2. Go to **Settings → Community Nodes**.
-3. Click **Install**.
-4. Enter the package name `n8n-nodes-nfe`.
-5. Confirm the installation and restart n8n if requested.
+Use this for queue mode or when the editor installation is turned off:
 
-After installation, the **NFe.io** node will be available in the node picker.
+```bash
+# inside the n8n container or host, as the user that runs n8n
+mkdir -p ~/.n8n/nodes
+cd ~/.n8n/nodes
+npm install n8n-nodes-nfe
+```
 
-### Self-hosted / manual installation
+Restart n8n afterwards. With Docker, open a shell first with `docker exec -it <container> sh`. See [Manual installation](https://docs.n8n.io/integrations/community-nodes/installation-and-management/manual-installation/). In queue mode, install the package on the main instance and on every worker.
 
-If you manage n8n as a local or self-hosted instance and prefer manual installation:
+The package has no runtime dependencies.
 
-1. Navigate to your n8n installation directory.
-2. Install the package:
+## Credentials
 
-	 ```bash
-	 npm install n8n-nodes-nfe
-	 ```
+Create a credential of type **NFE.io API**. It has two fields:
 
-3. Restart your n8n instance so it can load the new nodes.
+| Field | Required | Used for |
+|---|---|---|
+| **API Key** | Yes | Service invoices, companies and webhooks (the "Nota Fiscal" key of your account) |
+| **Data API Key** | Only for the billable lookups | CNPJ, state registration and postal code lookups (the "Dados" key of your account) |
 
-For more details, see the official n8n documentation on Community Nodes: <https://docs.n8n.io/integrations/community-nodes/>
+Both keys are in the NFE.io account app: open your subscription and the **Chaves de acesso** tab ([how to find them](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)). The node sends the right key to each NFE.io service, so one credential covers every operation. The credential test lists one company of the account with the API Key.
 
----
+The free IBGE city code lookup needs no key.
 
-## Credentials
+## NFE.io node
 
-The nodes use a dedicated **Nfe API** credential type.
+### Resources and operations
 
-1. In n8n, go to **Settings → Credentials**.
-2. Click **New** and search for **Nfe API**.
-3. Paste your **NFe.io API Key** into the **API Key** field.
-4. Save the credential.
+| Resource | Operation | Notes |
+|---|---|---|
+| Service Invoice | **Issue** | Issues an NFS-e. Waits for the city to authorize it by default. |
+| | **Get** | By NFE.io invoice ID |
+| | **Get by External ID** | By the ID you sent at issue time. Returns no item when nothing is found, or fails with **Fail If Not Found**. |
+| | **Get Many** | All invoices of a company, page by page, with **Return All** or a **Limit**. Filters: accrual date (competência) and creation date. |
+| | **Cancel** | Requests the cancellation and waits for it by default |
+| | **Download PDF** | Binary file |
+| | **Download XML** | Binary file |
+| | **Download Cancellation XML** | Binary file with the cancellation event. Only for invoices of the national environment (Ambiente Nacional). |
+| | **Send Email** | Sends the invoice to the borrower's email. Returns `{ "sent": true, "invoiceId": "..." }`. |
+| Company | **Get**, **Get Many** | Companies of your NFE.io account |
+| Lookup | **Get Company by CNPJ** | Registration data of a company. Numeric and alphanumeric CNPJ. **Billable.** |
+| | **Get State Registration** | State registrations (inscrição estadual) of a CNPJ in a state. **Billable.** |
+| | **Get Address by Postal Code** | Address of a CEP. **Billable.** |
+| | **Get City Code by Postal Code** | IBGE city code and name of a CEP. Free, no key. |
 
-Under the hood, requests are authenticated using the `Authorization` header with your API key. A quick test request is performed against `https://api.nfe.io/v1/companies` to validate the credential.
+The **Company** field lists the companies of your account (**From List**, searchable) or takes an ID (**By ID**, accepts expressions).
 
-Once configured, select this credential in the **NFe.io** node under the *Credentials* section.
+Service invoices use the NFE.io NFS-e API V3, which also handles companies with an alphanumeric CNPJ. CPF and CNPJ values are returned as strings, so leading zeros are kept.
 
----
+### Output
 
-## Node Overview
+Operations that return invoices or companies have an **Output** option:
 
-### Node: NFe.io
+- **Simplified** (default): the 10 main fields of an invoice (`id`, `externalId`, `number`, `status`, `flowStatus`, `flowMessage`, `issuedOn`, `servicesAmount`, `borrowerName`, `borrowerFederalTaxNumber`) or the main fields of a company.
+- **Raw**: the full object sent by NFE.io.
+- **Selected Fields**: a comma-separated list such as `number,status,borrower.name`.
 
-- **Display name:** NFe.io
-- **Resource:** `Service Invoice`
-- **Inputs:** Main
-- **Outputs:** Main
+Issue also adds `externalId`, `alreadyExisted` and, when it waited, `waitTimedOut` to the item, whatever the output mode.
 
-Each operation requires a **Company ID** field, which is the identifier of the company in NFe.io that owns the invoices.
+### Issuing an invoice
 
-### Supported Operations (Service Invoice)
+Required fields: **Company**, **City Service Code** (the service code of the company's city), **Description** and **Services Amount**.
 
-- **Issue**
-	- Create a new service invoice (NFS-e) for a given company.
-	- Uses `POST /v1/companies/{companyId}/serviceinvoices`.
+- **Borrower** (the customer): fill in the fields (name, CPF or CNPJ, email, address) or send the `borrower` object of the API as JSON. The type (person or company) is detected from the tax number.
+- **Taxes are optional.** Leave them out and NFE.io calculates ISS, rates and withholdings from the company settings. A value you add replaces the automatic calculation. Only the fields you add are sent: an empty group sends nothing.
+- **Federal Withholdings**: withheld PIS and COFINS go in this group. They are not the PIS and COFINS of the company's own tax.
 
-- **Get**
-	- Retrieve full details for a single invoice by its NFe.io invoice ID.
-	- Uses `GET /v1/companies/{companyId}/serviceinvoices/{invoiceId}`.
+#### Tax reform (IBS/CBS)
 
-- **Get Many**
-	- List multiple invoices for a company, optionally with filters (date ranges, status, pagination, etc., depending on the configured fields).
-	- Uses `GET /v1/companies/{companyId}/serviceinvoices`.
+Add **Operation Indicator** and **Classification Code** in the **Tax Reform (IBS/CBS)** group to send the `ibsCbs` group of the invoice. These are the only two required values, each with six digits:
 
-- **Get by External ID**
-	- Retrieve an invoice using your own external ID that was associated when issuing the invoice.
-	- Uses `GET /v1/companies/{companyId}/serviceinvoices/externalId/{externalId}`.
+- **Operation Indicator** (`cIndOp`) defines where IBS/CBS is due and which address the invoice needs. For example, `100301` (services such as consulting or software development) uses the borrower's address, so add it with the IBGE city code. See the [indicator table](https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/).
+- **Classification Code** (`cClassTrib`), for example `000001`.
 
-- **Cancel**
-	- Cancel an issued invoice, where allowed by the municipality and NFe.io rules.
-	- Uses `DELETE /v1/companies/{companyId}/serviceinvoices/{invoiceId}`.
+NFE.io calculates IBS and CBS. Use **Overrides (JSON)** only to replace the calculation or to send other fields of the group, and **Recipient (JSON)** when the destination is different from the borrower. The field reference is in the [NFS-e layout with the tax reform](https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/). Ask your accountant which codes apply to your services.
 
-- **Download PDF**
-	- Download the PDF representation of an invoice.
-	- Uses `GET /v1/companies/{companyId}/serviceinvoices/{invoiceId}/pdf`.
+#### Waiting for authorization
 
-- **Download XML**
-	- Download the XML representation of an invoice.
-	- Uses `GET /v1/companies/{companyId}/serviceinvoices/{invoiceId}/xml`.
+NFE.io accepts the invoice right away and the city authorizes it later (seconds to minutes, depending on the city). With **Wait for Authorization** on (default), the node checks the invoice every 2 seconds until it is issued or rejected, up to **Timeout (Seconds)** (60 by default, at most 300):
 
-- **Send Email**
-	- Trigger an email with the invoice to be sent to the borrower.
-	- Uses `PUT /v1/companies/{companyId}/serviceinvoices/{invoiceId}/sendemail`.
+- Issued: the item has the final invoice (`flowStatus: "Issued"`), ready for the PDF.
+- Rejected by the city (`IssueFailed`): the node fails with the reason sent by the city.
+- Timeout: the item has the invoice as it is, with `waitTimedOut: true`. Check it later with **Get**, or follow up from the **NFE.io Trigger**.
 
-All operations share a common error parser so API validation and business errors from NFe.io are exposed clearly to your workflow.
+For large batches, turn the wait off and use the trigger: n8n keeps the execution running while it waits. **Cancel** has the same option.
 
----
+#### External ID and safe re-runs
 
-## Usage Examples
+Every invoice is sent with an **External ID**, your unique ID for it, such as the order number.
 
-Here are some common ways to use the **NFe.io** node inside n8n:
+- Issuing again with an External ID that already exists returns the existing invoice with `alreadyExisted: true` instead of issuing a second one. Re-running a workflow for the same order is safe.
+- When NFE.io does not answer clearly (timeout, network failure, 5xx), the node **never sends the invoice again**. It looks for it by External ID for 30 seconds; if it is not found, the node fails with the External ID so you can check before trying again.
+- If you leave External ID empty, the node creates one per execution, node run and item. It protects **Retry On Fail** inside the same execution only: retrying a failed execution, or running the workflow again, creates a new ID and can issue a second invoice. Use an ID from your own system whenever the same sale can reach the node twice.
 
-### 1. Issue an invoice from an order
+### Files
 
-1. Receive order data from your e-commerce/ERP system (e.g. via webhook or database node).
-2. Map the customer and service details into the **Issue** operation fields of the **NFe.io** node.
-3. Store the returned NFe.io invoice ID or external ID in your system for later reference.
+**Download PDF**, **Download XML** and **Download Cancellation XML** put the file in a binary field (`data` by default, see **Put Output File in Field**) with the file name and MIME type, ready for an email, storage or messaging node. The PDF can take a few seconds to be available after the authorization; the node tries again for a short time.
 
-### 2. Send the invoice by email automatically
+### Lookups
 
-1. After issuing an invoice, add another **NFe.io** node with the **Send Email** operation.
-2. Use the `invoiceId` returned by the previous step.
-3. Optionally combine with other n8n nodes (e.g. Slack, email, CRM) to notify internal teams.
+CNPJ, state registration and postal code lookups are **billable per call** and need the **Data API Key**. The node validates the input (CNPJ check digits, 8-digit CEP, state) before calling, and makes **one call per run**: it does not retry them automatically, because a lookup that timed out on our side may already be billed. **Get City Code by Postal Code** is free and uses the open NFE.io endpoint.
 
-### 3. Periodic invoice sync
+### Use as an AI agent tool
 
-1. Use a **Cron** node to trigger a workflow periodically.
-2. Add an **NFe.io** node with the **Get Many** operation to list recent invoices.
-3. Upsert the invoice data into your internal database or analytics tooling.
+The NFE.io node can be connected to the **AI Agent** as a tool. Each tool node runs one operation; use [`$fromAI()`](https://docs.n8n.io/build/integrate-ai/ai-examples/use-ai-for-parameters/) to let the model fill fields such as the invoice ID or the CNPJ, and keep **Output** on **Simplified** so the model gets the main fields only.
 
-For request/response formats and advanced parameters, always refer to the official NFe.io API reference: <https://nfe.io/docs/rest-api/>.
+- **Issue** sends a real fiscal document. Put it behind [human review for tools](https://docs.n8n.io/build/integrate-ai/ai-examples/human-in-the-loop-for-tools/) so a person approves each call, and give the model an External ID that comes from your system.
+- Lookups are billable: say in the system message when the agent may call them. An agent can call a tool more often than you expect.
+- Fix the company in the tool node (By ID) instead of letting the model choose it.
 
----
+See [`examples/ai-agent-invoice-assistant.json`](examples/ai-agent-invoice-assistant.json).
 
-## Limitations and Notes
+### Errors
 
-- These nodes currently support only the **Service Invoice** (NFS-e) resource.
-- NFe.io is specific to Brazilian tax regulations and municipalities; some behaviors may vary by city.
-- You must have your company and services correctly configured in NFe.io for issuing invoices to succeed.
-- Network connectivity and NFe.io availability are required for all operations.
+Messages say what happened and how to fix it, and include the NFE.io **Request ID** (`x-request-id`) to share with NFE.io support. With **Continue On Fail**, each failed item becomes an output item with the error, and the other items go on.
 
-Future versions may add additional resources and operations as needed.
+## NFE.io Trigger node
 
----
+The trigger registers a webhook in your NFE.io account when the workflow is activated (or when you select **Listen for test event**) and removes it when the workflow is deactivated (or after the test event).
 
-## Development
+- **Events**: every event type offered by the NFE.io API, loaded when you open the node (with a built-in list when the API cannot be reached), plus **All Events**. Service invoice events include issued successfully, issue failed, cancelled successfully and cancellation failed; the list also has product (NF-e), consumer (NFC-e), received (inbound) documents, product tax and tax payment events. See the [event catalog](https://nfe.io/docs/webhooks/catalogo-de-eventos/).
+- **Company** (optional): only start the workflow for events of this company. NFE.io webhooks belong to the whole account, so without this filter the workflow starts for events of every company of the account. Events with no company in them (for example product tax events) always start the workflow.
+- **Signature**: every delivery is checked against the `X-Hub-Signature` header (HMAC-SHA1 of the raw body with a secret the trigger creates). Deliveries with an invalid signature get HTTP 401 and do not start the workflow.
 
-If you want to work on this package locally:
+Each event becomes one item:
 
-1. Clone the repository:
+```json
+{
+  "event": "service_invoice.issued_successfully",
+  "resource": "service_invoice",
+  "action": "issued_successfully",
+  "companyId": "...",
+  "deliveryId": "...",
+  "payload": { "id": "...", "number": "...", "flowStatus": "Issued", "borrower": { "name": "..." } }
+}
+```
 
-	 ```bash
-	 git clone https://github.com/nfeio/n8n-nodes-nfe.git
-	 cd n8n-nodes-nfe
-	 ```
+`payload` is the document sent by NFE.io (for service invoices, the invoice). `companyId` is `null` when the event does not say which company it belongs to. `deliveryId` is the delivery ID sent by NFE.io (`X-Hook-Id`).
 
-2. Install dependencies:
+## Examples
 
-	 ```bash
-	 npm install
-	 ```
+Importable workflows are in [`examples/`](examples/):
 
-3. Run in development mode:
+- Issue an NFS-e with IBS/CBS for a paid order, wait for the authorization, download the PDF and email it.
+- When an NFS-e is issued, download the PDF and send it to Telegram.
+- An AI agent that finds invoices, looks up a CNPJ and issues an NFS-e only after a person approves it.
 
-	 ```bash
-	 npm run dev
-	 ```
+## Limitations
 
-	 This uses the `@n8n/node-cli` to run the node in a local n8n environment.
+- **Each test listen and each activation creates a webhook in your NFE.io account.** It is removed when you stop the listen, when the first test event arrives or when you deactivate the workflow.
+- **Before registering, the trigger reads the webhook list of the account** and removes webhooks with exactly its own URL. They are leftovers of this same node: a test listen started again without stopping the previous one (n8n replaces the listen and the node loses track of the previous webhook) or a creation that timed out. Webhooks with any other URL are never changed. A leftover of an old n8n URL that the node no longer tracks stays in the account: webhooks created by this node have `source=n8n-nodes-nfe` in their URL, and you can list and remove them with the [NFE.io webhooks API](https://nfe.io/docs/documentacao/webhooks/integracao/).
+- **NFE.io takes a moment to notice a new webhook.** In our tests, an event right after a new webhook was created was not delivered. After activating a workflow for the first time, wait two minutes before relying on events, and use **Get Many** with a date filter to catch up on events of that window.
+- **After publishing, deliveries signed with the previous webhook secret are accepted for 5 minutes.** For a short time after the trigger replaces its webhook (deactivate and activate again, publish a change, change the events), NFE.io still signs events with the secret of the removed webhook. The trigger accepts that secret on the same URL for 5 minutes, then refuses it with 401. Test listens do not keep it: n8n starts each listen with empty data, so an event signed with the secret of an earlier listen gets 401.
+- **Repeated deliveries are not removed.** NFE.io delivers an event again when your n8n does not answer with success (a redelivery keeps the same `deliveryId`; each webhook has its own). Use `deliveryId` to skip repeats (for example, keep the processed IDs in a data table).
+- **The format of events other than service invoices comes from the NFE.io documentation.** Service invoice events were checked against real deliveries; the other families were built from the event catalog. The trigger passes their body as `payload` without changing it.
+- **CNPJ, state registration and postal code lookups are billable and not retried.** If one fails with a timeout, run it again yourself.
+- **The automatic External ID only protects retries inside the same execution.** See [External ID and safe re-runs](#external-id-and-safe-re-runs).
+- With **All Events** and no company filter, the workflow receives the events of every company of the account.
+- IBS/CBS: the node sends the group as documented and NFE.io calculates the values. How the city prints them depends on the company's tax regime and the city.
+- Operations for product (NF-e) and consumer (NFC-e) invoices are not in the action node yet; the trigger already receives their events.
 
-4. Build the production bundle:
+## Migrating from 0.1
 
-	 ```bash
-	 npm run build
-	 ```
+Version 0.2.0 is a new node. **Workflows built with 0.1 do not run on 0.2**: replace each old NFE.io node by a new one and set its fields again. Until you do, an old node stops the execution with "This node was created with version 0.1 of n8n-nodes-nfe" and sends nothing to NFE.io, including in active workflows.
 
-5. Lint the code:
+| | 0.1 | 0.2 |
+|---|---|---|
+| Node | `NFe.io`, node version 1 | `NFE.io`, node version 2. Nodes saved with version 1 do not run and must be added again. |
+| API | NFS-e V1 | NFS-e V3 (alphanumeric CNPJ, tax reform fields) |
+| Company | Free text | List of your companies or ID |
+| Issue fields | Fixed groups that sent every tax field, including the ones left at 0 | Optional groups: only what you add is sent; NFE.io calculates the rest |
+| Issue result | The first answer of NFE.io (invoice still processing) | The authorized invoice (Wait for Authorization, on by default) |
+| External ID | Optional | Always sent (yours or automatic); a repeated ID returns the existing invoice |
+| Get by External ID | Failed for every ID | Fixed |
+| Get Many | One item with the first page | One item per invoice, every page with Return All |
+| Download PDF and XML | Text in the JSON (the PDF was corrupted) | Binary files |
+| Output | Raw | Simplified, Raw or Selected Fields |
+| Credential | API Key | Same credential type (`nfeApi`); existing credentials keep working. Add the Data API Key for the lookups. |
+| New | | Company resource, Lookup resource, Download Cancellation XML, NFE.io Trigger |
 
-	 ```bash
-	 npm run lint
-	 # or
-	 npm run lint:fix
-	 ```
+To keep a 0.1 workflow running while you migrate, stay on version 0.1.0 of the package.
 
-For publishing a new version to npm, follow the usual `n8n-node` release flow using the `npm run release` script.
+## Security
 
----
+Report security issues privately to [hackers@nfe.io](mailto:hackers@nfe.io). Please do not open a public issue for them.
 
-## Support & Issues
+- Keys are stored only in the n8n credential and are never written to the output or to error messages.
+- Download links of PDF and XML files are followed without the API key and never appear in the output.
+- The webhook secret is kept in the workflow static data, as n8n triggers do. People who can open the workflow in n8n can read it. When the trigger replaces its webhook, the previous secret stays there too and is still accepted for 5 minutes on the same URL; it is never written to the output.
 
-If you run into problems using these nodes:
+## Support
 
-- Check the NFe.io API status and documentation: <https://status.nfe.io/> and <https://nfe.io/docs/>
-- Open an issue in this repository: <https://github.com/nfeio/n8n-nodes-nfe/issues>
+- Status of the NFE.io services: <https://status.nfe.io/>
+- NFE.io documentation: <https://nfe.io/docs/>
+- Bugs and feature requests: [GitHub issues](https://github.com/nfe/n8n-nodes-nfe/issues)
 
-Bug reports and feature requests are welcome.
+## Development
 
----
+See [docs/development.md](docs/development.md) and [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-This project is licensed under the **MIT License**.
-
-See the package metadata and repository for full license details.
+[MIT](LICENSE)

package/dist/credentials/NfeApi.credentials.d.ts

@@ -1,4 +1,4 @@
-import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+import type { ICredentialDataDecryptedObject, ICredentialTestRequest, ICredentialType, IHttpRequestOptions, INodeProperties } from 'n8n-workflow';
 export declare class NfeApi implements ICredentialType {
     name: string;
     displayName: string;
@@ -8,6 +8,6 @@ export declare class NfeApi implements ICredentialType {
     };
     documentationUrl: string;
     properties: INodeProperties[];
-    authenticate: IAuthenticateGeneric;
+    authenticate(credentials: ICredentialDataDecryptedObject, requestOptions: IHttpRequestOptions): Promise<IHttpRequestOptions>;
     test: ICredentialTestRequest;
 }

package/dist/credentials/NfeApi.credentials.js

@@ -1,10 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NfeApi = void 0;
+const DATA_API_HOSTS = ['legalentity.api.nfe.io', 'address.api.nfe.io'];
+function requestHost(requestOptions) {
+    try {
+        return new URL(requestOptions.url, requestOptions.baseURL).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
 class NfeApi {
     constructor() {
         this.name = 'nfeApi';
-        this.displayName = 'Nfe API';
+        this.displayName = 'NFE.io API';
         this.icon = { light: 'file:nfe.svg', dark: 'file:nfe.svg' };
         this.documentationUrl = 'https://github.com/nfe/n8n-nodes-nfe?tab=readme-ov-file#credentials';
         this.properties = [
@@ -15,20 +24,33 @@ class NfeApi {
                 typeOptions: { password: true },
                 required: true,
                 default: '',
+                description: 'Main key of the NFE.io account, used for service invoices, companies and webhooks',
             },
-        ];
-        this.authenticate = {
-            type: 'generic',
-            properties: {
-                headers: {
-                    Authorization: '={{$credentials.apiKey}}',
-                },
+            {
+                displayName: 'Data API Key',
+                name: 'dataApiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                description: 'Key for the data services (CNPJ, state registration and postal code lookups). Only needed for the Lookup operations.',
             },
-        };
+        ];
         this.test = {
             request: {
-                baseURL: 'https://api.nfe.io',
-                url: '/v1/companies',
+                baseURL: 'https://api.nfse.io',
+                url: '/v2/companies',
+                qs: { limit: 1 },
+            },
+        };
+    }
+    async authenticate(credentials, requestOptions) {
+        const useDataKey = DATA_API_HOSTS.includes(requestHost(requestOptions));
+        const key = useDataKey ? credentials.dataApiKey : credentials.apiKey;
+        return {
+            ...requestOptions,
+            headers: {
+                ...requestOptions.headers,
+                Authorization: typeof key === 'string' ? key : '',
             },
         };
     }

package/dist/credentials/NfeApi.credentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"NfeApi.credentials.js","sourceRoot":"","sources":["../../credentials/NfeApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,MAAM;IAAnB;QACC,SAAI,GAAG,QAAQ,CAAC;QAEhB,gBAAW,GAAG,SAAS,CAAC;QAExB,SAAI,GAAG,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAW,CAAC;QAGhE,qBAAgB,GAAG,qEAAqE,CAAC;QAEzF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;aACX;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,aAAa,EAAE,0BAA0B;iBACzC;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,oBAAoB;gBAC7B,GAAG,EAAE,eAAe;aACpB;SACD,CAAC;IACH,CAAC;CAAA;AApCD,wBAoCC"}
+{"version":3,"file":"NfeApi.credentials.js","sourceRoot":"","sources":["../../credentials/NfeApi.credentials.ts"],"names":[],"mappings":";;;AASA,MAAM,cAAc,GAAG,CAAC,wBAAwB,EAAE,oBAAoB,CAAC,CAAC;AAExE,SAAS,WAAW,CAAC,cAAmC;IACvD,IAAI,CAAC;QACJ,OAAO,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC;AAED,MAAa,MAAM;IAAnB;QACC,SAAI,GAAG,QAAQ,CAAC;QAEhB,gBAAW,GAAG,YAAY,CAAC;QAE3B,SAAI,GAAG,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAW,CAAC;QAEhE,qBAAgB,GAAG,qEAAqE,CAAC;QAEzF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EACV,mFAAmF;aACpF;YACD;gBACC,WAAW,EAAE,cAAc;gBAC3B,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,WAAW,EACV,sHAAsH;aACvH;SACD,CAAC;QAiBF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,qBAAqB;gBAC9B,GAAG,EAAE,eAAe;gBACpB,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;aAChB;SACD,CAAC;IACH,CAAC;IAtBA,KAAK,CAAC,YAAY,CACjB,WAA2C,EAC3C,cAAmC;QAEnC,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;QACxE,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC;QACrE,OAAO;YACN,GAAG,cAAc;YACjB,OAAO,EAAE;gBACR,GAAG,cAAc,CAAC,OAAO;gBACzB,aAAa,EAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;aACjD;SACD,CAAC;IACH,CAAC;CASD;AArDD,wBAqDC"}

package/dist/nodes/Nfe/Nfe.node.d.ts

@@ -1,4 +1,11 @@
-import { type INodeType, type INodeTypeDescription } from 'n8n-workflow';
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { getCompanies } from './methods/listSearch';
 export declare class Nfe implements INodeType {
     description: INodeTypeDescription;
+    methods: {
+        listSearch: {
+            getCompanies: typeof getCompanies;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
 }