How to integrate with Xentral: Every endpoint has its own version, and the version sets the query

One personal access token reaches all of Xentral, and Xentral means that literally: the current interface, the older REST one and the older Standard one all accept the same credential. That is convenient on the first day and it is the reason the version question never fully goes away.

The vendor recommends the current generation and says why: “the older REST and Standard APIs can’t handle all endpoints when using personal access tokens.” It then lists thirteen paths that a token cannot reach in the legacy interfaces, twelve under /shopimport/ plus /v1/reports, and closes the list with “This list makes no claim to completeness.”

Versioning itself is in the path, as /api/v1/…, /api/v2/… and /api/v3/…. The sentence that decides how you plan is the one about scope: “not our complete API has a version, instead each individual endpoint has its version. We will introduce new versions of endpoints but not of the complete API.”

So there is no single number to pin your integration to. There is a version per endpoint, and a fourth shape besides: the versionless /api/… form still answers, and Xentral marks it as deprecated and due for removal. Which objects a connection reaches through us, cell by cell, is on the Xentral API page.

Two rules about change complete the picture, and they pull in opposite directions. Releasing a new version of an endpoint means “the previous version automatically gets deprecated”, so the version you are on ages by someone else releasing the next one. And inside a version, “Adding items to a payload is not considered a breaking change”, so a stable version can still grow fields under you.

Neither of those is unusual on its own. Together with a per-endpoint version they mean a Xentral client is never simply on v2 or v3, it is on a set of versions that move individually.

Here is where a per-endpoint version stops being a footnote. Xentral documents its query language twice, on two pages, one for the first two generations and one for the third. Those are not two descriptions of one thing. The page parameter, the sort syntax, the operator set and the date format are different on each.

The filter shape survives the jump, which is what makes the rest easy to miss: both dialects take filter[n][key], filter[n][op] and filter[n][value], and both AND-combine the entries. Everything around that changed.

The operator sets are the part that changes behaviour rather than syntax. The newer dialect adds contains and notContains for strings and isNull and isNotNull for any field, and it accepts nested keys in dot notation, so totals.gross.amount and dunningSettings.blocked are filterable. On the older dialect neither the null checks nor the nested paths are documented at all.

None of this is hard to write once. It is hard to keep correct across a set of endpoints that version individually, because the dialect a call needs is a property of the endpoint rather than of your client. Through Maesn the query surface is one shape for every system, which is what unified pagination and filtering describes, and the two Xentral dialects sit behind it.

The newer generation offers three paging models, and the choice between them travels in a request header instead of a query parameter. That placement is the reason it matters: a header is the thing a client forgets to send.

X-Pagination takes simple, table or cursor. Xentral is explicit about what happens when it is absent:simple applies. And simple is the mode that returns no total, deliberately, because it skips the COUNT(*) query that would produce one.

Read that against how a first version of a sync usually gets written. You ask for page one, read a total, divide by your page size and loop that many times. Against the default mode there is no total to divide, so the loop either runs once or runs on a value that was never there.

The fix is a decision rather than a workaround, and there are two reasonable ones. Send X-Pagination: table when a person is going to look at a count, and accept the extra query it costs. Or keep the default and stop when a page comes back short, which is the loop that works in all three modes.

For a first backfill the third mode is the one Xentral points at. Cursor paging avoids offset queries, which is why the vendor’s own comparison rates its performance highest, and it gives that up in exchange for direction: navigation is next and previous only, with no jumping to an arbitrary page. That is a good trade for an export and a bad one for a table a user clicks through.

One detail belongs next to the paging and is easy to read past. Every response, in every mode, arrives inside the same envelope of meta, data, extra and links, where data is an array for a collection and extra is where Xentral puts pagination and totals. A client that reads the body as the record rather than as the envelope gets one level too high.

Xentral tells you how finished an endpoint is, and it tells you in the one place a client sets and forgets. Media types are built as application/vnd.xentral.VARIANT.vVERSION+DATAFORMAT, and the version segment carries a suffix when the endpoint is not stable yet.

The third row is the one to sit with. An alpha endpoint is released, it authenticates and it answers. What comes back is not your customer’s data, and Xentral puts that plainly: “this endpoint has been released, but the data you get is dummy data, meaning you can start working on building your integration, but we are still working on these endpoints.”

Nothing about the status code separates that from a working read. A test that asserts a 200 and a non-empty body passes against an alpha endpoint, and it passes for as long as the endpoint stays there.

The same header is also how one endpoint offers several shapes of the same record. A product read is documented with a default representation, a minimal one and a CSV variant, all on the same path, selected by Accept. Asking for a combination Xentral does not publish is not a fallback either, it is a 406.

So this system answers with at least two error classes that a client will meet before it meets a real bug: a 406 when the media type is wrong and a 429 when the request budget is spent, at 100 requests a minute regardless of plan. Reducing that kind of variation to one shape is what unified error handling is for.

Beta carries a second marker as well, and it is the one you see without reading a media type. A large number of endpoint descriptions in the reference open with their own warning that the endpoint is in beta and that “breaking changes can occur at any time without prior notice”.

So the maturity label and the endpoint description are two separate places to look, and both are read per endpoint like everything else on this system.

Two things are true about events on this system at the same time, and a description that carries only one of them is wrong in one direction or the other.

Xentral publishes an event catalogue, and it is a large one. Counting the operations on its webhook reference gives 152 distinct types across 44 domains, from salesOrder.created to invoice.released to datev.exported.

Delivery is an HTTP POST to a destination URL of at most 255 characters and the payload arrives as {"type": "com.xentral.EVENTTYPE.vX", "body": {…}}. The whole feature sits behind a flag: “The webhooks feature is currently in testing and available behind a feature flag”, with access arranged by email rather than switched on in the interface.

