How to integrate with Weclapp: The rate limit is a queue

Weclapp is a cloud ERP for small and mid-sized companies in the DACH region, and it covers more ground than an accounting package: CRM, inventory, projects and invoicing in one system. That breadth is why an integration against it rarely stops at invoices, and why the same customer record turns up in a sales flow and in a bookkeeping flow.

Connecting is short, and it is not OAuth. Weclapp appears in the headless list in our authentication documentation, so there is no redirect and no consent screen: an administrator generates a personal access token in their own settings and hands it over with the tenant id. The full object matrix and the connection fields sit on the Weclapp API page.

The tenant id is not a field Weclapp hands back to you. It is the subdomain the customer already browses: every call goes to <TENANT>.weclapp.com, under the path /webapp/api/v2/.

What you can do is spare them the retyping. Our authentication documentation names Weclapp and xentral as the two systems where you can pass tenantId as a query parameter to autopopulate that field on the submission page, so a value your customer has already given you is not asked for a second time. Both credentials are still required: the API token and the tenant id.

A rate limit is normally a number you can divide your workload by: calls per second, credits per request, a bucket with a refill rate. Weclapp opens its load management section by declining to give you one. Its words: “The weclapp API has no fixed rate limits, and we want to keep it that way.”

What follows is not an absence of control, it is a different one. Weclapp limits the number of requests running at the same time per tenant, and separately watches sustained load. Go over either and your call is not refused, it is held: “the requests will just take a little bit longer”. That waiting room has a documented depth of 30 seconds, and only after that does the answer become HTTP 429.

The second mechanism changes what you are budgeting. Weclapp measures effective request time, not request count, and its own worked example makes the unit explicit: 500 requests at 100 ms each, even run in parallel, come to 50 request-seconds of load and are described as no problem. A handful of expensive queries can therefore cost more than several hundred cheap ones.

Because the pressure arrives as latency, the platform tells you about it in headers rather than in an error. Two ride on the response when a request had to wait, and both are absent when it did not, which makes their presence the signal.

All four are Weclapp’s own, and they travel on the leg between Weclapp and whoever calls it. Two of them you set on the way out to ask for a shorter wait, and the two from the visual above come back on the way in to report one. Through Maesn that leg is ours, so the table below is what the queue looks like from the inside rather than a set of headers you attach.

The queue is Weclapp’s, not ours, and a 429 that survives it reaches you. What we do with it is make it the same shape as every other system’s through unified error handling, so a wait that ends in a refusal is one error type in your code rather than a Weclapp-shaped exception.

Weclapp’s advice for staying out of the queue is specific, and one line of it is a prohibition: “No unfiltered polling”, alongside “Prefer fewer, larger requests”. So filtering is not an optimisation on this system, it is the mechanism that keeps your integration inside a budget nobody published.

The filter syntax itself is generous. A parameter is a property name and an operator joined by a minus, there are thirteen operators from eq through ilike to in, several parameters combine with AND, and an or- prefix or an or<group>- prefix builds the boolean shapes underneath.

Then comes the sentence to build defensively around: “Filtering query parameters for unknown properties or properties that don’t support filtering are silently ignored.” No error, no warning, no field in the response. The filter simply is not there, and what comes back is the collection.

One paragraph earlier in the same reference, sorting takes the opposite line: “If an unsupported or unknown property is specified then an error response is returned.” Same API, same class of typo, two different fates. Only one of the two parameters tells you that the field name was wrong.

Dates make the same mistake easy to walk into twice, because the query layer accepts two formats depending on which door you use. The simple filter parameters take milliseconds since the epoch. The newer filter expressions take ISO 8601, and they carry Weclapp’s own label: “This is still a beta feature.”

Five Weclapp resources are switched on here today: CUSTOMER, SUPPLIER, INVOICE, CREDIT_NOTE and SALES_ORDER, each of them able to report CREATED, UPDATED and DELETED. Weclapp publishes more than that, and the rest of the matrix is available on request rather than closed.

That carries more weight here than it would on a system with a published call budget, because subscribing is Weclapp’s own answer to the queue in the previous section: “Ideally: Event-driven architecture using webhooks.”

