How to integrate with Procountor: Two authorisation worlds, and one of them has a ceiling

The first thing to know about Procountor is not technical. You cannot start against it on the afternoon you decide to. Procountor issues credentials through a form, and the answer comes back by email and by text message after three to four days.

The form asks what your integration does, which objects it will move, in which direction and for which countries, plus the redirect address the flow will use. None of it is hard. All of it sits between you and your first call.

Production is a second application of the same kind, with its own wait, and the test account does not transfer into it. Our own engineer built against the interface while waiting for the first reply and could not run a single request until it arrived.

Procountor offers an authorisation code flow for applications with a user in front of them, and a client credentials flow for everything that runs on its own. The second uses an API key as its credential, and that key is bound to one user, one company and one client application at the same time.

So far this is ordinary. The sentence that decides your architecture is the next one, and Procountor publishes it plainly: an access token from the client credentials flow cannot reach any endpoint that requires two-factor authentication, because those endpoints need a user who is actively present.

Procountor gives the example itself, and it is the one that matters commercially. An integration may modify a purchase invoice on its own. The payment for that invoice has to be approved by a person holding Procountor Key, which is issued to a natural person and cannot be handed to a service.

The expensive part is that the boundary is not machine readable. Across 192 operations in the published specification, two-factor authentication is named exactly once. Which endpoints sit behind it is described in prose, so a team that plans for full automation usually discovers the line at runtime.

A Procountor user can belong to several companies, which on most systems means an identifier you resolve after authenticating and then carry in every request. Procountor settles it earlier. During login it shows a selection page of its own, and the connection that comes back is bound to the company the user chose.

That has a pleasant consequence and one constraint. The pleasant part is that there is nothing to discover afterwards and nothing to thread through your calls. The constraint is that one connection is one company, so a customer running three of them is three connections, each created by a person in a browser.

It also explains something you will notice if you read our documentation: Procountor is not on either of the two flow lists there, because it needs neither a company lookup nor a selection step of ours. The vendor already does it.

The authorisation code flow returns an access token valid for one hour and a refresh token valid for six months. The refresh token does not rotate, so the value you store on day one is the value you still hold in month five.

What matters is the list of things that end it early, because four of the five are actions by somebody who has never heard of your integration.

The last row is the one that catches teams out, and it is self-inflicted instead of a limit anyone reaches by growing. Requesting a fresh token on every connection attempt instead of reusing the stored one walks a tenant towards a hundred quietly.

In all five cases the consequence is the same, and it belongs in your design. The stored refresh token is invalid, and because Procountor keeps a person in the authorisation step, nothing can quietly renew it. Your customer authenticates once more. What that costs you is a path in your product for a connection that has gone cold, and a message that says so.

Procountor does not model a sales invoice, a purchase invoice and an order as separate things. It models one invoice object with a type on it, and the type takes seven values. A sales invoice, a purchase invoice, both kinds of order, a travel invoice, a bill of charges and a periodic tax return are the same shape with a different label.

The ledger receipt does the same on a larger scale, with sixteen values including salary, employer contributions and a bank statement used as a receipt. Getting the type wrong produces a valid document of the wrong kind.

Two smaller things belong in the same section because they reach the same schema. First, an id is unique inside one company and nowhere else, so two companies can hold invoices with identical ids. Procountor names the company and the resource id together as the pair that is unique across the system.

Second, updating an invoice requires an invoiceVersion, which is a timestamp carried as a string. You send back the value you received, unchanged, or the write is rejected. It is optimistic concurrency wearing a date.

Through the common data model none of that reaches your product: the seven document kinds arrive as the objects they actually are, and the identifier question is answered before you see the record.

This one is not in any documentation, and it is the reason this section exists. Asking Procountor for tax rates returns a response containing two arrays. One holds the percentages. The other holds the tax codes. Nothing in the response says which code belongs to which percentage.

Most accounting systems hand you a tax rate and its code as one object, and most data models are built that way, ours included. Against Procountor that model cannot be filled from a single response, so the pairing has to be established another way before any of it is usable.

The cost of this one does not show up in any estimate, because nothing announces it. You call an endpoint, you get a valid response, and only when you try to map it does the gap appear.

Connecting through the Procountor API with Maesn changes the shape but not the fact. Tax data arrives as one list instead of two, in the same form every other connected system uses, and each entry carries the rate or the code it came with. The relation is not published by Procountor, so nobody downstream invents one, and a use case that needs the pairing establishes it deliberately.

Procountor publishes webhooks, and the list is short. Three event types exist: a payment was updated, a payment was deleted, a user was updated. Subscriptions are authenticated with HMAC over SHA512, and one webhook is allowed per event type.

For an accounting integration that reads accounts, contacts and tax rates, none of those three helps. Change detection is a read you schedule, and the interval is yours to choose.

Paging is thinner than the documentation suggests at first glance. Counted across the specification, 22 of 101 read operations carry paging parameters at all, in four different combinations, and the rest have none. Where paging exists there are two mechanisms, a cursor and a page number with a size that often defaults to fifty.

Our engineer added the practical half of that: some list endpoints return no total count, which he found on accounts. You can page through them, and you cannot tell in advance how far you have to go.

The production request limit is 60 a second per client, and Procountor writes that exceeding it may result in suspending the service for that client. That is a firmer consequence than the usual rejected call, so it belongs in the design of the schedule instead of in the error handling.

Reading on a schedule across a catalogue of systems that each page differently is exactly the work that one way to filter and page removes. The loop you write once is the loop you point at the next system.

Everything above is real work, and most of it is the same work for every customer you connect. That is the part to do once.

The role question in that column is genuinely yours. Procountor sorts contacts into companies and people, and neither carries a field saying which side of an invoice they are on. A matching rule written against a system with separate customer and supplier objects needs adjusting here.

And the objects available today are a smaller set than the system as a whole. Accounts, contacts and tax rates have been readable since July, with posting for booking proposals and expenses added in August. The rest of Procountor, including a payroll surface larger than most of its accounting one, is not part of the connection today.