Three Zeros Mean Yes

Integrating with a revenue authority is not like integrating with a software company. There is no developer relations team, the documentation is a specification rather than a guide, and the interface reflects the tax law rather than any idea of developer experience. It is also, once you accept that, an unusually clear thing to build against — because a specification does not change to suit anybody, and everything it does is written down.

Four fields, every time

Every response has the same shape: a result code, a message, the time the result was produced, and a data section that is populated when there is something to return.

One value of the result code means success. It is three zeros — a string, not a number, which matters because the leading zeros carry meaning and a numeric comparison would lose them.

So success is a comparison against that exact string. Not the response status, which is the same pattern that appeared with the mobile money connector and the chat provider whose body can refuse inside a healthy reply: the transport can be entirely fine while the answer is no.

A tax filing that reports success because the network worked is a filing that did not happen, on a record that says it did.

And the code stays in the message

When something is refused, the reported error carries the authority's own code alongside its own message. Deliberately, and against the usual instinct to translate.

The reason is that these codes are published. They are in the specification, they are searchable, and they are what anybody helping you — an accountant, a consultant, the authority's own support — will ask for. A code is a shared reference between parties who otherwise have no common vocabulary.

Translating it into a friendly sentence would make the message nicer to read and strictly less useful, because the friendly sentence is ours and appears in no document anybody else has. In a regulated interface, the provider's vocabulary is the useful one.

And where there is no code at all — a network failure, a response that is not the expected shape — the status is carried in its place, so the message never comes back empty.

Every workspace is its own taxpayer

This is the structural point, and it is what makes this connector different from every other one in the series.

There is no platform account. Each workspace files under its own tax identity: its own taxpayer identifier, its own branch, its own device.

1. A taxpayer identifier

   Whose tax obligation this is. It appears on every call, because every submission is a filing by that taxpayer.

2. A branch

   Which registered place of business. A company with several branches files separately for each.

3. A device serial

   The identity of the thing doing the invoicing. This is a device-based regime — the concept comes from physical tax registers, and the interface inherits it.

4. A key returned at initialisation

   Handed back when the device is registered and required on every subsequent call. It is what proves this device was enrolled.

The consequence is worth stating plainly: a filing is made by you, not on your behalf. The submission carries your identifier and your device, and what is filed is your record with the authority. That is the correct arrangement for a statutory obligation, and it means the setup involves your own registration rather than a key we could issue.

Initialisation is a one-way step

Registering the device is its own operation, done once, and it is the only call that does not carry the authorising key — because the point of it is to obtain that key.

The connector refuses to treat it as successful unless a key actually came back. That check is worth having: a response that is well formed, carries a success code and contains no key would otherwise be recorded as a completed initialisation, leaving a connector that believes it is enrolled and fails on every subsequent call for reasons that point elsewhere.

It is the same instinct as refusing a storage connection with no refresh token, or a messaging credential with no routing suffix. A configuration missing the thing that makes it work reads as unconfigured rather than as connected.

The test that files nothing real

Proving a statutory connection is awkward, because the obvious test — file something — has consequences.

So the connection test submits a minimal, well-formed document carrying a clearly marked test reference. It exercises the credentials, the device enrolment, the payload shape and the authority's validation, which is everything that can be wrong.

And it is run against the test environment, which is a per-workspace setting rather than a deployment-wide one — so a workspace can be testing while another is filing live, and going live is a deliberate switch rather than a consequence of where the software is running.

A tax code decided by a rule, not a lookup

One mapping detail worth surfacing, because it is a real business rule sitting in the connector.

Every invoice line has to carry a tax type. The connector derives it: a line taxed at nothing is marked zero-rated, and everything else is marked at the standard rate.

That is correct for the great majority of trade and it is a simplification, and the honest way to describe it is as a rule rather than as a classification. A business dealing in genuinely exempt supplies — which is a different thing from zero-rated, in law and in the codes — is a business whose invoices need that distinction made deliberately rather than derived from a rate.

Naming the rule is the point. A derived value that is right almost always is exactly the kind that nobody checks, and the person who needs to know is the one for whom it is not right.

What is in place, layer by layer

Three positions held on purpose

• The authority's codes and wording are surfaced rather than translated. A friendly sentence of our own appears in no document anybody else holds, and a published code is the only shared vocabulary between you, your accountant and the authority.
• Filing happens under your own tax identity, with no platform account in the middle. A statutory obligation is yours, and an arrangement where a vendor's credentials sit between you and the authority is the wrong shape for one.
• A derived tax classification is described as a derived rule. It is right for most trade, it is what nobody checks precisely because it is usually right, and the business it is wrong for is the one that most needs to know.

Frequently asked questions