De facturatiedienst
Bijgewerkt op 2026-08-29
Dit hoofdstuk is niet voor een kapsalon. Het beschrijft het scherm Facturatiedienst in het platformpaneel: de koppeling met de dienst die de facturen van HairConnect aan zijn salons uitgeeft.
Wat de dienst doet en wat wij doen
HairConnect geeft zijn platformfacturen niet zelf uit. Dat gebeurt bij een externe facturatiedienst, en die neemt vier dingen voor haar rekening:
- het factuurnummer dat de klant op zijn document ziet;
- de PDF en de UBL van dat document;
- de btw-behandeling — Belgisch tarief, verlegging van heffing binnen de EU, of export — op basis van het land en het btw-nummer van het salon;
- de btw-bedragen die daaruit volgen.
Wij houden lokaal bij: welk salon, welke periode, welke regels, welk bedrag exclusief btw, en onze eigen referentie.
Onze referentie is geen factuurnummer
In de lijst staat bij een factuur ofwel het echte factuurnummer, ofwel ref. 2026-0001. Dat tweede is onze referentie: een doorlopende, gatenloze telling per boekjaar die we meesturen. Daaraan herkent de dienst een aanvraag die twee keer aankomt, en daaraan koppelen wij een uitgegeven document terug aan de juiste periode.
Het voorvoegsel ref. staat er met opzet. Zonder dat leest 2026-0001 als een factuurnummer, en dat is het niet.
De sleutel instellen
De API-sleutel staat niet in een configuratiebestand op de server maar op dit scherm. Dat scheelt een deploy bij elke wijziging, en het maakt op het scherm zichtbaar of er wel een sleutel staat.
Wat u invult:
| Veld | Wat erin hoort |
|---|---|
| Koppeling aan | Zet de koppeling aan. Zonder sleutel blijft ze uit, ook als deze aanstaat. |
| Adres van de dienst | De basis-URL inclusief het API-voorvoegsel, dus eindigend op /api/v1. |
| Pad voor een nieuwe factuur | Waar een factuur aangemaakt wordt, relatief aan het adres hierboven. Staat als instelling zodat dit rechtgezet kan worden zonder deploy. |
| Nieuwe sleutel | Plak hier de sleutel. |
De sleutel wordt versleuteld bewaard en komt nooit meer op het scherm — ook niet voor u. Wat u terugziet is dát er een sleutel staat, de laatste vier tekens, en de datum waarop hij gezet is.
Het veld is dan ook leeg wanneer u deze pagina opent, ook als er wel degelijk een sleutel staat. Dat is geen fout: leeg laten betekent "laat staan wat er staat". Wie een verkeerde sleutel plakte, plakt gewoon de juiste erover.
De juiste waarden
Een verse installatie staat meteen goed. Wie ze met de hand nakijkt:
| Veld | Waarde |
|---|---|
| Adres van de dienst | https://invoice.fades-management.com/api/v1 |
| Pad voor een nieuwe factuur | /invoices |
De valkuil. Laat u /api/v1 uit het adres weg, dan komt Verbinding testen op de website terecht in plaats van op de API, en antwoordt de dienst met 404 — The route me could not be found. Die melding wijst naar het pad terwijl het het adres is dat scheelt. Zet u het voorvoegsel er twee keer in — één keer in het adres en één keer in het pad — dan wordt het /api/v1/api/invoices en krijgt u dezelfde 404 bij het versturen van een factuur.
Verbinding testen
De knop Verbinding testen rechtsboven roept GET /me aan bij de dienst en toont wat er terugkomt. Dat is de snelste manier om te zien of de sleutel klopt vóór er een factuur langs moet.
Wat er gebeurt als de dienst niet bereikbaar is
Niets van uw eigen administratie gaat verloren. De koppeling is best effort:
- de factuur wordt lokaal gewoon vastgelegd, met haar regels en haar referentie;
- er wordt niets teruggedraaid en niets geblokkeerd;
- de reden staat bij de factuur in de lijst ("niet uitgegeven — …") en in het logboek;
- de knop Opnieuw versturen biedt de factuur nog eens aan.
Die knop is veilig om twee keer te gebruiken: de factuur houdt haar referentie, en zodra er een factuurnummer is, gebeurt er niets meer. Er komt dus nooit een tweede document voor dezelfde periode.
Zolang de btw niet bekend is, staat er in de kolommen Btw en Incl. btw een streepje. Dat is met opzet geen nul: nul zou beweren dat er geen btw is, en dat weten we niet.
Wat blokkeert er wél
De facturatiegegevens van het salon. Zonder naam, adres, land en btw-nummer kan de dienst niet bepalen welke btw-behandeling geldt, en dan zou ze gokken. Een factuur met de verkeerde behandeling is een fiscale fout bij twee partijen tegelijk.
Ontbreekt er iets, dan weigert Vastleggen met een melding die zegt welk veld. Vul het aan bij het salon zelf.
Wat er nog nagemeten moet worden
De adressen kloppen: GET /me is nagemeten en geeft een geldig antwoord. Twee dingen zijn dat nog niet:
- de exacte vorm van het antwoord op een aangemaakte factuur;
- de vorm van wat wij versturen — de veldnamen van de klantgegevens en van de referentie.
Het antwoord wordt daarom verdraagzaam uitgelezen: er worden meerdere aannemelijke veldnamen geprobeerd, en een eventuele data-omslag gaat eraf. Komt er een antwoord binnen zonder factuurnummer, dan wordt er niets verzonnen — de factuur blijft staan met de melding dat het antwoordformaat gecontroleerd moet worden.
Meet dit na op de server vóór de eerste echte factuur, en breng deze code daarna terug tot de vorm die de dienst werkelijk gebruikt.