Billit-koppeling
Door je Klantel-account te koppelen aan een Billit-abonnement, laat je Billit het officiële factuurnummer toewijzen en de Peppol-verzending uitvoeren. Klantel behoudt de tijdregistratie- en CRM-functionaliteit; Billit neemt de facturatiestroom over.
De Billit-koppeling is optioneel. Zonder koppeling genereert Klantel zelf UBL-facturen via de standalone-provider (zie Facturen).
Vereisten
- Een actief Billit-abonnement (zie billit.be)
- Beheerderrechten in Klantel (admin-rol)
Koppeling instellen
- Ga naar Instellingen → Billit-koppeling.
- Klik op Koppel Billit-account.
- Je wordt doorgestuurd naar de Billit-autorisatiepagina.
- Log in met je Billit-account en klik op Sta toegang toe.
- Je wordt teruggestuurd naar Klantel. De koppeling is actief.
Vanaf nu worden nieuwe facturen aangemaakt via je Billit-account. Billit wijst het officiële factuurnummer toe (bv. F2026/0042 in jouw Billit-nummerreeks) en verstuurt automatisch via Peppol als de ontvanger een Peppol-deelnemer is.
Hoe de OAuth-flow werkt
Klantel → (OAuth2 autorisatie-URL) → Billit-inlogpagina
Billit → (autorisatiecode) → /api/billit/oauth/callback
Klantel ← (access + refresh token versleuteld opgeslagen)
De tokens worden AES-256-GCM versleuteld opgeslagen in de database. Ze zijn nooit leesbaar als plaintext in logs of exports.
Veldmapping Klantel → Billit API
Bij het aanmaken van een factuur via de Billit-connector vertaalt Klantel zijn interne datamodel naar de Billit API-velden.
Factuurniveau
| Klantel-veld | Billit API-veld | Toelichting |
|---|---|---|
Factuur.id | reference | Interne Klantel-referentie voor correlatie |
Klant.naam | customer.name | Naam van de factuurationtvanger |
Klant.btwnummer | customer.vatNumber | Formaat BE0123456789 |
Klant.straat + huisnummer | customer.address.street + number | Adresonderdelen apart |
Klant.postcode | customer.address.postalCode | |
Klant.gemeente | customer.address.city | |
"BE" (vast) | customer.address.country | Altijd BE voor Belgische klanten |
invoer.vervalDagen ?? 30 | paymentTermDays | Betalingstermijn in dagen |
Factuurregelniveau
| Klantel-veld | Billit API-veld | Toelichting |
|---|---|---|
Regel.omschrijving | lines[].description | Omschrijving van de geleverde dienst |
Regel.aantalUur | lines[].quantity | Aantal uren als decimaal getal |
Regel.uurtariefCent / 100 | lines[].unitPrice | Omzetting eurocenten → euro (Billit verwacht euro's) |
Regel.btwTarief | lines[].vatRate | Percentage: 0, 6, 12 of 21 |
Responsverwerking
Billit retourneert bij een succesvolle uitreiking:
| Billit-responsveld | Klantel-opslag | Toelichting |
|---|---|---|
id | Factuur.externeId | Billit-intern ID voor statusopvragen |
invoiceNumber | Factuur.nummer | Officieel factuurnummer uit Billit-reeks |
ubl | Factuur.ublXml | UBL 2.1 XML gegenereerd door Billit |
netAmount × 100 | Factuur.bedragNettoCent | Euro → eurocent |
vatAmount × 100 | Factuur.bedragBtwCent | Euro → eurocent |
totalAmount × 100 | Factuur.bedragTotaalCent | Euro → eurocent |
Bedragen: Klantel slaat bedragen altijd op in eurocenten (ADR-0003). Billit communiceert in euro's met twee decimalen. De conversie (× 100, afgerond met Math.round) vindt plaats in BillitProvider.reikUit().
Webhook-statusupdates
Billit stuurt statusupdates naar POST /api/billit/webhook. De handtekening wordt geverifieerd met HMAC-SHA256 (X-Billit-Signature-header).
| Billit-event | Klantel-actie |
|---|---|
invoice.sent | peppolStatus = "verzonden" |
invoice.delivered | peppolStatus = "afgeleverd", status = "verzonden" |
invoice.payment_received | status = "betaald" |
invoice.failed | peppolStatus = "fout", status = "mislukt", admin-alert |
Stel de webhook-URL in in je Billit-portaal:
https://app.klantel.be/api/billit/webhook
En synchroniseer het gedeelde geheim (BILLIT_WEBHOOK_SECRET) met de waarde in je Coolify-omgevingsvariabelen.
Koppeling verbreken
- Ga naar Instellingen → Billit-koppeling.
- Klik op Ontkoppel.
- Nieuwe facturen worden aangemaakt via de standalone-provider.
- Bestaande Billit-facturen blijven zichtbaar in Klantel (alleen-lezen).
Omgevingsvariabelen
| Variabele | Verplicht | Beschrijving |
|---|---|---|
BILLIT_CLIENT_ID | Ja | OAuth client ID van de Klantel-app in Billit |
BILLIT_CLIENT_SECRET | Ja | OAuth client secret |
BILLIT_REDIRECT_URI | Ja | https://app.klantel.be/api/billit/oauth/callback |
BILLIT_WEBHOOK_SECRET | Ja | HMAC-geheim voor webhook-handtekeningverificatie |
BILLIT_API_BASE_URL | Nee | Standaard https://api.billit.be/v1 |
BILLIT_TOKEN_URL | Nee | Standaard https://auth.billit.be/oauth/token |
Probleemoplossing
'Billit-koppeling is niet geconfigureerd'
De OAuth-flow is niet voltooid of de tokens zijn verlopen en kunnen niet worden vernieuwd. Verbreek de koppeling en koppel opnieuw.
Factuur aanmaken geeft HTTP 422
Billit keurde de factuuraanvraag af. Controleer of het BTW-nummer van de klant correct is en of alle verplichte velden zijn ingevuld. De foutmelding van Billit is zichtbaar in de Sentry-logs.
Webhook-handtekening ongeldig
Synchroniseer BILLIT_WEBHOOK_SECRET in Coolify met de waarde in het Billit-portaal. Beide moeten exact overeenkomen.