The arithmetic of switching that on is the part worth planning for. A subscription names one resource and one event type, and it is created per customer. Five resources times three types is fifteen subscriptions for one connection that wants everything, and fifteen deletions when that customer leaves.

Naming a resource and an event type is not a Weclapp peculiarity, it is what a subscription is on our side as well. What differs between systems is the level it attaches to: Exact Online subscribes to a resource on its own, and on QuickBooks and Xero the choice is made once inside your own app registration. On Weclapp it attaches to the customer, which is why the count above is per connection rather than per product.

Two properties of the payload shape what you can do with it. The first is shared with Lexware Office and stated in both sets of docs: filterDate and userId arrive as null, so an event tells you neither when the change happened nor who made it.

The second is easier to build against: notifications arrive as a single object, because the array form is documented only for Business Central, QuickBooks and Xero.

Weclapp’s JSON has three conventions that will not match your deserialiser’s defaults, and all three are deliberate rather than accidental.

• Decimals are strings. Prices and quantities are “serialized as JSON strings and not as JSON numbers to prevent accidental loss of precision”, always with a dot as the decimal mark. Parse them as decimals, not as floats, and the reason Weclapp gives is the reason to keep them that way.
• Timestamps are integers. Dates and times are “milliseconds since 1970-01-01T00:00:00Z”, which is also why the simple filter parameters in the previous section want epoch values.
• There is no empty string. Weclapp states that empty or whitespace-only strings “are always interpreted as null”, so you cannot clear a text field by sending one. Nulls are also omitted from responses unless you ask for them with serializeNulls.

Normalising exactly this, so that an amount is a decimal and a date is a date whichever system produced it, is the job of the common data model. It is also the reason the three conventions above are worth reading once and then forgetting.

The matrix is small and unusually consistent: every object that sends an event can also be read, so there is no case here of a notification you cannot follow up on. The interesting rows are the last two.

Bills and payments are readable and their events are the two on request, which is worth asking about early rather than late: those are the purchase side and the money side, and they are usually what a reconciliation or a payables flow is built on. If they matter to your product, ask for the event at the same time as the read.

Deletion is unavailable on every object here, so removing records stays a job in the source system. Accounting practice expects corrections as new documents anyway, which is why this rarely turns out to be the constraint it first looks like.

One structural note for anyone matching our object names against Weclapp’s own endpoints. Version 2 removed /contact, /customer, /lead and /supplier and consolidated them into /party, with a type field telling the kinds apart. Read the endpoint names above as Weclapp’s current shape rather than as our field list, and expect the two vocabularies to differ.

Testing all of this does not need a special environment. Weclapp offers a free trial account, and our sandboxes page lists a Maesn-provided sandbox for it as well. What does not exist is a separate sandbox base URL, so you switch accounts rather than endpoints.

Weclapp documents itself well, and almost everything above is discoverable in an afternoon. The cost is not the reading, it is that the next system answers the same questions with different mechanisms, and the one after that again. What we take off the list:

• The tenant, the token and the header choice. The subdomain is captured once at connection time and becomes the base URL, AuthenticationToken is attached to every call, and the prefill parameter keeps your customer from typing a tenant id you already hold.
• Fifteen subscriptions behind one call. Resource and event type pairs, our own companyId parameter and the signature check reach your code as the same event you already handle everywhere else.
• Two date formats and a string decimal. Epoch milliseconds, ISO 8601 in the beta expression syntax, amounts as strings and absent nulls arrive as one normalised shape.
• Page one, and the operator vocabulary. One-based paging, the 100 default and the thirteen filter operators sit behind one paged interface.

What stays with you, and the first two are decisions rather than tasks:

• Your request timeout. Weclapp asks for at least a minute because its queue can hold a successful call for 30 seconds. That number lives in your HTTP client and no integration layer can set it for you.
• How much you read, and how often. The budget is effective request time, so the shape of your sync is the lever. Fewer and larger beats many and small here, and the guidance to avoid unfiltered polling is Weclapp’s own.
• Knowing your own field names. A filter on a property that does not exist is accepted and dropped. Whatever validates your query fields, whether a test against a real tenant or a generated field list, is yours to run.
• The token lifecycle at the customer. A regenerated token retires the old one and nothing announces it. Detecting that, and asking the right person for a new one, is a support flow rather than an API call.