> ## Documentation Index
> Fetch the complete documentation index at: https://docs.klantel.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Billit-koppeling

> Koppel een Billit-account voor professioneel factuurbeheer en Peppol-verzending

# 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.

<Note>
  De Billit-koppeling is optioneel. Zonder koppeling genereert Klantel zelf UBL-facturen via de **standalone-provider** (zie [Facturen](/handleiding/facturen)).
</Note>

## Vereisten

* Een actief **Billit-abonnement** (zie [billit.be](https://www.billit.be))
* Beheerderrechten in Klantel (admin-rol)

## Koppeling instellen

1. Ga naar **Instellingen** → **Billit-koppeling**.
2. Klik op **Koppel Billit-account**.
3. Je wordt doorgestuurd naar de Billit-autorisatiepagina.
4. Log in met je Billit-account en klik op **Sta toegang toe**.
5. 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                          |

<Warning>
  **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()`.
</Warning>

## 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

1. Ga naar **Instellingen** → **Billit-koppeling**.
2. Klik op **Ontkoppel**.
3. Nieuwe facturen worden aangemaakt via de standalone-provider.
4. 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

<AccordionGroup>
  <Accordion title="'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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Webhook-handtekening ongeldig">
    Synchroniseer `BILLIT_WEBHOOK_SECRET` in Coolify met de waarde in het Billit-portaal. Beide moeten exact overeenkomen.
  </Accordion>
</AccordionGroup>