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.

​Billit-koppeling

​Vereisten

​Koppeling instellen

​Hoe de OAuth-flow werkt

​Veldmapping Klantel → Billit API

​Factuurniveau

​Factuurregelniveau

​Responsverwerking

​Webhook-statusupdates

​Koppeling verbreken

​Omgevingsvariabelen

​Probleemoplossing

Billit-koppeling

Vereisten

Koppeling instellen

Hoe de OAuth-flow werkt

Veldmapping Klantel → Billit API

Factuurniveau

Factuurregelniveau

Responsverwerking

Webhook-statusupdates

Koppeling verbreken

Omgevingsvariabelen

Probleemoplossing