Technische Handleiding: API documentatie Credifin

In CollectOnline vertegenwoordigt een case (ook wel dossier genoemd) een compleet incassotraject. Via de Recover API maak je deze cases aan en beheer je ze vanuit je eigen systeem. In deze documentatie combineren we de logica van het front-end systeem met concrete API voorbeelden, zodat jij je koppeling stap voor stap goed kunt inrichten.

Bij het inrichten van je koppeling maak je een fundamentele keuze: hoe groepeer je facturen tot een dossier? Er zijn twee methodes.

Optie A: Factuur logica (Invoice logic)

Gebruik deze methode als je vertrouwt op de standaard bedrijfsregels van CollectOnline. Het systeem bepaalt dan automatisch of er een nieuw dossier wordt aangemaakt of dat een factuur wordt toegevoegd aan een lopend dossier.

De belangrijkste regels:

• Juridische status: Staat een dossier al in de juridische fase (bijvoorbeeld bij de deurwaarder)? Dan maakt het systeem automatisch een nieuw dossier aan.
• Minnelijke status: Loopt er al een minnelijk dossier tegen dezelfde debiteur van dezelfde opdrachtgever? Dan wordt een nieuwe factuur, creditnota of betaling toegevoegd aan dat bestaande dossier.
• Betalingsregeling: Is er een actieve betalingsregeling? Dan wordt een nieuwe factuur aan hetzelfde dossier gekoppeld.
• Wetgeving: Regels zoals Boek XIX en Wki worden automatisch toegepast door het systeem.

Optie B: Dossier logica (Case logic)

Gebruik deze methode als je zelf de volledige controle wilt hebben over de dossiervorming.

