Filing with FIRS
The three calls that take a draft invoice to registered with FIRS, and what to do when one fails.
Creating an invoice does not file it. Three further calls do.
Validate
curl -X POST https://api.taxlyne.com/api/v1/invoices/{id}/validate \
-H "X-API-Key: sk_live_…"Checks the invoice against what FIRS will accept, and moves it to Validated. Do this first — it is the cheapest place to find a problem.
Sign
curl -X POST https://api.taxlyne.com/api/v1/invoices/{id}/sign \
-H "X-API-Key: sk_live_…"Signs the invoice with your business's key. Moves it to Signed.
Submit
curl -X POST https://api.taxlyne.com/api/v1/invoices/{id}/submit \
-H "X-API-Key: sk_live_…"Registers the invoice with FIRS and moves it to Submitted, then onward as FIRS responds. This is the call that has an outside dependency, so it is the one that can fail for reasons that are nothing to do with your request.
All three need invoices:write.
Where it goes from there
Submission is not the end of the journey — FIRS responds asynchronously, and the invoice moves through further statuses on its own. Invoice statuses explains each one in plain language and tells you whether you need to act.
When submission fails
The invoice moves to Error, and recovery is automatic but slower and more limited than you might assume:
| Runs | every 10 minutes |
| Attempts | up to 3 |
| Only for | invoices touched in the last 24 hours |
An invoice that has exhausted its three attempts, or has sat in Error for more than a day, will not be picked up again. At that point it needs a deliberate re-submit.
Poll the invoice rather than re-submitting blindly. If recovery is still in play, another submit will not speed it up. If it is not — three attempts used, or older than 24 hours — a submit is exactly what is needed. The status tells you which.
Two failures worth recognising, because the message misleads:
"Access points are offline." This is about the buyer's access point, not ours. It means the party you are invoicing cannot currently receive it. Nothing on your side is wrong and nothing you change will fix it — the buyer's provider has to come back.
A validation error naming one field. FIRS validates one field at a time and stops at the first problem, so fixing the field it names may simply reveal the next. Expect to iterate rather than getting a complete list.
Tax
You send tax per line, as taxRate — a required percentage on every line. There is
no invoice-level tax field to set.
We aggregate those per-line rates into the invoice-level total FIRS expects, which is the only place FIRS counts tax. You do not need to do anything for that to happen, and there is nothing to group: the tax category is derived from the rate, so lines at the same rate land in the same category automatically.
FIRS does not check your arithmetic. A total that contradicts its own lines is accepted and filed. Nothing downstream will catch a mistake, so reconcile totals on your side before filing.