# SnelStart B2B API - Entity Relationship Diagram
> Gebaseerd op echte API responses en productie data
## Begrippen: Dagboek vs Bankboeking vs Grootboek
Voordat je de structuur begrijpt, moet je weten hoe deze drie begrippen samenhangen:
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ HIËRARCHIE: Dagboek → Bankboeking → Grootboekmutatie │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ DAGBOEK (bijv. "1190 Creditcard") │
│ ════════════════════════════════ │
│ = Een logboek/journaal waarin transacties worden geregistreerd │
│ = Container voor boekingen van hetzelfde type │
│ = Elk dagboek is gekoppeld aan een grootboekrekening │
│ │
│ │ │
│ │ bevat │
│ ▼ │
│ │
│ BANKBOEKING (één transactie) │
│ ═══════════════════════════ │
│ = Eén individuele transactie in het dagboek │
│ = Heeft datum, omschrijving, bedrag │
│ = Bevat boekingsregels die verwijzen naar grootboeken │
│ = Voorbeeld: "ANTHROPIC €249,82 op 16-01-2025" │
│ │
│ │ │
│ │ genereert │
│ ▼ │
│ │
│ GROOTBOEKMUTATIE(S) (het resultaat) │
│ ═══════════════════════════════════ │
│ = Het EFFECT van de boeking op de grootboekrekeningen │
│ = Altijd debet EN credit (dubbel boekhouden) │
│ = READ-ONLY in de API! Verwijder de bronboeking om mutatie te verwijderen │
│ = Voorbeeld: Credit 1190 €249,82, Debet 4610 €249,82 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Concrete uitleg:
| Begrip | Wat is het? | Voorbeeld (VCA) |
|--------|-------------|-----------------|
| **Dagboek 1190** | Een "logboek" voor creditcard transacties | Alle ICS creditcard afschrijvingen |
| **Bankboeking** | Eén transactie in dat dagboek | "ANTHROPIC €249,82 op 16-01" |
| **Grootboek 1190** | De balansrekening "Creditcard schuld" | Toont saldo: €825,95 openstaand |
| **Grootboekmutatie** | Het effect op een grootboekrekening | Credit 1190 €249,82, Debet 4610 €249,82 |
### Visueel voorbeeld:
```
DAGBOEK 1190 "Creditcard ICS" GROOTBOEKREKENING 1190
───────────────────────────── ──────────────────────
│ Bankboeking 16-01: │ Mutatie: Credit €249,82
│ ANTHROPIC €249,82 │ Mutatie: Credit €108,37
│ │ Mutatie: Credit €20,14
│ Bankboeking 13-01: │ ...
│ HAILUOAI €108,37 ───────► │ ───────────────────────
│ │ SALDO: €825,95
│ Bankboeking 19-01: │
│ LULU PRESS €20,14 │
│ ... │
```
### Orphan mutaties
Een **orphan mutatie** is een grootboekmutatie op rekening 1190 die GEEN bijbehorende bankboeking heeft. Dit kan ontstaan door:
- Foute MT940 imports
- Handmatige correcties in SnelStart
- Bugs in de import
**Probleem:** De mutatie staat wel op de grootboekrekening (saldo klopt niet), maar er is geen transactie om aan een factuur te koppelen.
**Oplossing:** Verwijder handmatig in SnelStart UI, of maak eerst een bankboeking aan.
---
## Master Data (Stamgegevens)
```
┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐
│ ADMINISTRATIE │ │ RELATIE │ │ LAND │
│ (CompanyInfo) │ │ (Klant/Leverancier) │ │ (Country) │
├─────────────────────────┤ ├─────────────────────────┤ ├─────────────────────────┤
│ PK id UUID │ │ PK id UUID │ ┌───>│ PK id UUID │
│ naam str │ │ naam str │ │ │ naam str │
│ kvkNummer str │ │ relatiesoort [] │ │ │ landcodeISO str? │
│ btwNummer str │ │ email str? │ │ │ (252 landen) │
│ straat str │ │ telefoon str? │ │ └─────────────────────────┘
│ postcode str │ │ btwNummer str? │ │
│ plaats str │ │ kvkNummer str? │ │ ┌─────────────────────────┐
└─────────────────────────┘ │ iban str? │ │ │ KOSTENPLAATS │
│ memo str? │ │ │ (Cost Center) │
│ FK land_id ──────────────────┘ ├─────────────────────────┤
└──────────┬──────────────┘ │ PK id UUID │
│ │ nummer int │
│ │ omschrijving str │
│ │ nonactief bool │
│ └─────────────────────────┘
```
## Boekhouding (Financiële Structuur)
```
┌─────────────────────────┐ ┌─────────────────────────┐
│ GROOTBOEK │ │ DAGBOEK │
│ (Ledger Account) │ │ (Journal) │
├─────────────────────────┤ ├─────────────────────────┤
│ PK id UUID │ │ PK id UUID │
│ nummer int │◄──────────────────────────────────────────>│ nummer int │
│ omschrijving str │ │ omschrijving str │
│ grootboeksoort enum │ │ dagboeksoort enum │
│ rgsCode json │ │ FK grootboek_id UUID │
│ nonactief bool │ └───────────┬─────────────┘
└───────────┬─────────────┘ │
│ Soorten: │
│ Soorten: • Bank │
│ • Balans • Kas │
│ • WinstEnVerlies • Inkoop │
│ • Memoriaal • Verkoop │
│ • Memoriaal │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ GROOTBOEKMUTATIE │ │ BANKBOEKING │
│ (Ledger Mutation) │ │ (Bank Transaction) │
├─────────────────────────┤ ├─────────────────────────┤
│ PK id UUID │ │ PK id UUID │
│ datum date │ │ datum date │
│ omschrijving str │ │ omschrijving str │
│ FK grootboek_id UUID │ │ boekstuk str │
│ debet dec │ │ FK dagboek_id UUID │
│ credit dec │ │ bedragUitgegeven dec │
│ FK relatie_id UUID? │ │ bedragOntvangen dec │
│ FK kostenplaats UUID? │ └───────────┬─────────────┘
└─────────────────────────┘ │
│
⚠️ BELANGRIJK: Grootboekmutaties zijn READ-ONLY in de API! │
Geen DELETE of PUT - alleen GET. │
Om een mutatie te verwijderen → verwijder de bronboeking. │
```
## Creditcard Boeking met Inkoopfactuur Koppeling
Dit is de **CORRECTE structuur** voor een creditcard betaling gekoppeld aan een inkoopfactuur:
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ BANKBOEKING op dagboek 1190 (creditcard) │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ id: "0347f0b9-ebe9-4aa8-a518-5f4912fbf997" │
│ dagboek: { id: "f3b0be5f-d201-4b0a-ac69-c95dfdb7fced" } ← 1190 ICS Creditcard │
│ omschrijving: "SPEEKLY.DE KOLN DE" │
│ bedragUitgegeven: 734.02 │
│ bedragOntvangen: 0 │
│ │
│ grootboekBoekingsRegels: [] ← LEEG! (geen directe grootboek boeking) │
│ │
│ inkoopboekingBoekingsRegels: [ │
│ { │
│ boekingId: { id: "d3c2d514-4c77-473c-94a4-6ef615e238e2" } ← KOPPELING! │
│ omschrijving: "SPEEKLY GmbH", │
│ debet: 734.02, │
│ credit: 0 │
│ } │
│ ] │
└─────────────────────────────────────────────────────────────────────────────────────────┘
│
│ inkoopboekingId verwijst naar:
▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ INKOOPBOEKING │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ id: "d3c2d514-4c77-473c-94a4-6ef615e238e2" │
│ leverancier: { id: "4797463f-5784-476e-962a-db8ed569405d" } ← Speekly GmbH │
│ factuurnummer: "NL-25-15-108" │
│ factuurdatum: "2025-01-16" │
│ factuurbedrag: 734.02 │
│ │
│ boekingsregels: [ │
│ { │
│ grootboek: { id: "9a6d9cde-1bbc-462f-9fde-7dd04b251786" } ← HIER het echte GB! │
│ omschrijving: "UGC-Video Gepersonaliseerd Human Design boek (2x)", │
│ bedrag: 734.02, │
│ btwSoort: "Geen" ← Duitse leverancier, BTW verlegd │
│ } │
│ ] │
│ │
│ documents: [ │
│ { │
│ id: "773f6454-aa95-46aa-9600-df6a21c02d9e", │
│ fileName: "speekly-NL-25-15-108.pdf" │
│ } │
│ ] │
└─────────────────────────────────────────────────────────────────────────────────────────┘
```
### Hoe de koppeling werkt:
1. **Bankboeking** heeft een regel in `inkoopboekingBoekingsRegels` met `boekingId` → verwijst naar de inkoopboeking
2. **grootboekBoekingsRegels is LEEG** - omdat het bedrag via de inkoopboeking naar het juiste grootboek gaat
3. **Inkoopboeking** bepaalt:
- Het echte grootboek (bijv. reclamekosten 4400)
- De BTW-behandeling (Hoog/Laag/Geen/Verlegd)
- De leverancier relatie
- Het document (PDF factuur)
### API Call voor koppeling:
```javascript
// Bankboeking aanmaken MET inkoopboeking koppeling
await client.request('/bankboekingen', 'POST', {
dagboek: { id: 'f3b0be5f-d201-4b0a-ac69-c95dfdb7fced' }, // 1190 creditcard
datum: '2025-01-16',
omschrijving: 'SPEEKLY.DE KOLN DE',
bedragUitgegeven: 734.02,
bedragOntvangen: 0,
grootboekBoekingsRegels: [], // LEEG!
inkoopboekingBoekingsRegels: [{ // HIER zit de koppeling
boekingId: { id: 'd3c2d514-4c77-473c-94a4-6ef615e238e2' },
omschrijving: 'speekly',
debet: 734.02,
credit: 0,
}],
verkoopboekingBoekingsRegels: [],
btwBoekingsregels: [],
});
```
## Inkoop Flow
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ INKOOPBOEKING │
│ (Purchase Invoice) │
├───────────────────────────────────────────┬─────────────────────────────────────────────┤
│ PK id UUID │ ┌─────────────────────────────────────────┐│
│ factuurnummer str │ │ BOEKINGSREGEL (Line Item) ││
│ factuurdatum date │ ├─────────────────────────────────────────┤│
│ FK leverancier_id ───────► RELATIE │ │ omschrijving str ││
│ omschrijving str │ │ FK grootboek_id ──────► GROOTBOEK ││
│ factuurbedrag decimal │ │ FK kostenplaats_id ───► KOSTENPLAATS ││
│ openstaandSaldo decimal │ │ bedrag decimal (excl BTW)│
│ │ │ btwSoort enum ││
│ BTW Array: │ │ (Hoog/Laag/Geen/Verlegd) ││
│ ┌─────────────────────────────────────┐ │ └─────────────────────────────────────────┘│
│ │ btwSoort: InkopenHoog/InkopenLaag/ │ │ │
│ │ InkopenVerlegd │ │ ┌─────────────────────────────────────────┐│
│ │ btwBedrag: decimal │ │ │ DOCUMENT (Attachment) ││
│ └─────────────────────────────────────┘ │ ├─────────────────────────────────────────┤│
│ │ │ PK id UUID ││
│ Link naar betaling: │ │ fileName str ││
│ Gekoppeld via bankboeking. │ │ parentIdentifier UUID ││
│ inkoopboekingBoekingsRegels │ │ readOnly bool ││
└───────────────────────────────────────────┴─────────────────────────────────────────────┘
```
## Verkoop Flow
```
┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐
│ OFFERTE │ │ VERKOOPORDER │ │ VERKOOPBOEKING │
│ (Quote) │──────>│ (Sales Order) │──────>│ (Sales Invoice) │
├─────────────────────────┤ ├─────────────────────────┤ ├─────────────────────────┤
│ PK id UUID │ │ PK id UUID │ │ PK id UUID │
│ offertenummer str │ │ ordernummer str │ │ factuurnummer str │
│ datum date │ │ datum date │ │ factuurDatum date │
│ FK klant_id ──► RELATIE │ │ FK klant_id ──► RELATIE │ │ FK klant_id ──► RELATIE │
│ totaalbedrag dec │ │ totaalbedrag dec │ │ factuurBedrag dec │
│ status enum │ │ status enum │ │ openstaandSaldo dec │
├─────────────────────────┤ ├─────────────────────────┤ ├─────────────────────────┤
│ Status: │ │ Status: │ │ BTW: │
│ • Concept │ │ • Concept │ │ • VerkopenHoog │
│ • Verstuurd │ │ • Open │ │ • VerkopenLaag │
│ • Geaccepteerd │ │ • Verwerkt │ │ • VerkopenVerlegd │
│ • Afgewezen │ │ • Geannuleerd │ │ │
│ • Verlopen │ │ │ │ │
└─────────────────────────┘ └─────────────────────────┘ └─────────────────────────┘
```
## Artikelen (Products)
```
┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐
│ ARTIKEL │ │ ARTIKELOMZETGROEP │ │ PRIJSAFSPRAAK │
│ (Product) │──────>│ (Revenue Group) │ │ (Price Agreement) │
├─────────────────────────┤ ├─────────────────────────┤ ├─────────────────────────┤
│ PK id UUID │ │ PK id UUID │ │ artikel_id UUID │
│ artikelcode str │ │ nummer int │ │ relatie_id UUID │
│ omschrijving str │ │ omschrijving str │ │ aantal dec │
│ verkoopprijs dec │ │ FK grootboek_id UUID │ │ verkoopprijs dec │
│ inkoopprijs dec │ └─────────────────────────┘ │ korting dec │
│ eenheid str │ │ datumVanaf date │
│ FK omzetgroep_id UUID │ Standaard groepen: │ datumTotEnMet date │
│ isNonActief bool │ • Hoog btw (goederen) └─────────────────────────┘
└─────────────────────────┘ • Laag btw (goederen)
• Hoog btw (diensten)
• Laag btw (diensten)
```
## Belangrijke ID's (VCA Administratie)
| Type | Nummer | Naam | UUID |
|------|--------|------|------|
| **Dagboek** | 1100 | ING Bank | `351a237c-fd1b-42dc-9540-231a6026d454` |
| **Dagboek** | 1190 | Creditcard ICS | `f3b0be5f-d201-4b0a-ac69-c95dfdb7fced` |
| **Dagboek** | 1300 | Debiteuren | `b640b8ce-eb77-49e9-8189-b321db93803b` |
| **Dagboek** | 1600 | Crediteuren | `5435a910-512c-4607-a1d8-abf259ec22ce` |
| **Grootboek** | 4100 | Inkoop goederen | `8aaecf2d-d61f-4814-b8cc-f97da5f2a3e9` |
| **Grootboek** | 4400 | Reclamekosten | `9a6d9cde-1bbc-462f-9fde-7dd04b251786` |
| **Grootboek** | 4610 | Kosten automatisering | `e050b9fc-c7a5-4324-a403-8309ca3cb91d` |
| **Grootboek** | 4620 | Hosting- en domeinkosten | `6ed3eb16-3d1f-4200-b612-b51f9335c185` |
## Workflow: Factuur Boeken
```
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ 1. LEVERANCIER│ │ 2. CREDITCARD │ │ 3. INKOOP- │ │ 4. KOPPELEN │
│ ZOEKEN │───────>│ TRANSACTIE │───────>│ BOEKING │───────>│ + DOCUMENT │
│ │ │ VINDEN │ │ AANMAKEN │ │ │
└───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘
│ │ │ │
▼ ▼ ▼ ▼
list_relaties list_boekingen create_inkoop- link_inkoop-
search="X" search="X" boeking boeking_to_
from/to_date bankboeking
│ │ │ │
▼ ▼ ▼ ▼
Als niet gevonden: Geeft bankboeking_id Geeft inkoopboeking_id Markeert factuur
create_relatie voor creditcard 1190 + upload document als BETAALD
via create_document
```
## Gevonden Bugs in MCP Tools
| Bug | Oorzaak | Fix |
|-----|---------|-----|
| `list_landen` met search: `Cannot read properties of null` | `landcodeISO` kan NULL zijn | Null-check: `l.landcodeISO?.toLowerCase()` |
| `get_invoice` voor type="verkoop" | `/verkoopfacturen/{id}` bestaat niet | Gebruik `/verkoopboekingen/{id}` |
| `list_verkooporders`: `Cannot read properties of undefined` | `klant.naam` kan undefined zijn | Optional chaining: `o.klant?.naam ?? "Onbekend"` |
| API veldnaam inconsistenties | Bankboeking: API verwacht 'datum', code stuurt 'boekdatum' | Correcte veldnamen gebruiken |