Through Maesn, no Xentral object has an event enabled today. That is the second true thing, and it is a statement about what is switched on rather than about what the platform can do.

The measurement that decides your design is neither of those two numbers, though. It is which domains the catalogue contains. Searching it for the party layer returns nothing: there is no customer domain, no supplier domain and no contact or address domain. The nearest match is dropshippingSupplier.orderCreated, which is an order rather than a supplier record.

Put that next to what is readable. Of the four objects a connection reads today, exactly one has an event family in Xentral’s catalogue, and it is invoice with eight types. Customers, the single object you can create here, has none at all.

One more property of the catalogue matters if you ever do consume it directly. Six of the 152 types accept two different payload shapes under the same type string: created and updated on salesOrder, product and invoice. One shape is a slim notification, two or three fields and no more allowed. The other is a full document, and Xentral names it in the spec as the fat event.

So a consumer keyed on the type alone is keyed on something that does not determine the body. Where a system does send events the subscription and delivery side is its own topic, and unified webhooks covers it.

What runs here instead is a read on a timestamp, and the shape of it is documented rather than improvised. You store when you last fetched, pass it back as lastModifiedAt, and get only what changed since.

There is no handshake on this system. An administrator inside your customer’s instance opens Account settings, then Developer settings, then Personal Access Tokens, names the token in at most 50 characters and copies the value. That copy is the only moment the value is visible: “After you close the window you won’t be able to see the token again.”

What that token then is, in Xentral’s own words: “Personal access tokens enable API-based access to Xentral with unlimited permissions and without expiration date.” No scope and no expiry. What follows in the reference is advice rather than a control: “it is good practice not to share tokens publicly and not to hardcode them into external applications.”

The consequence that gets underestimated is not the breadth of the permission, it is the absence of a deadline. A token that expires forces someone to touch it, and that moment is where a team notices where the value has ended up. Nothing on Xentral ever becomes due, so the noticing has to be scheduled by you or it does not happen.

Xentral also permits the shape that makes this worse, explicitly: “With personal access tokens you can use the API with multiple applications at the same time.” One value in four products is allowed, and it is how one value ends up in four products. The way back is a single door and it is one-way: “You can’t restore a deleted token.”

So the practice this system rewards is one token per consumer, named after that consumer, because revocation is all-or-nothing per token and the name in the list is the only thing that tells you which one you are about to switch off.

The second value at connection time is the instance. A Xentral customer answers on their own host in front of xentral.biz, so apiKey and tenantId are both required, and the id can be prefilled into the page your customer sees when you already know it.

Xentral is also on the headless list, so the pair can be posted straight to an endpoint that returns the account key. For a credential that never expires, keeping that exchange inside your own interface is usually the version a security review prefers.

The write side of this connection is one object today, and the limit is ours rather than Xentral’s. Customers is switched on for creating, and no object is switched on for updating or deleting yet. So through Maesn you can add a customer and not change it afterwards, which is worth designing around now and worth asking about before you assume it is permanent: where the vendor exposes the operation, switching it on is a request rather than a rebuild.

On the read side four objects answer today, and which four is itself informative. Xentral sells order management, stock and multichannel commerce, and what is switched on is the receivables end: customers, invoices, invoice lines and suppliers.

Purchase orders, goods receipts, journals and journal entries are not enabled, while sales orders and items are available on request. A finance use case and a logistics one therefore start from different conversations.

Fifty-five object and operation combinations sit on request across the matrix, which is a different state from absent. Invoices, for one, are readable now and their writing is in that group rather than ruled out. Objects that do arrive come through the common data model, so a Xentral invoice reads like every other invoice you already handle.

None of the above is a rank. Several systems in the catalogue have no updatable object, and it is a property of this connection rather than a place in a table.

Three facts meet in that quote and they are all Xentral’s. The token has no permission scope, granular control is a plan rather than a feature, and some records cannot be removed once written. A test that goes wrong against a live instance is therefore not always reversible.

There is also no free Xentral trial to register for, which turns this from an inconvenience into a scheduling problem: the token only exists inside a real instance, and creating it needs an administrator.

Building the first version of an integration therefore means asking a customer for admin access to their live system before you have anything to show them. That is the gap a sandbox closes, and Maesn provides one for every supported system including those without a trial.

Most of what makes this system expensive to build against is absorbable, because most of it is variation rather than limitation. Five things stop being yours:

• The dialect. Which paging parameters, which sort syntax, which operator set and which date format an endpoint wants is resolved behind one interface, so a per-endpoint version is not a per-endpoint branch in your client.
• The maturity check. You do not pick a media type, so you do not pick an alpha endpoint by accident and read dummy data at 200.
• The instance. The id is collected with the key and turned into the host on every request, so no call site of yours builds a customer-specific URL.
• Custody of the key. It is held against the connection rather than copied into each product that needs it, which leaves one place to revoke from.
• The error shapes. A 406 from a media type and a 429 from the request budget arrive in the same form as every other system’s.

Three things do not move, and two of them are decisions rather than work:

• How often you look. Change detection here is a scheduled read, so the interval, how far back each pass reaches and how much re-reading you accept stay yours. The ceiling behind that choice is 100 requests a minute, and Xentral marks the figure as still being evaluated.
• Which objects you need switched on. The on-request group is large and it is a conversation rather than a roadmap. Having the list before your design is fixed is cheaper than after.
• Whether your product corrects records in place. Nothing is updatable here today. Accounting practice expects corrections as new documents anyway, so check that against your own use case early rather than designing a write path around it.

And one thing sits with your customer rather than with either of us: the administrator right that makes the token screen reachable at all. That is a sentence in your onboarding instructions, and it is better written before somebody reports that the connection cannot be created.