Bij dossier logica is een uniek referentienummer verplicht bij het aanmaken van een dossier. Jij bepaalt als ontwikkelaar exact welke financiële transacties (facturen, creditnota's, betalingen) aan welk dossier worden gekoppeld. Daarmee overrule je bewust de standaard bedrijfslogica van CollectOnline.

Let op: gebruik je dossier logica, dan ben je zelf verantwoordelijk voor de juiste mapping van alle financiële regels en de correcte toepassing van relevante wetgeving (zoals Boek XIX en Wki).

Best practice: start bij voorkeur met factuur logica, tenzij je een zeer specifieke eigen dossiervorming of complexe interne logica hebt die je 1-op-1 wilt doorzetten naar CollectOnline.

Om de API te gebruiken heb je een API key nodig. Het type sleutel bepaalt tot welke endpoints je toegang hebt.

Type API sleutels

• Incasso API key: Volledige toegang tot alle endpoints.
• Creditor API key: Beperkte toegang, alleen tot je eigen dossiers en data.
• Bailiff API key: Toegang tot specifieke deurwaardersfuncties, zoals juridische procedures, kosten en derdengelden.

API key aanmaken

1. Log in op CollectOnline.
2. Ga in het menu naar Instellingen (Settings) → Webservice Documentatie.
3. Klik op Create API Key (of Overwrite als je een bestaande sleutel wilt vernieuwen).
4. Kopieer de sleutel via Copy API Key. Dit is je geheime authenticatiesleutel.
5. Noteer de Base URL die boven de sleutel staat. Deze gebruik je in al je requests.

Authenticatie in je request

Je stuurt de API key mee in de header van elk request.

Header voorbeeld (HTTP):
Api-Key: jouw-unieke-api-key

Base URL voorbeeld:
https://jouwbedrijf.collectonline.eu/api/

Verbinding testen

Je kunt je verbinding testen via cURL of Postman.

Voorbeeld via cURL (command line):
curl -H 'Api-Key: jouw-unieke-api-key' https://jouwbedrijf.collectonline.eu/api/debtor

Voorbeeld via Postman:

• Methode: GET
• URL: https://jouwbedrijf.collectonline.eu/api/debtor
• Header key: Api-Key
• Header value: jouw-api-key-hier

Voorbeeld responses en foutcodes

Succesvoorbeeld (vereenvoudigd):
{
'status': 'success',
'data': [ { 'uuid': 'debtor-uuid', 'name': 'Voorbeeld Debiteur' } ]
}

Ongeldige of ontbrekende API key (401 Unauthorized):
{
'status': 'error',
'code': 401,
'message': 'Unauthorized: invalid or missing API key'
}

Best practice:

• Gebruik altijd een aparte API key per omgeving (bijvoorbeeld test en productie).
• Sla je API key nooit op in front-end code of openbare repositories.
• Beperk de rechten van een Creditor API key tot wat strikt nodig is.

Het systeem ondersteunt specifieke wetgeving voor consumentenbescherming in België en Nederland. Een groot deel van deze logica wordt automatisch afgedwongen, vooral als je factuur logica gebruikt.

Boek XIX (België)

Boek XIX van het Wetboek van Economisch Recht regelt de minnelijke invordering bij Belgische consumenten. De wet schrijft onder andere verplichte wachttijden, meldingen en communicatievormen voor.

Toepassing in de API
Als je een dossier of factuur aanmaakt, controleert het systeem onder andere:

• Is de debiteur een Belgische consument?
• Is de wetgeving van toepassing op de opdrachtgever?

Als dat zo is, worden verplichte velden en termijnen afgedwongen. Voor een correcte aansturing gebruik je onder andere deze velden in je JSON:

• firstReminderDate: Datum van de eerste herinnering.
• firstReminderMethod: Verzendwijze van de eerste herinnering.
• firstReminderInterval: Intervaltermijn tussen herinneringen.
• KMO: Aanduiding of de schuldeiser een KMO is (heeft invloed op het kostenplafond).
• BookXIXDefaultEnabled: Schakelt de standaard Boek XIX logica in.
• BookXIXSubstractCost: Instelling voor de verrekening van kosten.

Voorbeeld Boek XIX payloadfragment:
{
'country': 'BE',
'debtorType': 'consumer',
'firstReminderDate': '2026-03-01',
'firstReminderMethod': 'EMAIL',
'firstReminderInterval': 14,
'KMO': true,
'BookXIXDefaultEnabled': true,
'BookXIXSubstractCost': false
}

Wki (Nederland)

De Wet kwaliteit incassodienstverlening (Wki) geldt voor vorderingen op consumenten en eenmanszaken (EZ, VOF, particulier) voor dossiers die je aanmaakt vanaf 1 oktober 2024.

Rekenregels Wki:

• Incassokosten (WIK) mag je maar één keer per 6 opeenvolgende facturen of termijnen in rekening brengen.
• De berekening gebeurt op basis van het hoogste factuurbedrag binnen die reeks van 6.
• Na de 7e termijn start een nieuwe reeks, waarbij opnieuw één keer kosten berekend mogen worden.
• Bij een nieuw dossier controleert het systeem of de debiteur in de afgelopen 6 maanden al een factuur had bij dezelfde opdrachtgever, zodat de staffel goed wordt toegepast.

Praktisch Wki voorbeeld (termijnenfacturen):
Je stuurt 6 maandtermijnen van 100 euro naar dezelfde debiteur. De API berekent één keer incassokosten over 100 euro voor die reeks van 6. Vanaf termijn 7 start een nieuwe reeks.

Belangrijk:

• Gebruik je factuur logica? Dan past CollectOnline de regels van Boek XIX en Wki automatisch toe.
• Gebruik je dossier logica? Dan ben je zelf verantwoordelijk voor de juiste toepassing van Boek XIX en Wki, inclusief het goed doorgeven van datums, landcodes en debiteuren type.

Best practice: stuur bij elk dossier minimaal het land, het type debiteur (consument of bedrijf) en de relevante factuur en herinneringsdatums mee. Zo kan de API direct toetsen of Boek XIX of Wki actief moet zijn.

Gebruik altijd vaste ISO standaarden om fouten bij het importeren te voorkomen. Zo voorkom je discussies over formaten en valideert de API je data beter.

• Taal: Kleine letters, ISO 639-1 (bijvoorbeeld: nl, fr, de, en, it).
• Land: Hoofdletters, ISO 3166-1 (bijvoorbeeld: BE, NL, LU).
• Valuta: Hoofdletters, ISO 4217 met 3 tekens (bijvoorbeeld: EUR, GBP, USD). Als je geen waarde meestuurt, wordt EUR gebruikt.
• Datum: Formaat JJJJ-MM-DD (bijvoorbeeld: 2026-03-15).
• Datum en tijd: Formaat JJJJ-MM-DD UU:mm:ss.

Voorbeeld combinatie in een invoice payload:
{
'language': 'nl',
'country': 'NL',
'currency': 'EUR',
'invoiceDate': '2026-03-15',
'dueDate': '2026-03-30',
'createdAt': '2026-03-15 10:30:00'
}

Best practice: valideer deze formaten al in je eigen applicatie voordat je een request verstuurt. Daarmee voorkom je onnodige foutmeldingen en herhaalde calls.

Hieronder zie je de workflow voor het opbouwen van een volledig dossier via de API. Dit proces werkt op basis van UUID's voor elke entiteit.

Stap 1: Entiteiten identificeren of aanmaken

Voordat je een factuur kunt inschieten, moeten de betrokken partijen bestaan en een UUID hebben.

A. Debiteur (Debtor)

• Aanmaken: POST /api/debtor
• Zoeken: GET /api/debtor
• Adres ophalen: GET /api/debtor/{debtor}/address
• Contactpersoon ophalen: GET /api/debtor/{debtor}/contact

Voorbeeld request (POST /api/debtor):
{
'externalReference': 'DEB-1001',
'name': 'Voorbeeld Debiteur BV',
'country': 'NL',
'language': 'nl',
'email': 'debiteur@example.com'
}

Resultaat: je ontvangt een Debtor UUID.

B. Opdrachtgever (Creditor)

• Aanmaken: POST /api/creditor
• Zoeken: GET /api/creditor

Voorbeeld request (POST /api/creditor):
{
'externalReference': 'CRED-2001',
'name': 'Jouw Bedrijf BV',
'country': 'NL',
'language': 'nl'
}

Resultaat: je ontvangt een Creditor UUID.

C. Dossier (Case)

• Aanmaken: POST /api/dossier
• Zoeken: GET /api/dossier

Voorbeeld request (POST /api/dossier, dossier logica):
{
'externalReference': 'DOS-3001',
'debtor': 'debtor-uuid',
'creditor': 'creditor-uuid',
'country': 'NL',
'debtorType': 'consumer'
}

Resultaat: je ontvangt een Dossier UUID.

Stap 2: Factuur aanmaken (Invoice creation)

Je koppelt de factuur (POST /api/invoice) op één van de twee manieren.

Methode 1: Via de debiteur (debtor based)

Verplicht veld: Debtor (UUID). Het systeem zoekt zelf het juiste dossier erbij op basis van de factuur logica.

Voorbeeld:
{
'debtor': 'debtor-uuid',
'invoiceNumber': '2026-0001',
'amount': 250.00,
'currency': 'EUR',
'invoiceDate': '2026-03-01',
'dueDate': '2026-03-31'
}

Methode 2: Via het dossier (dossier based)

Verplichte velden: Dossier (UUID) en Creditor (UUID). De factuur wordt hard gekoppeld aan het specifieke dossier dat jij aanwijst.

Voorbeeld:
{
'dossier': 'dossier-uuid',
'creditor': 'creditor-uuid',
'invoiceNumber': '2026-0002',
'amount': 500.00,
'currency': 'EUR',
'invoiceDate': '2026-03-05',
'dueDate': '2026-03-20'
}

Resultaat: je ontvangt een Invoice UUID.

Voorbeeld termijnenfacturen (Wki scenario)

Bij een reeks van 6 maandtermijnen stuur je 6 facturen met hetzelfde dossier of dezelfde debiteur. De API bewaakt dat de incassokosten slechts één keer per reeks worden berekend.

Voorbeeld eerste termijn:
{
'dossier': 'dossier-uuid',
'invoiceNumber': 'TERM-001',
'amount': 100.00,
'isInstallment': true,
'installmentSeries': 'ABO-2026-01'
}

Voorbeeld tweede termijn:
{
'dossier': 'dossier-uuid',
'invoiceNumber': 'TERM-002',
'amount': 100.00,
'isInstallment': true,
'installmentSeries': 'ABO-2026-01'
}

Stap 3: Vervolgacties en verrijking

Betaling toevoegen

• Endpoint: POST /api/payment
• Via Debiteur UUID (veld: debtor) of Dossier UUID (veld: dossier)

Voorbeeld:
{
'dossier': 'dossier-uuid',
'amount': 100.00,
'paymentDate': '2026-03-10',
'method': 'BANK_TRANSFER'
}

Resultaat: je ontvangt een Payment UUID.

Metadata toevoegen aan dossier

• Endpoint: POST /api/dossier/{dossier}/meta
• Alle meta velden ophalen: GET /api/dossier/{dossier}/meta

Voorbeeld:
{
'key': 'internalSegment',
'value': 'high-risk'
}

Bijlagen toevoegen (attachments)

• Aan dossier: POST /api/dossier/{dossier}/attachment
• Aan factuur: POST /api/invoice/{invoice}/attachment (bijvoorbeeld de originele PDF)

Resultaat: je ontvangt een Attachment UUID.

Creditnota aanmaken

• Endpoint: POST /api/creditnote
• Via Debiteur UUID (veld: debtor) of Dossier UUID (veld: dossier)

Voorbeeld:
{
'dossier': 'dossier-uuid',
'originalInvoice': 'invoice-uuid',
'amount': 50.00,
'reason': 'Korting overeengekomen met klant'
}

Best practice: bouw een interne flow waarin je altijd eerst controleert of debtor, creditor en dossier bestaan (en een geldige UUID hebben) voordat je een invoice of payment aanmaakt. Zo houd je je datamodel schoon en voorkom je losse facturen zonder bruikbare context.

Deze handleiding behandelt de belangrijkste workflows voor je integratie. Voor de volledige lijst met beschikbare endpoints, parameters en response codes gebruik je de interactieve documentatie in het portaal.

Waar vind je de technische details?

1. Log in op CollectOnline.
2. Ga naar Instellingen (Settings) → Webservice Documentatie.
3. Open de Swagger of OpenAPI documentatie.

Daar kun je:

• Alle endpoints en HTTP methodes bekijken.
• Exacte JSON schema's voor requests en responses inzien.
• Live calls testen met je eigen API key.

Veelvoorkomende HTTP statuscodes

• 200 OK: Request geslaagd, data aanwezig.
• 201 Created: Nieuwe resource succesvol aangemaakt (bijvoorbeeld debtor, dossier, invoice).
• 400 Bad Request: Request is ongeldig, bijvoorbeeld door ontbrekende of fout geformatteerde velden.
• 401 Unauthorized: API key ontbreekt of is ongeldig.
• 403 Forbidden: API key is geldig, maar heeft geen rechten voor dit endpoint.
• 404 Not Found: De gevraagde resource of endpoint bestaat niet.
• 500 Internal Server Error: Er ging iets mis aan de serverkant.

Voorbeeld 400 foutresponse:
{
'status': 'error',
'code': 400,
'message': 'Validation failed',
'errors': {
'invoiceDate': 'Invalid date format, expected YYYY-MM-DD',
'amount': 'Amount must be greater than 0'
}
}

Best practice:

• Log altijd de volledige request body, headers (zonder de ruwe API key) en response code bij fouten.
• Gebruik unieke correlatie IDs in je eigen systeem om API calls te kunnen terugzoeken.
• Test kritieke flows (zoals aanmaken van dossiers en invoices) eerst in een testomgeving.

Support voor developers

Kom je er niet uit met de integratie of krijg je onverwachte foutmeldingen?

• Controleer eerst of je API key de juiste rechten heeft (bijvoorbeeld Incasso vs Creditor).
• Bekijk de foutmelding en validatie errors in de response.
• Test hetzelfde request met de Swagger of Postman om lokale issues uit te sluiten.

Blijf je vastlopen, neem dan contact op met ons IT team