In this article (8 sections)
"It has to handle tax" is one line in an RFP, and it usually gets priced like any other feature, right next to "customer list". It isn't one. Wiring your system into a tax API you're required to go through —a government filing endpoint, a sales tax engine, an e-invoicing network— is the part of the project with the most rules you didn't write, the most in-between states and the least room for error, because you're not the one who decides if it passed.
Here's what's inside, so you can read a quote and know what to ask.
What "compliance by API" actually means
Your system doesn't produce the document. It asks for permission to.
The loop is: you assemble the document, send it to the other side, and wait. If everything checks out you get back an acceptance — a clearance code, a submission reference, a signed identifier, depending on the market — usually with a validity window of its own. Only with that reference is the document good. Without it you don't have an invoice. You have a draft.
That distinction is what shapes the whole design. Your system has to live with documents in three states: assembled but not sent, sent with no answer, and accepted. The second one is what wrecks integrations built in a hurry.
The three pieces you have to solve
Authentication
You don't get in with a username and a password. You get in with a credential the other side issued you: an X.509 certificate and its private key, a signed client assertion, an API key tied to a registered software ID. Certificates are the norm whenever a tax authority is on the other end.
The flow: your system signs a request with the certificate, sends it to the auth endpoint, and gets back an access token with a short life — hours, not days. That token carries every other call until it expires, and then it has to be renewed.
Three things to get right here:
- Cache the token. Asking for a new one on every document is the fastest way to start getting throttled.
- Renew it on its own, before it expires. If nobody built that, the system stops filing twelve hours in and nobody understands why.
- Store the private key like the secret it is. Not in the repo, not in the code, not in a variable anyone can read. That file files on your company's behalf.
The credential also has to be requested, and somebody has to authorize your software to act for the company — enrolling as a filer, registering the software, linking the account. That's the taxpayer's paperwork, not the developer's, and it's the most common reason a project stalls at the start. Begin it on day one of the project, not the week before go-live.
The document
This is where most of the real work is, and almost none of it is technical. It's tax.
You have to work out which document applies —invoice, credit note, debit note, corrected invoice— and which tax treatment goes with it: standard rate, reduced, exempt, zero-rated, reverse charge, out of scope. That depends on where you're registered, where the customer is and what you're selling. That logic lives in your system and it has to be right, because the other side validates some of it, not all of it.
Then the detail that blows up budgets: numbering is sequential per series and can't have gaps. If document 105 was accepted and 106 failed, you can't issue 107 before resolving 106. Sequential, gap-free numbering is a requirement in most places that regulate invoicing, and it's good practice everywhere. A system that assigns the number before it has the acceptance goes out of sync on day one of real use.
And the dates. There are tolerance windows between the document date and the date it gets accepted, and there are filing periods that close. Invoicing something on Monday dated last month isn't always allowed, and touching a period that's already been filed is a different and more expensive problem.
The errors
An integration that only covers the happy path isn't finished.
- Rejections. The other side returns error codes. Some are data — a tax ID that doesn't validate, a total that doesn't match the line items — and get corrected. Others are configuration, and don't.
- Warnings. The document is accepted anyway, with a note attached. Record it, don't drop it.
- Timeouts. The worst case: you sent the document and you don't know whether it was accepted. Never retry blind, because you can duplicate. The right move is to query the last accepted document for that series and decide from there.
- The service is down. It happens, and it happens at month end. Your system has to queue and retry later without the business grinding to a halt.
The difference between a two-week integration and a two-day one is almost entirely here. The happy path is fast. What takes time is everything that can go wrong.
Sandbox is not production
There's a separate test environment with its own credentials. You need it, and it will also mislead you: it's more permissive than the real one, and it answers faster.
Budget a testing phase in production, with real low-value documents, before you call the integration finished. It's the only way to find the validations the sandbox doesn't apply.
What to ask when someone quotes you this
- Which document types are in scope? Are credit and debit notes included, or extra?
- How is a timeout handled without duplicating the document?
- Where is the certificate's private key stored?
- Is token renewal automatic?
- Is there a retry path for when the service doesn't answer?
- Does it include testing in production, or only in the sandbox?
- When they publish a new version with a cutoff date, who updates it, and at what cost?
The last one decides the most money long term. These APIs change when the other side decides, on their calendar. An integration with no maintenance planned works until it stops working, and you don't get to pick that date.
When not to integrate
Worth saying out loud: it isn't always worth it.
If you file low volume with simple documents, the portal you already have access to is free, or already paid for, and it works. If you already run accounting software that files correctly, what you probably need is for your system to hand it the data, not to learn to file on its own.
The integration earns its keep when the document is the last step of a loop that already lives in your system — the order, the delivery note, the customer's balance — and keying it in somewhere else by hand means doing the work twice and opening the door to numbers that don't match.
If that loop isn't there yet, start there. Filing is the end of the process, not the beginning.
Tax rules and validations change, and they're different in every jurisdiction. Check the current official documentation and talk to your accountant before making decisions on this.