How to integrate with Abacus: Three values you cannot hardcode

Abacus is a Swiss ERP for small and mid-sized businesses, covering financials, payroll and project management, and it reaches the parts of the market that never moved to a browser-only product: fiduciaries, construction firms, manufacturers. If you sell software to Swiss companies, it turns up early in the integration backlog.

It is also a system where the question where does it run has no single answer. Abacus is installed, either on the customer’s own server or on one belonging to a hosting provider, and that is not a deployment detail. It is the reason the next four sections exist.

Everything a platform normally settles for you is settled per customer here. Which endpoints exist, how many requests you may send, what you can subscribe to, even where the logs end up.

If you would rather have those differences absorbed than handled, the Abacus API page is the object by object view of what a connection through us carries. The rest of this guide is the consequences themselves, in the order you meet them.

Start with the smallest thing that usually goes without saying. To call an endpoint you need a host, and for Abacus there is no host to hardcode. Each installation answers on its own address, and where a provider hosts several customers it can differ per Mandant as well.

So the base URL becomes an onboarding field. It travels as a query parameter on the authentication call and is stored against that customer, which keeps it out of your configuration once you have more than one of them.

The Mandant is the second value of the same kind. Abacus calls it the Mandant on both routes; environmentName is our own name for that layer, and it is what the REST route asks for and what the environments endpoint returns. On AbaConnect the vendor’s word stays and the value is fixed at login.

One consequence lands outside your code. Because Abacus runs on the customer’s machine, so do its logs. Turning on request logging means editing a properties file in the installation and setting a level such as ch.abacus.eapi.level = FINER, after which the entries appear in that server’s log folder. Support conversations here start with somebody else opening a file.

Abacus ships a major release annually, and the interface ships with it. The developer portal does not publish one endpoint overview, it publishes one per version, with its own changelog beside it. A customer on 2024 and a customer on 2026 are running the same product and offering you two different catalogues.

The gap is visible even in a list nobody would expect it in. Abacus 2026 exposes an Absences entity set; the 2024 catalogue starts one entry later in the alphabet, because that entity does not exist there. Multiply that by a few hundred rows and you have the reason a feature can be ready for one customer and impossible for another.

The version even reaches the parts of the setup you would call boilerplate. The login redirect you register for a service user carries it in the path, so the callback is version-specific rather than tenant-specific, and adding support for a new release is a configuration step rather than a code change.

This is the point where a normalised model stops being a convenience. When two customers answer differently to the same question, something has to decide what your product sees, and doing that once is what the common data model is for.

The REST route uses OAuth, with the authorization code and client credentials grants, both returning a JWT. What it does not use is an ordinary user. Abacus wants a service user, created in the integration wizard, and the definition is strict: “The specified Service-User can only access Abacus via the available interfaces (access to the Abacus UI is not possible).”

Two details around that will cost you a day each if you meet them in production instead of reading them here. The first is a deadline: “Please note that the integration has to be approved within 10 days otherwise it will be deactivated.” An integration your customer creates and then leaves for a fortnight is gone.

The second is an error code that does not mean what it says. A token request without the form content type comes back as 404, naming the token path, rather than the 400 or 415 you would reach for first. Abacus documents the exact body, so the misleading part is documented too.

Abacus publishes its limits, which is not universal: our own rate limiting reference records four systems that enforce a ceiling without publishing the value. Abacus names three windows and applies them at the same time, a minute, an hour and a day. Exceed any of them and you get a 429 with a small JSON body naming the servlet and the url that was refused.

The number, though, is a property of the version rather than of the product. That is the third time the same sentence turns up in this guide, and here it lands in your scheduler: a sync sized for a customer on 2026 will spend the afternoon backing off at a customer on 2025.

Three documented ways to spend less exist, and the third changes the arithmetic. A $expand pulls related entities in the same request, a deep insert writes them in one, and a batch request counts as a single request against the limit however many operations it carries.

Read against that budget, one more number matters: a response returns at most 100 records, and you walk further with the @nextlink the response carries. A first sync of twenty thousand contacts is therefore two hundred calls before anything else you wanted to do that minute. Paging behaves differently on nearly every system, which is why unified pagination and filtering exists as its own layer.

Abacus sends you nothing. There are no webhooks and no callbacks, and our own coverage data records no native event for any object. What it offers instead is easy to misread as push, because it is called a subscription: you register a topic, and Abacus records what changed until you come and collect it.

