n8n-nodes-nibo-empresas

Automate the finances of a Brazilian company in n8n, through the
Nibo Empresas API.

Contacts, accounts payable and receivable, settlements, bank accounts and transfers,
boletos with Pix, NFS-e service invoices, attachments and the chart of accounts —
17 resources, 75 operations, all of it without a single HTTP Request node.

Zero runtime dependencies. Published with npm provenance. Usable as an AI Agent tool.

🇧🇷 The node speaks Portuguese

Every label the editor shows — resources, operations, fields, hints — is translated to
Brazilian Portuguese. English is the default; to switch, set this in your n8n:

NIBO_NODE_LOCALE=pt-BR

The language is read when n8n loads the node, so the change takes effect on the next
restart. Nothing a workflow stores changes with the language — the same flow runs
identically in either one, and switching is a restart rather than a migration.

Do not use N8N_DEFAULT_LOCALE: on n8n 2.33.7 any value other than en brings down
the route that hands node descriptions to the editor (ENOENT: scandir), for native
and community nodes alike.

---

🇧🇷 O node fala português

Todo rótulo que o editor mostra — recursos, operações, campos, dicas — está traduzido
para o português do Brasil. O padrão é inglês; para trocar, defina no seu n8n:

NIBO_NODE_LOCALE=pt-BR

O idioma é lido quando o n8n carrega o node, então a mudança vale a partir do próximo
reinício. Nada do que um workflow guarda muda com o idioma — o mesmo fluxo roda
igual nos dois, e trocar é um reinício, não uma migração.

Não use N8N_DEFAULT_LOCALE: em n8n 2.33.7 qualquer valor diferente de en derruba a
rota que entrega as descrições dos nodes ao editor (ENOENT: scandir), para nodes
nativos e de comunidade igualmente.

---

What it can do

Resource	Operations
Contact - Customer / Supplier / Employee / Partner	Create · Get · Get Many · Update · Delete
Schedule - Credit — a receivable	Create · Get · Get Many · Update · Delete
Schedule - Debit — a payable	Create · Get · Get Many · Update · Delete
Schedule - File	Get Many · Attach · Delete
Schedule - Annotation	Create
Transaction - Payment / Receipt	Settle · Create · Get · Get Many · Delete
Category — the chart of accounts	Create · Get · Get Many · Get Many Groups · Get Tree
Cost Center	Create · Get · Get Many · Update · Delete
Bank Account	Create · Get Many · Get Balances · Import Bank Statement · Update
Bank Transfer	Create · Get Many · Delete
File	Upload · Upload and Attach · Download
Collection — a boleto with Pix	Create · Get · Get Many · Cancel · Get Many Profiles
Service Invoice — the NFS-e	Issue · Get · Get Many · Cancel · Get Many Service Profiles

Every gap in that table is a gap in the API, not in the node: a category cannot be edited or
deleted, a settled entry cannot be updated, a bank account cannot be read one by one or
archived, and a stored file cannot be listed. Each is documented where you meet it.

A receivable can be born complete

Schedule - Credit · Create does more than write a line. In the same operation it can:

• generate the boleto — immediately, or a number of days before the due date;
• issue the NFS-e — immediately, on settlement, or when the boleto goes out;
• repeat — as a recurrence (every N days, weeks, months or years, ending on a date, after
  N occurrences or never), or split into installments.

Installments come either way: say how many and how far apart and the node writes the parcels —
dates clamped to short months, so a plan starting on the 31st falls on the 28th in February and
returns to the 31st in March, and the leftover cents go on the first parcels so the sum closes —
or list every parcel yourself, for a plan that is not regular.

Each of the three defaults to no, so a workflow that ignores them writes a plain schedule.
The created item comes back carrying its sibling parcels.

---

Installation

In n8n, go to Settings → Community Nodes → Install and enter:

n8n-nodes-nibo-empresas

Or follow the community node installation guide.

The package has no runtime dependencies — nothing is pulled into your n8n instance
beyond the node itself. Every release is built in CI, gated on lint, the official n8n
community rules and a unit-test suite, then published with npm provenance and scanned
by @n8n/scan-community-package.

Credentials

You need an organization API token from Nibo:

1. In Nibo, open the organization.
2. Go to More options → Settings → API and copy the token.
3. In n8n, create a Nibo Empresas API credential and paste it.

In this API the token is the organization — every request reads that company's books,
and there is no organization parameter in any route. To work with another company, use
another token.

Many companies in one node. Set Authentication to API Token (Per Item) and the
token is read from each input item ({{ $json.apiToken }}), so one node can walk a whole
portfolio in a loop. An n8n credential cannot be selected per item — that is what this mode
is for. Note that a token in a parameter stays visible in the execution history; where that
matters, use credentials.

---

What you get over a plain HTTP Request node

Searchable pickers instead of GUIDs. Contacts are searched on the server as you type —
an organization can hold thousands. Categories arrive grouped and ordered like the Nibo
screen, filtered to the half that fits the schedule. Cost centers, bank accounts, collection
profiles and service profiles all load from the credential on the node.

