Xentral ERP

Xentral ERP

This connector works with one Xentral cloud instance through the current Xentral API (developer.xentral.com). Each endpoint carries its own version in the path, and the connector calls the newest stable one per resource: /api/v3/... for sales orders, delivery notes, invoices, credit notes and purchase orders, /api/v2/... for products and customers, /api/v1/... for stock, warehouses, suppliers, supplier invoices, payment methods and projects. The old Basic-auth API user is not used.

Setup (about 5 minutes, needs an admin)

1. In Xentral, click Administration at the bottom left, then Account settings (Kontoeinstellungen) → Developer settings (Developer Einstellungen) → Personal Access Tokens. A quicker way: type "Personal Access Token" into the Smart Search.
2. Click Create token (Token erzeugen). Give it a name such as AnythingMCP-Read, a description and a lifetime (default 180 days).
3. Grant Read on the areas the AI should see: products and stock, customers (CRM), sales documents (sales orders, delivery notes, invoices, credit notes), purchasing (purchase orders, suppliers, liabilities) and settings such as payment methods and projects. Add Create and Delete on sales orders only if the AI may prepare order drafts. Avoid the Admin scopes.
4. Click Create and copy the token right away: Xentral shows it only once.
5. Set XENTRAL_URL to the address you open Xentral at, e.g. https://acme.xentral.biz (or your own domain), with no /api, no path and no trailing slash, and XENTRAL_TOKEN to the token. The connector sends it as Authorization: Bearer <token>.

A token's permissions cannot be edited later: to change them, create a new token and replace XENTRAL_TOKEN. Tokens expire at the date you chose, and Xentral deletes tokens that were unused for 180 days.

Ids and numbers: every tool takes Xentral's internal id, not the printed number. Find the id with a list tool first (a filter on number, documentNumber or customerNumber, or search). A customer's id is also its address id: documents show it as address.id, and xentral_create_sales_order takes it as addressId.

Filters are lists of conditions that must all match, each with a field (key), an operator (op) and a value:

• [{"key": "paymentStatus", "op": "in", "value": ["pending", "partiallyPaid"]}] lists open invoices;
• [{"key": "documentDate", "op": "greaterThanOrEquals", "value": "2026-10-01"}, {"key": "status", "op": "equals", "value": "released"}] lists released documents since 1 October.

Operators: equals, notEquals, in and notIn (value is a list), contains, startsWith, endsWith, greaterThan, greaterThanOrEquals, lessThan, lessThanOrEquals, and on documents isNull and isNotNull (no value). Each tool lists the fields it accepts; Xentral answers any other field with a 400 validation error. Document dates are YYYY-MM-DD; updatedAt on products takes an ISO 8601 date-time with offset (2026-10-01T00:00:00+02:00). Customer filters only match exactly (no contains).

Document search and sorting (sales orders, delivery notes, invoices, credit notes, purchase orders): search is a free-text search over the number, customer or supplier name and number, email, ZIP and external order numbers. sort takes field names, a leading minus sorts descending (-documentDate). include embeds related data such as lineItems or address.

Statuses: sales orders are draft, released, completed or cancelled; invoices, delivery notes and purchase orders also have sent. paymentStatus on invoices and credit notes is pending, paid, partiallyPaid, cancelled, partiallyCancelled, badDebt or debited.

Stock: xentral_get_product_stock returns several figures. sellable is what can still be promised to a customer, physical what is on the shelves, reserved what open orders hold. Warehouses (Lager) contain storage locations (Lagerplaetze), and xentral_list_product_storage_locations shows where a product lies.

Pagination: document lists take page and perPage (up to 1000, default 25 here); pagination: table adds the total count. The other lists take page and pageSize (10 to 50).

Writing: xentral_create_sales_order only creates a draft: no order number, nothing reserved or shipped until someone releases it in Xentral. xentral_delete_sales_order_draft removes such a draft; it is installed switched off. Every other tool only reads.

Rate limit: about 100 requests per minute per instance, whatever the plan. Above that Xentral answers 429 with a Retry-After header. Prefer one filtered list call over many single lookups.

Common errors

• 401: the token is wrong, expired or deleted.
• 403: the token lacks the permission for that area. Create a new token with it.
• 400 "Generic request validation failed" or "filter must be an array": a filter field or operator the endpoint does not accept, or a malformed value. Use the fields listed in the tool.
• 404 "Route not found": XENTRAL_URL contains a path such as /api/v1, or the instance does not offer that endpoint yet.
• 409 when deleting a sales order: only drafts can be deleted.