The loop is three calls. SubscribeChanges registers a topic under a name you choose, ConsumeChanges returns everything not yet acknowledged, and AcknowledgeChanges clears the batch with the key that came back. The mandant sits in the path of all three, so a customer with three Mandants runs the loop three times.

Three rules turn that from a convenience into a job with a deadline. Consume at least once a day. Acknowledge at least once a day when there is anything to acknowledge. And “subscriptions that are not used to consume messages for more than 3 days will be automatically removed”, which means a weekend outage can end with the subscription gone rather than a backlog waiting.

What arrives is a list of identifiers rather than records, so a read follows each message. And one sentence in the reference changes how you use the timestamp: “Only 1 message per changed data record is registered. If multiple changes have been made to a data record on the Abacus Server, the ‘CreatedOn’ timestamp references the time of the first change.”

It is when the record was first noticed, not when it last moved, and a watermark built on it will sit earlier than the truth.

Acknowledgement is all or nothing as well: one key clears the whole batch. Fail halfway through processing and your choice is to acknowledge work you did not finish or to consume it all again.

AbaConnect is the route you need when a customer runs a module whose objects the REST endpoints do not carry. It logs in with a username, a password and a Mandant, and returns a login token. From there it behaves in a way that is worth reading before you design around it.

Every data request comes back with an IsFinished flag, and that is not the same as every request making you wait: many return it true on the first call, while others need one or more polling loops with the RequestID you were given, 100 to 250 milliseconds apart. Writes are the ones that usually wait and reads sometimes do, and which of the two it will be is not something you can tell before you send it. While the flag is false that request is pending, and “a pending request will block other requests in the same user session, until the RequestID is cleared”.

Two more properties compound it. A user gets one session, and “multiple User Sessions for the same User are not possible”. And a session holds one Mandant: switching means logging out and logging in again. Serial requests, one client, one Mandant at a time.

That is also the real reason behind the advice to create a dedicated integration user. It is not tidiness. A person logging into the Abacus menu with the same account can terminate the web service session, after which your calls fail with an invalid session, and since Abacus V2018 the usernames permitted to log in this way have to be listed in a server configuration file anyway.

Sessions themselves are not on a fixed clock. The default is that a session lives until logout, with the server closing one that has been inactive for a while, in the documentation’s own words “e.g. 15 – 20 minutes”. Two useful small operations sit beside all of this: Ping tests reachability without logging in, and IsAlive tests whether a session is still there. Through Maesn neither is your job: where a session has been closed, the next call logs in again before it runs.

One line from the same family belongs in a security review rather than a build plan. The connection runs over http or https depending on the URL you were handed, so transport encryption here is a property of how that server was set up.

Through Maesn the shape stays but the bookkeeping moves. Asynchronous work returns a taskId, and GET /asyncTask/{taskId} reports progress and hands over the result when it is ready.

Our own list of asynchronous endpoints includes GET as well as POST on contacts, projects and journal entries, which is what a read-side wait looks like from the outside, and the same queue sequences requests per tenant. What that buys beyond neatness is on the asynchronous processing page.

Two interfaces, one of them SOAP, one catalogue per year and a change feed with a deadline. What we take off the list:

• The three values become one onboarding step. The base URL arrives as a parameter during authentication and is stored per tenant, the Mandant travels with the call, and neither ends up in your configuration.
• Both routes arrive in one shape. Whether a customer is served over the REST endpoints or over AbaConnect, a contact reaches you as a contact. The SOAP envelope stays on our side and so does the IsFinished bookkeeping, including the part where a request turns out not to need any: what reaches you is a task id when there is something to wait for.
• Asynchronous work has one interface. A task id and a status endpoint, the same for the systems that queue and the ones that answer immediately.
• Sandboxes exist even where the vendor has no free trial. Abacus and Ababau are two of the systems where a trial cannot simply be registered, and we provide the environment.

What stays with you, and two of these are decisions rather than tasks:

• The polling interval. We do not turn Abacus into an event source, because it is not one. The subscription topics cover master data, everything else is a read on a rhythm you choose, and how fresh your product has to be is a product question.
• Which version your customers are on. It decides what exists, and it is worth asking during sales rather than discovering during implementation.
• The setup inside the installation. The application installed with its AbaConnect option enabled, a service user with an approved integration, and a Mandant enabled for the interface. Abacus notes pricing implications for the number of clients enabled, and the detailed conditions live in a knowledge base article open only to its sales partners.