How to integrate with Visma eAccounting: Three brand names, sixty-minute tokens and fifty-record pages

The first question on this system is a naming one rather than a technical one: which product are you actually looking at. The same software is sold under a different name in each of its markets, and the documentation is in the middle of changing which name it uses.

Maesn’s integration documentation answers it in one line, directly under the target system identifier: “Note that the system is known under the brand name eAccounting in the Netherlands and Norway and as Spiris (used to be called SPCS) in Sweden.”

The vendor has gone further than that. Its developer documentation is now titled Spiris/eAccounting, the client id you receive is described as “provided to you upon registration for the Spiris Partner Programme”, the product is written as Bookkeeping & Invoicing/eAccounting throughout, and Swedish partners are answered at an address on the Spiris domain.

What has not moved is everything you type. The scopes are ea:api, ea:sales, ea:accounting and ea:purchase, the host is eaccountingapi.vismaonline.com, the paths are /v2/…, and the target system through Maesn is vismaeaccounting. A rename above the interface and a stable one below it is the useful way to hold this system in your head.

Which objects that connection can reach today, and which sit on request, is listed object by object on the Visma eAccounting API page. It is narrower than the market coverage suggests.

Three markets on one interface is the commercial argument for this system, and it holds. What it does not tell you is that the markets are run separately underneath, and that shows up the first time you need a partner contact.

The vendor’s own support structure reflects the split, and it is the clearest signal of how separate these markets are underneath one interface:

Three separate contacts on two domains for one interface. Read that as a planning input rather than as a verdict: it tells you which door to knock on per market, and that the door is not the same one.

The wider pattern belongs to the group rather than to the product. Visma acquires software and keeps it running under its own name, which is why one vendor logo across a pitch deck can still mean four unrelated integrations underneath.

Authentication is OAuth 2.0 with the authorisation code flow, which makes it the familiar half of this system. The unfamiliar half is that the scope list is decided twice, and the second time is in every authorisation request you send.

Two scopes are mandatory. ea:api grants access to the interface at all, and offline_access is what makes a refresh token come back. Everything else is per resource area, each with a read-only variant, which means the boundary of what your integration can ever reach is drawn before your first customer sees a consent screen.

Both ea:accounting and ea:purchase have _readonly variants as well, on the same pattern as sales. And one scope belongs to a different product: vls:api reaches Visma’s payroll interface, which shares the identity server, so one token can serve both as long as the scopes were authorised.

Two request parameters are recommended by the vendor in unusually strong terms, and both exist to stop the flow from connecting the wrong company:

• prompt=select_account forces the company selection instead of reusing the one already chosen in Visma Online. The documentation calls it “highly recommended” and says omitting it “may result in automatic or unpredictable logins with an already selected company”.
• acr_values filters the selector down to companies that actually have access to this product, which keeps a customer from picking an unrelated Visma subscription.

The practical consequence of declaring scopes up front is a product question rather than an engineering one. Widening them later means going back to every connected customer for a fresh approval, so what your product might need in a year belongs in the conversation before the first customer connects.

Through Maesn the scope set is submitted once with the credentials and applied to every authorisation request, which is the same shape unified authentication gives every other system.

Three numbers describe the whole token lifecycle here, and the third one is the reason integrations on this system stop working without anybody deploying anything.

The access token expires 60 minutes after it is issued, which the token response states as expires_in: 3600. Refreshing is the same call with grant_type=refresh_token, and the response has the identical shape, so a refresh returns a new refresh token alongside the new access token.

The refresh token itself is valid for two years from issue. Then comes the exception, in the vendor’s words: “The refresh token remains valid for two years from the date it is issued. However, please be aware that if the user changes their password, the refresh token will become invalid.”

Two things follow, and the second is where the cost sits. A password change is an ordinary event in a small business, so this is a normal state rather than an edge case. And the documentation describes no notification for it, so the first signal your code receives is a 401 on the next call, at whatever hour your scheduler happens to run.

That makes re-authorisation a product surface rather than an error handler. Something in your interface has to be able to say this connection needs reconnecting to the right customer, which is exactly the state one error model exists to surface consistently instead of once per vendor.

There is also a revocation endpoint, which is the polite way to end a connection from your side: POST /connect/revocation with the token and an optional token_type_hint, authenticated the same way as the token exchange. A successful call returns 200 with an empty body.

