API-documentatie: koppel je administratie aan Credifin

Deze handleiding legt uit hoe je aansluit en welke keuzes je maakt. Alle endpoints, velden en voorbeelden staan in de volledige technische referentie op crm.credifin.nl/api/docs.

• Dossiers aanleveren: debiteur, facturen, documenten en extra gegevens in één aanvraag.
• Dossiers volgen: status, openstaand saldo en het volledige financiële overzicht met hoofdsom, rente, incassokosten, betalingen en creditnota's.
• Betalingen melden die de debiteur rechtstreeks aan jou heeft betaald.
• Aanvullen: extra gegevens en documenten toevoegen terwijl het dossier loopt.
• Meldingen ontvangen via webhooks, zodat je niet steeds hoeft op te vragen of er iets is veranderd.

1. Credifin activeert de koppeling. Vraag activering aan via je contactpersoon of plan een API-intake. Daarna verschijnt in het klantportaal het onderdeel Koppelingen → API.
2. Je maakt zelf de API-key. Een klantbeheerder klikt op Genereer API-key. Naam, rechten en geldigheid worden automatisch ingevuld. De sleutel begint met cfi_live_ en blijft geldig tot je hem intrekt.
3. Kopieer en test. Bewaar de sleutel in een beveiligde opslag, zoals een secret manager. Test je eerste aanvraag met de validatieroute uit stap 1 van het stappenplan hieronder.

Het API-adres is voor iedere klant hetzelfde. De sleutel bepaalt automatisch voor welke opdrachtgever een aanvraag geldt. Je ziet en wijzigt alleen je eigen dossiers.

Rechten van een sleutel

Werk je als agent voor meerdere klanten?

Dan krijg je één sleutel voor je hele agentschap. Met GET /api/creditor zie je voor welke klanten die sleutel werkt.

Bij het aanleveren geef je in het veld creditor het klantnummer of de uuid van de klant mee. Nieuwe klanten vallen automatisch onder dezelfde sleutel; je hoeft per klant niets in te stellen.

Stuur de sleutel mee in de header Api-Key van elke aanvraag, uitsluitend via HTTPS.

Test je verbinding met een eenvoudige leesaanvraag: GET /api/creditor. Je krijgt dan je eigen opdrachtgever terug.

Veilig opnieuw versturen met Idempotency-Key

Stuur bij elke POST een Idempotency-Key mee: een unieke sleutel per aanvraag, bijvoorbeeld je eigen ordernummer. Krijg je een time-out? Verstuur dan exact dezelfde body met dezelfde key.

Credifin geeft dan hetzelfde antwoord terug en maakt nooit een tweede dossier aan. Gebruik dezelfde key nooit voor een andere body; dan krijg je 409 IDEMPOTENCY_KEY_REUSED. Bij POST /api/v1/dossiers is de key verplicht.

Goede gewoonten

• Zet de sleutel nooit in een URL, browsercode, openbare repository of logbestand.
• Een sleutel die is uitgelekt of niet meer nodig is, trek je in via Koppelingen → API met Sleutel intrekken.
• Bewaar de X-Request-Id van elke aanvraag. Daarmee vinden wij één aanroep terug bij een supportvraag, zonder dat je sleutels of persoonsgegevens hoeft te delen.
• Elke response bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Krijg je 429, wacht dan het aantal seconden uit Retry-After af.

Je levert per factuur alleen de hoofdsom aan. Wettelijke rente en incassokosten berekent Credifin zelf, op basis van de facturen, het type debiteur en het land.

• Bedrijf of particulier. Vul je companyName of companyNumber (KvK-nummer) in, dan behandelt Credifin de debiteur als bedrijf. Laat je die leeg en vul je firstName en lastName in, dan gaat het om een particulier. Deze keuze bepaalt welke regels gelden.
• Nederlandse consumenten (WIK). Het traject begint met de kosteloze veertiendagenbrief. Pas als die termijn verstrijkt zonder betaling, rekent Credifin incassokosten volgens de wettelijke staffel. Binnen die termijn kan de debiteur altijd zonder incassokosten betalen.
• Zakelijke debiteuren. Er gaat geen veertiendagenbrief uit en Credifin rekent met de wettelijke handelsrente.
• Debiteuren buiten Nederland. Credifin stuurt geen WIK-brief naar debiteuren buiten Nederland. Geef daarom altijd de juiste landcode mee.
• Nooit te vroeg. Het dossier staat direct in het systeem, maar het incassotraject start nooit vóór de dag na de laatste vervaldatum die je opgeeft.

Heb je zelf al een veertiendagenbrief verstuurd? Stem dat vooraf met ons af, zodat de debiteur geen tweede brief krijgt.

Bijlagen stuur je als base64 mee, zonder data:-voorvoegsel. Toegestaan zijn pdf, afbeeldingen (ook HEIC), HTML, XML/UBL, EML, MSG, DOCX, XLSX, tekst en csv.

Een bestand mag maximaal 10 MB zijn. Via POST /api/v1/dossiers lever je per dossier maximaal 25 bijlagen aan, samen maximaal 25 MB. Credifin controleert elk bestand op inhoud en haalt het door een virusscanner voordat het wordt opgeslagen.

Lijsten worden verdeeld over pagina's. Stuur X-API-NEXT-PAGE (eerste pagina is 1) en X-API-PAGE-LIMIT (standaard 20, maximaal 200) mee. De response geeft in X-API-NEXT-PAGE het volgende paginanummer terug; is die leeg, dan heb je alles.

In zes stappen van je eerste test naar een volledige koppeling. Kopieerbare voorbeelden in cURL, JavaScript en PHP staan in de technische referentie.

