The invoicing service
Updated on 2026-08-29
This chapter is not for a hair salon. It describes the Invoicing service screen in the platform panel: the integration with the service that issues HairConnect's invoices to its salons.
What the service does and what we do
HairConnect does not issue its platform invoices itself. That happens at an external invoicing service, which takes care of four things:
- the invoice number the customer sees on their document;
- the PDF and the UBL of that document;
- the VAT treatment — Belgian rate, intra-EU reverse charge, or export — based on the salon's country and VAT number;
- the VAT amounts that follow from it.
We keep locally: which salon, which period, which lines, which amount excluding VAT, and our own reference.
Our reference is not an invoice number
The list shows either the real invoice number or ref. 2026-0001. That second one is our reference: a continuous, gap-free count per fiscal year that we send along. The service uses it to recognise a request that arrives twice, and we use it to tie an issued document back to the right period.
The ref. prefix is there on purpose. Without it, 2026-0001 reads as an invoice number, and it is not one.
Setting the key
The API key is not in a configuration file on the server but on this screen. That saves a deploy on every change, and it makes it visible on screen whether there is a key at all.
What you fill in:
| Field | What belongs there |
|---|---|
| Integration on | Turns the integration on. Without a key it stays off, even when this is on. |
| Service address | The base URL including the API prefix, so ending in /api/v1. |
| Path for a new invoice | Where an invoice is created, relative to the address above. Kept as a setting so it can be corrected without a deploy. |
| New key | Paste the key here. |
The key is stored encrypted and never comes back on screen — not even for you. What you see again is that there is a key, its last four characters, and the date it was set.
So the field is empty when you open this page, even when there is in fact a key. That is not a bug: leaving it empty means "leave what is there". Anyone who pasted the wrong key simply pastes the right one over it.
The right values
A fresh install is correct out of the box. To check by hand:
| Field | Value |
|---|---|
| Service address | https://invoice.fades-management.com/api/v1 |
| Path for a new invoice | /invoices |
The trap. Leave /api/v1 out of the address and Test connection lands on the website instead of the API, and the service answers 404 — The route me could not be found. That message points at the path while it is the address that is wrong. Put the prefix in twice — once in the address and once in the path — and it becomes /api/v1/api/invoices, giving you the same 404 when an invoice is sent.
Testing the connection
The Test connection button at the top right calls GET /me at the service and shows what comes back. That is the quickest way to see whether the key is right before an invoice has to go through.
What happens when the service is unreachable
Nothing of your own administration is lost. The integration is best effort:
- the invoice is simply recorded locally, with its lines and its reference;
- nothing is rolled back and nothing is blocked;
- the reason appears next to the invoice in the list ("niet uitgegeven — …") and in the log;
- the Send again button offers the invoice once more.
That button is safe to use twice: the invoice keeps its reference, and as soon as an invoice number exists, nothing happens any more. So there is never a second document for the same period.
As long as the VAT is unknown, the VAT and Incl. VAT columns show a dash. That is deliberately not a zero: zero would claim there is no VAT, and we do not know that.
What does block
The salon's billing details. Without a name, address, country and VAT number, the service cannot determine which VAT treatment applies, and it would have to guess. An invoice with the wrong treatment is a tax error at two parties at once.
If something is missing, Record refuses with a message naming the field. Complete it at the salon itself.
What still has to be verified
The addresses are correct: GET /me has been measured and returns a valid answer. Two things are still not verified:
- the exact shape of the response to a created invoice;
- the shape of what we send — the field names of the customer details and of the reference.
The response is therefore read tolerantly: several plausible field names are tried, and a data wrapper is unwrapped. If a response arrives without an invoice number, nothing is invented — the invoice stays put with the message that the response format needs checking.
Verify this on the server before the first real invoice, then reduce this code to the shape the service actually uses.