Collection endpoints return 50 objects per page unless you ask for more, and the maximum is 1.000. You raise it with $pagesize and move through pages with $page, or you follow the Link response header, which carries the next page and the last page.

The part that decides whether a sync is correct is the envelope. A paginated response is not a bare array: it is a Meta object and a Data array, and Meta reports how much there is in total.

Filtering is the other half of a scheduled read, and it is oData v4 with a $filter parameter rather than a bespoke syntax. The operators are the ordinary set, strings are matched case insensitively and have to be quoted, and dates take a fixed format.

For a delta sync the field that matters is ChangedUtc, and the vendor documents it as the example of a datetime filter, which makes it the natural pair to the paging above: ask what moved, then walk the pages until CurrentPage reaches TotalNumberOfPages.

Through Maesn both halves arrive in the shape every other connected system uses, which is what one way to filter and page means in practice: the same query against a system that pages by cursor, by page number or by fifty records at a time.

The rate limit is one number with an unusual unit: 600 requests per minute, and “limit is registered per client and endpoint/URL”.

Per endpoint changes how a backfill behaves. A worker reading customers, suppliers and articles does not share one budget across the three, so parallelising across resources buys throughput that parallelising within one resource does not. It also means a single hot endpoint can be throttled while the rest of your integration is unaffected, which is harder to spot in a log than a global limit.

Exceeding it returns 429 with a body that names the window and the wait in plain language, which is more than most systems offer:

It is worth comparing this to the other Visma product in the catalogue, because the two meter on axes that have nothing in common. The Visma e-conomic API runs a token bucket per customer agreement in which different endpoints cost different amounts, so its budget depends on which calls you make. This one counts calls flatly, and splits the count per endpoint.

One vendor, two products, two models and no shared vocabulary between them. That is the normal case in this group rather than an accident of two acquisitions, and it is the reason a pacing strategy is worth writing once at a layer above.

Testing this system has two properties that are easy to miss and expensive to discover late. The first is that the sandbox is not a separate address.

In the vendor’s words: “It’s the same URL’s as production but with a IdentityServer client and Visma Online account that has a specific Sandbox type.” Nothing in a base URL or a hostname tells you which environment you are talking to. Only the credential does.

The two directions are not symmetric either: a production client id can reach a sandbox company, while a sandbox client id can never reach a production one.

The second is scale. A sandbox company is tied to one region at creation, the region cannot be changed afterwards, and “you can have a maximum of 1 company per email address”. Testing a second market therefore means registering a second account under a different email address. The vendor notes it is working on lifting that, which makes it a current limitation rather than a design.

That last row deserves a sentence, because the vendor is candid about the consequence: since some internal integrations are mocked, “you might encounter some weird errors if you try to access these services”. A failure in the sandbox is therefore not automatically a failure in your code.

Two steps in this flow are also not self-service, and both belong in a plan rather than in a launch week. Going live requires contacting Visma’s API support for production access. And the callback URL is set by the vendor rather than by you: Maesn’s documentation says plainly that “you have to contact Visma to change the URL to the correct one”.

What Maesn changes here is the sandbox itself rather than the paperwork. Our sandbox overview lists this system as having a free trial and as being provided by Maesn, so a test environment is available without registering four Visma accounts of your own. The four regions still exist; they just stop being four registration projects.

Everything above describes what the system does. This is the split: the parts that stop at this layer, and the decisions that stay yours because only you know your product.

What Maesn takes off the list:

• The scope declaration and the two parameters. Submitted once with your credentials and applied to every authorisation request.
• The refresh, per tenant. Tokens are refreshed on this side, so the lifecycle is not something your product schedules or stores per customer.
• Paging every collection. The envelope is read for you, so what arrives is the complete set rather than the first fifty.
• Three brand names reduced to one connection. Whichever name the customer uses, your code addresses one target system, mapped into one shared data model with every other system.

What stays with you:

• The scope decision. What your product might need in a year is cheaper to request now than after every customer has consented.
• The polling interval. How fresh your product needs to be is your choice, and you have 600 requests a minute per endpoint to spend on it.
• Which objects you need enabled. Name them from your use case, and have that conversation before a customer commitment instead of after one.