Stap 1: Controleer je aanvraag zonder iets op te slaan

Met POST /api/v1/dossiers/validate controleert Credifin precies dezelfde velden als bij een echte aanlevering. Er wordt niets opgeslagen en er start geen traject. Gebruik deze route tijdens het bouwen en vóór je eerste echte aanlevering.

Stuur dezelfde JSON-body die je straks echt aanlevert: je referentie, de debiteur met adres en taal, en de facturen. Is alles in orde, dan meldt de API dat de aanvraag geldig is en dat er niets is opgeslagen, met het aantal facturen en het totaalbedrag. Klopt er iets niet, dan zie je per veld wat er mis is.

Stap 2: Lever het dossier aan

Stuur dezelfde body naar POST /api/v1/dossiers, nu met een vaste Idempotency-Key. Credifin verwerkt de hele aanvraag in één keer: alles wordt opgeslagen of niets. Je loopt dus nooit tegen een half aangemaakt dossier aan.

Je krijgt 201 Created terug, met onder meer de dossierId. Bewaar die; je gebruikt hem bij alle vervolgaanvragen.

Gaat het om een particulier, vul dan firstName en lastName in en laat companyName en companyNumber leeg.

Stap 3: Geef extra gegevens en documenten mee

Hoe meer informatie in het dossier staat, hoe vaker Credifin een vraag van de debiteur direct kan beantwoorden. Stuur daarom documenten en extra gegevens mee, zoals het contract, de factuur-pdf of een bevestigingsmail.

Documenten stuur je mee in attachments: per bestand de bestandsnaam en de inhoud als base64. Extra gegevens stuur je mee in meta, als lijst van naam en waarde, bijvoorbeeld contractnummer of opzegdatum.

Een bijlage bij een specifieke factuur zet je in attachments binnen die factuur. Kies voor meta vaste namen per soort gegeven en schrijf datums als JJJJ-MM-DD.

Later aanvullen kan per dossier via POST /api/dossier/{dossier}/meta en POST /api/dossier/{dossier}/attachment. Een veld met dezelfde naam wordt overschreven.

Stap 4: Volg de stand van je dossiers

Haal de gewijzigde dossiers op met X-API-FILTER-FROM (bijvoorbeeld 2026-10-01 00:00:00) en loop de pagina's door tot X-API-NEXT-PAGE leeg is.

Stap 5: Meld betalingen die je zelf ontvangt

Heeft de debiteur rechtstreeks aan jou betaald? Meld dat dan met POST /api/payment. Het saldo, een lopende regeling en de afrekening worden direct bijgewerkt, en je behandelaar ziet de melding.

Geef het dossier, het bedrag, de ontvangstdatum en je eigen kenmerk mee, bijvoorbeeld het nummer van het bankafschrift.

Betalingen op de derdengeldenrekening van Credifin boeken wij zelf; die meld je niet. Daarom accepteert deze route alleen betalingen die jij hebt ontvangen. Staat deze functie nog uit voor jouw organisatie, dan krijg je PAYMENT_REPORTING_NOT_ENABLED. Vraag ons dan om hem aan te zetten.

Stap 6: Ontvang meldingen via webhooks

In plaats van steeds op te vragen of er iets is veranderd, laat je Credifin een bericht sturen. Een klantbeheerder voegt onder Koppelingen → Webhooks een URL toe, kiest de gebeurtenissen en krijgt eenmalig een geheim om meldingen mee te controleren. Credifin zet webhooks per opdrachtgever aan.

Elke melding is een POST met JSON en de headers Credifin-Event, Credifin-Event-Id en Credifin-Signature. Controleer de handtekening: bereken HMAC-SHA256 over het tijdstempel, een punt en de ruwe body, met je geheim als sleutel. Vergelijk de uitkomst met v1 uit de header. Wijs meldingen af waarvan het tijdstempel meer dan vijf minuten afwijkt. Een voorbeeld in Node.js en PHP staat in de technische referentie.

• Antwoord snel. Bevestig binnen tien seconden met een 2xx-status en verwerk de melding daarna. Redirects worden niet gevolgd.
• Herkansingen. Mislukt een melding, dan probeert Credifin het opnieuw na 1 minuut, 5 minuten, 30 minuten, 2 uur, 12 uur en 24 uur. Na 50 mislukte pogingen op rij wordt de webhook gepauzeerd.
• Dubbel of in een andere volgorde. Een melding kan meer dan één keer aankomen. Bewaar het id en negeer herhalingen. Gebruik occurredAt voor de volgorde.
• Testen. Met Test versturen in het portaal krijg je direct een testmelding en zie je het antwoord van je server.

Het veld dossierClosed geeft in één oogopslag aan of een dossier gesloten is.

Gebruik in je eigen software de vaste code uit een foutmelding, niet de leesbare tekst; die tekst kan veranderen. Herhaal een aanvraag alleen als retryable op true staat, en gebruik dan dezelfde Idempotency-Key.

/api/v1-routes geven fouten terug als application/problem+json. De bestaande /api/...-routes gebruiken een error-object met vergelijkbare velden.

Elke foutmelding bevat een vaste code, een leesbare uitleg, een requestId en retryable. Bij een validatiefout staat per veld wat er mis is, bijvoorbeeld veld invoices[0].dueDate met code INVALID_DATE.

Kom je er niet uit?

Stuur ons de X-Request-Id (of requestId) van de aanvraag, het tijdstip en de route. Stuur nooit je API-key mee. Daarmee vinden wij de aanroep terug en kijken we met je mee.