Xentral

v1.4.6

Last updated Nov 1, 2026

n8n community node for Xentral ERP. 41 resources, 257 operations, a Custom API Call for every endpoint, and a trigger for 162 webhook events. Built by next8n.

233 Weekly Downloads

2,766 Monthly Downloads

View on NPM GitHub Repository

Included Nodes

Xentral

Xentral Trigger

Description

n8n-nodes-xentral

Connect Xentral ERP to n8n. 41 resources, 257 operations, a Custom API Call that reaches every Xentral endpoint, and a webhook trigger for 162 Xentral events.

![npm version](https://www.npmjs.com/package/n8n-nodes-xentral)
![npm downloads](https://www.npmjs.com/package/n8n-nodes-xentral)
![CI](https://github.com/mjmirza/n8n-nodes-xentral/actions/workflows/ci.yml)
![License MIT](LICENSE)
![Signed with npm provenance](https://www.npmjs.com/package/n8n-nodes-xentral#provenance)

What is this?

Xentral is an ERP used by e-commerce, wholesale and manufacturing teams to run orders, invoices, stock and shipping. This package adds two nodes to n8n so those records can move between Xentral and every other tool you use, without writing code.

It is for operations teams and automation builders who already run Xentral and want orders, documents and stock to flow on their own.

What you get

Orders that create themselves. A web shop order, a form or an email turns into a Xentral sales order, offer or invoice without anyone typing it in.
Documents that leave on time. Release and send offers, invoices, delivery notes and purchase orders the moment the data is complete, with line items and attachments.
Stock you can act on. Read and update products, prices, warehouses and storage locations, and book goods receipts against purchase orders or returns.
Reactions within seconds. The Xentral Trigger starts a workflow when an order is created, a delivery note is sent or a product changes, so nothing waits for a nightly export.
Searches that find the right product. Product search matches the article number, the EAN and the name, with article number matches first.
Customer lookup by exact value. Customer Search finds a customer by its exact customer number, name or email. Xentral’s customer API does not support partial matches, so the node does not pretend to.
Safe defaults. HTTPS only, literal internal addresses (localhost, private, loopback and link-local IPs in any decimal, hex or octal spelling, and IPv6 literals) blocked for every request including the credential test, IDs validated before they reach a URL, writes never retried after a gateway error, and Xentral error details shown in the n8n UI. Hosts with percent-encoding or non-ASCII characters, and URLs with user info (@), backslashes or spaces, are refused, and redirects are never followed. The node does not resolve DNS, so a public hostname that points at an internal address is not caught here. Use your n8n instance’s egress or network policy for that.
Trigger that fails closed. Every delivery is checked against its HMAC signature and must be no older than five minutes. Anything unverifiable is rejected with 401 and never starts the workflow.
Every endpoint within reach. Custom API Call sends any request in the Xentral API with your saved credential, so a rare accounting, tax or POS endpoint never needs a separate HTTP Request node.
Works with AI agents. The Xentral action node is marked as a tool, so an n8n AI Agent can call Xentral operations directly. The trigger starts workflows and is not a tool.

From install to first result

1. In n8n open Settings, then Community Nodes, click Install, and enter n8n-nodes-xentral.
2. In Xentral create a Personal Access Token under Administration, Account settings, Developer Settings, Personal Access Tokens (admin rights required, see the Xentral authentication guide).
3. In n8n add a Xentral API credential with your instance URL, for example https://yourcompany.xentral.com, and paste the token exactly as Xentral shows it. Click Test to confirm the connection.
4. Add a Xentral node to a workflow, choose Product and Get Many, and run it.
5. Your Xentral products appear as items in the output panel, and you can filter them, map them or pass them to any other node.

Nodes

Resources and operations

Design decisions behind a few deliberate limits are in docs/DESIGN-DECISIONS.md.

Operations whose endpoint Xentral marks beta show a notice in the node, because Xentral may change them without warning. That covers Customer Delivery Address, Supplier Invoice and some User reads, Production Create, Get and Get Many, Proforma Invoice Create, Get, Get Many, Update and its line item writes, Delivery Note and Return creates, updates and line item writes, Return Create From Delivery Note, and Invoice Create From Sales Order.

API coverage

The Xentral public API (specs dated 2026-10-26) has 573 operations, 542 of them not deprecated. This release has dedicated operations for 244 of those 542, up from 177. Custom API Call reaches all 573, which a test checks against every documented path, including parameterized ones such as /api/v2/salesOrders/{id}/files and /api/v2/productsTagAssignments. The specs the node was built against are in specs/.

Custom API Call

Choose the Custom API Call resource to call any Xentral endpoint with your saved credential. Authentication, retries with backoff and Xentral error details work the same as in every other operation.

| Field | Meaning |
|——-|———|
| Method | GET, POST, PATCH, PUT or DELETE |
| API Version | V1, V2 or V3. A path that starts with /api/v2/ or similar sets the version |
| Path | The part after /api//, for example posJournals |
| Query Parameters | JSON, for example filters or pagination |
| Body | JSON, shown for POST, PATCH, PUT and DELETE. A DELETE sends it only when it is not empty, for bulk deletes. n8n’s HTTP helper never sends a body with GET, so a GET endpoint that reads one (the product label download options) runs with its defaults |
| Content Type | application/json by default. Some endpoints need a vendor type such as application/vnd.xentral.minimal+json |
| Accept | Empty by default, which asks for JSON, or any type in Text and File mode. Set application/pdf to download a document such as an invoice as PDF |
| Full Response | Off by default, which splits the data array into items. On returns the whole JSON body as one item, keeping pagination cursors and meta such as totalResults |
| Response Format | JSON by default. Text returns the body in data. File keeps a download such as a CSV or ZIP export as binary data in the field you name |

The path must be relative, must start with a resource that exists in the Xentral API, and must not contain .., a full URL, a query string or an unfilled {placeholder}. Anything else is rejected before a request is sent.

Example, read POS journals, which have no dedicated operation.

Method        GET
API Version   V1
Path          posJournals
Query         {"page[number]": 1, "page[size]": 50}

Example, run a report query with a pasted V1 path and a report parameter.

Method        POST
Path          /api/v1/analytics/report/42/query
Body          {"parameters": [{"name": "date", "type": "string", "defaultValue": "2026-01-01"}]}

Deprecated endpoints migrated

Xentral deprecated several V1 endpoints this node used. They now point at the current versions.

Supplier Update still uses the deprecated V1 tag endpoint, because its only replacement is a Xentral beta endpoint.

To move an existing Product node to V2 reads, delete it and add it again. The new node uses node version 2.

Trigger events

Events marked Unverified are listed in the Xentral event catalogue but have not been observed firing on a live instance yet. The event list follows the Xentral AsyncAPI catalogue from 2026-10-26.

Credentials

The Xentral API credential needs two values.

Creating a token needs admin rights in Xentral. The Xentral authentication guide shows each step. The token stays in the n8n credential store and is only sent to your own Xentral instance.

Technical overview

Project structure

credentials/          Xentral API credential, icons, credential test
nodes/Xentral/
  Xentral.node.ts         action node and resource routing
  XentralTrigger.node.ts  webhook trigger with signature checks
  transport.ts            HTTP, pagination, retries, URL and ID validation
  resources//       operations, fields and handler per resource
  resources/specDriven/   operations generated from the Xentral specs
  resources/customApiCall/  Custom API Call and its path checks
scripts/copy-assets.mjs icon copy step for the build
scripts/gen-spec-catalog.mjs  regenerates the spec driven operations from specs/
specs/                Xentral OpenAPI specs the node is built against
test/                 node test runner suites
docs/assets/          images for this README

Build, test and lint

Requires Node.js 22 or newer.

npm ci
npm run build   # compile TypeScript and copy icons into dist/
npm test        # build, then run the unit tests
npm run lint    # n8n verification rule set, must report zero problems

Release flow

1. Bump version in package.json and add a CHANGELOG.md entry on a branch.
2. Open a pull request. CI builds, lints and tests it.
3. After merge, tag the merge commit with v and push the tag.
4. The Publish workflow checks that the tag matches package.json, runs the tests, packs the tarball and scans it with n8n’s community package scanner. Only a tarball that passes is published to npm with --provenance, which signs the package against that exact commit. The scan runs once more on the published version to check provenance.

Upgrade notes

1.4.5

Address overrides on documents leave Type out when it is empty. A set Type must be mrs, mr, company or other (any case). Any other value now stops the item with a clear error before the request, where Xentral used to reject it.
A line item update that sets only Price Currency now sends it. Before, it failed with “No fields provided” or the currency was dropped.
When the trigger cannot delete its webhook on deactivation (anything but 404 or 410), it keeps the webhook ID and signing key. The next activation adopts the webhook and the next deactivation retries the delete.
The trigger now remembers which Xentral instance it registered its webhook on, and only deletes it there. A webhook registered by an older version is read back first and deleted only when it still points at this node’s URL. A stored webhook from another instance is never adopted with the old signing key.
On activation the trigger first removes a webhook it kept from such a failed delete. If that removal fails too, activation stops with an error rather than registering a second webhook.
An empty Country in an address override is left out. A set Country must be a two-letter code (any case).
To clear a Delivery Date on an Invoice or Proforma Invoice update or a line item update, use an expression that returns null. An empty value is still ignored.
If you set your own Signature Key on the trigger, the credential must be allowed to list webhooks, or activation stops with an error. With an empty Signature Key nothing changes.
Custom API Call and the single-call operations built from the specs (for example Report Execute Query) have a Full Response option for responses that carry a cursor or meta next to the data. Xentral caps a report query at 5,000 rows, and meta.totalResults shows when that happened.
The trigger also stops activation when a webhook for the same URL and event that it does not own cannot be deleted.
Liability Status no longer lists Cancelled. Xentral has no such status and a saved Cancelled always failed. It still fails, with the same message, so pick Pending or Paid.
Product ID on a line item update and Product Number on a line item add or update are no longer sent, because Xentral V3 accepts neither and ignored them. To change a line item’s product, delete it and add a new one.
Sales Order and Return Get Many with the Sent filter now return documents marked as sent (isDocumentSent). Before, the filter asked for a status Xentral does not have.
On the first activation after upgrading, the trigger writes its stored signing key to the webhook it adopts, one extra request.
Add Line Item now sends a Price Currency that is set without a Price Amount.
Customer Create no longer needs Name for a person. Set Customer Type to Person with First Name and Last Name.
A Xentral host with percent-encoding or non-ASCII characters is now refused at run time too, matching the credential test.
An expression that returns null for a reference ID (for example Project ID) now removes the reference. Before, {"id": null} was sent and rejected.
An empty date value is now left out of every document and line item request instead of being sent as an empty string, which Xentral rejected.
The trigger ignores deliveries whose event type is not the one it is set to. Before, a webhook registered with extra events started the workflow for all of them.
To remove a price’s Valid From or Expires At, use an expression that returns null.
Product Update still ignores empty values. Turn on the new Clear Empty Fields option to clear text fields with an empty value, or the age rating with Age Rating None.
Return Create From Delivery Note now checks its line items before the request. Each needs the delivery note line item id, a quantity and a returnReason id, as Xentral requires.

Compatibility

Support

Bugs and feature requests go to GitHub issues.
Other questions, custom workflows or Xentral automation projects go to [email protected].
More about the maintainers is at next8n.com.

License

“Xentral” and the Xentral logo are trademarks of Xentral ERP Software GmbH. This project is independent and is not affiliated with or endorsed by Xentral ERP Software GmbH. It talks to Xentral only through the publicly documented REST API.