A filter builder that writes the OData for you. Pick a field, an operator and a value;
add as many conditions as you need and join them with And or Or. Each field menu holds
only what the API was verified to filter on, and each value gets the literal the API demands —
quoted for text, bare for IDs and amounts, apostrophes doubled. Filtering happens on the
server, so what does not match is never paged through.

Need something the conditions cannot say? Filter (OData) under Options takes a raw
expression, and using it takes over automatically.

Pagination that survives the 500-record cap. Return All walks the collection with
$skip, applying the stable sort key each collection actually requires. The node also
compares the record count the server reports before and after the scan and fails if records
went missing mid-scan — turn Fail on Incomplete Results off for reads where that does not
matter.

Updates that cannot silently erase data. The Nibo PUT takes the whole record and zeroes
every field left out of the body. So Update never sends a bare PUT: it reads the record,
merges your fields onto it, writes the whole thing back, and reads it again to confirm the
change took. A field you do not add is not touched; the item fails, naming the field, if a
write did not land.

Errors you can act on. This API answers HTTP 500 for invalid requests too, which makes
a generic failure message useless. The node reads the body and tells them apart:

What happened	Retry helps?
Token rejected (401)	No — fix the token
validation_error — bad filter, broken business rule	No — the request is invalid
internal_server_error	Yes — a genuine server-side failure
Over 14 calls/second (429)	Yes — and see Interval Between Requests

Failures are per item, carrying the item index, so one bad row does not take the run
down. Set the node's On Error to Continue (using error output) to route them elsewhere.

Rate limiting by default. Interval Between Requests waits 1000 ms between calls —
between items and between pages, never before the first. Nibo allows 14 calls per second per
organization; the default stays well clear. Set it to 0 to remove the gap.

---

Before you automate

The Nibo API does a few things quietly. These are the ones that cost money or cannot be undone.

🔴 Issuing is real and immediate. Generate Boleto and Issue Invoice set to
Immediately fire as the schedule is created — the charge is issued, the NFS-e goes to the
city hall. A note cannot be undone, only cancelled, and a cancelled note stays in the
company's fiscal history.

🔴 Public links. The url of an attachment, the url of a charge and the pdfFileUrl
/ xmlFileUrl of a note all serve their content with no token of any kind. Cancelling a
note does not take its documents down. Treat the link as the document.

⚠️ An update disarms a pending automation. Any PUT on a schedule wipes the boleto and
NFS-e automations the creation programmed, and no read can rebuild them. Do the updates
first and create with the automation last.

⚠️ Some acts have no way back. Creating a category and creating a bank account
cannot be undone through this API — no edit, no delete, no archive. Schedule - File ·
Delete destroys the document rather than detaching it. An annotation, once written,
can never be read, edited or deleted.

⚠️ Listings are eventually consistent. A schedule the get-by-id already answers can be
absent from its collection for a second or two, and a deleted one can linger. Chain by the
ID the create hands back rather than by re-listing.

⚠️ The sign of a debit belongs to the endpoint. The same payable reads -500 through
Get and +500 through Get Many; openValue is positive in both. The node forwards
what the API answered rather than inventing a convention. Compare with openValue, or
Math.abs().

⚠️ Two things need switching on in Nibo, and nothing in the API says whether they are:
splitting a schedule across several categories, and issuing charges or notes at all —
those need a collection profile / service profile, which cannot be created through
the API.

The node guards what it can: it refuses a settlement with no bank account (the API would
answer 200 and create an unsettled schedule instead), refuses a schedule ID of the wrong kind,
refuses a second charge on a schedule that already has one, checks the schedule exists before
attaching anything to it, and validates a bank-statement batch line by line — because that
import is accepted half way, in silence.

---

Usage

Add the Nibo Empresas node, select the credential, pick a resource and an operation. Each
record becomes one n8n item; each input item is one operation.

Read your customers

Contact - Customer · Get Many → Return All on, Filters: Name · Contains · ACME

Bill a customer, with the boleto and the note

Contact - Customer · Get Many (filtered by name)
→ Schedule - Credit · Create: Stakeholder by ID from the previous item, a Due Date,
an Accrual Date, one line under Categories, Generate Boleto = Immediately

Mark a bill as paid

Schedule - Debit · Get Many → Filters: Is Paid · Is · ☐
→ Transaction - Payment · Settle: the scheduleId, a bank account and the date

Walk a portfolio of companies

Set Authentication to API Token (Per Item), point API Token at {{ $json.apiToken }}
and feed the node one item per organization.

Accrual Date is worth filling in. Left empty, the API silently copies the due date —
which files the income or expense in the month the money moves rather than the month it was
earned. It is on the screen, not behind a menu, for that reason.

---

Compatibility

Developed and tested against n8n 2.18.5 (self-hosted), installed through the Community
Nodes screen. Node.js ≥ 20.15 to build.

Resources

• n8n community nodes documentation
• Nibo API documentation
• Changelog — the full release history, and what was measured against the API
  to get there

Disclaimer

This is an independent community package and is not an official Nibo product. Nibo and the
Nibo logo are trademarks of their respective owner, used here solely to identify the service
the node integrates with.

License

MIT