Van eerste sleutel tot eerste dossier

In drie stappen aangesloten

Credifin vult de sleutelnaam, rechten en het API-adres in. De sleutel blijft geldig tot intrekking en staat afgeschermd in het portaal. Bevoegde gebruikers kunnen hem opnieuw kopiëren.

1. 1

   Credifin activeert de koppeling

   Na activering verschijnt Koppelingen → API in het klantportaal.

2. 2

   De klantbeheerder maakt de sleutel

   Klik op Genereer API-key. Naam, scopes en geldigheid worden veilig ingevuld.

3. 3

   Kopieer en valideer

   Bewaar de sleutel in uw secret manager en voer de veilige validatie-cURL uit. De sleutel blijft afgeschermd; bevoegde gebruikers kunnen hem later opnieuw kopiëren.

API-adres

https://crm.credifin.nl

Authenticatieheader

Api-Key

Voorkeursroute

POST /api/v1/dossiers

Het API-adres is voor alle klanten gelijk. De sleutel koppelt elke aanvraag automatisch aan de juiste klant.

Zo werkt de API

Eén adres, één header, JSON in en JSON uit. Alles wat u hieronder leest geldt voor elke route.

Agenten

Klanten en agenten gebruiken dezelfde API en dezelfde documentatie. Een klantsleutel geeft toegang tot de eigen opdrachtgever. Een agentsleutel geeft toegang tot de bedrijven die op dat moment onder het agentschap vallen; een groepssleutel omvat ook de eigen vestigingen. De toegang wordt bij elke aanvraag opnieuw bepaald.

POST /api/creditor: maak met creditors:create en Idempotency-Key een bedrijf aan onder uw eigen agentschap. Gebruik de teruggegeven uuid of reference daarna als creditor. Deze aanvraag maakt geen gebruikersaccount aan.

Beheert u als agent meerdere klanten bij Credifin, dan krijgt u één sleutel voor uw hele agentschap. Credifin zet API-toegang per agent aan; de agentbeheerder maakt daarna zelf de sleutel aan onder Koppelingen → API. Nieuwe klanten binnen uw agentschap vallen direct onder dezelfde sleutel.

Overstappen vanuit CollectOnline

Overstappen in vijf stappen

1. Vraag activering aan. Credifin zet de API aan voor uw opdrachtgever en koppelt uw bestaande CollectOnline-identifiers.
2. Maak een sleutel onder Koppelingen → API en bewaar die in uw secret manager. De oude CollectOnline-sleutel werkt hier niet.
3. Vervang het adres https://credifin.collectonline.eu door https://crm.credifin.nl. De paden onder /api/... blijven gelijk.
4. Draai een acceptatietest: haal uw dossierlijst op, lees één dossier met /financial en lever een testdossier aan via POST /api/v1/dossiers/validate.
5. Loop de verschillen na in de tabel hieronder en schakel om. Meld ons welke routes u gebruikt; dan controleren wij die extra.

Rente, historie en creditnota's

Deze functies zijn beschikbaar voor alle klanten en agenten met de juiste rechten. Ze zijn onderdeel van de algemene API; er is geen aparte klantvariant. Open de route voor de voorwaarden, velden en antwoorden:

• Stel een vast rentebedrag op een factuur in — PUT /api/invoice/{invoice}/interest
• Lees de statushistorie van een dossier — GET /api/dossier/{dossier}/status/history
• Upload een creditnota-PDF — POST /api/creditnote/{creditNote}/attachment

Bij deze drie routes bepaalt de UUID in het pad bij welk bedrijf de aanvraag hoort. Een agentsleutel hoeft hier geen extra creditor mee te sturen. De dossier- en klantgrenzen blijven gelden.

Een gekoppelde CollectOnline-UUID blijft bruikbaar binnen uw huidige toegangsrechten. Een ontbrekende bronkoppeling of een resource buiten uw toegang geeft 404. Een niet-eenduidige bronkoppeling geeft 409. Meld in dat geval de route, UUID en X-Request-Id aan Credifin; maak geen vervangend dossier aan.

De statushistorie gebruikt de werkelijke statusdatum in Nederlandse tijd. Gebruik de overgang naar lost om een afboeking te herkennen; closed betekent positief gesloten. Een lege historie bewijst geen afboekdatum. Een historische notitie zonder bestand heeft attachmentName: null; er is dan geen bestand om te downloaden.

Identiteiten en creditnotabijlagen

Bij geïmporteerde dossiers kunnen meerdere historische debiteurregistraties bij dezelfde bron-UUID horen. De dossierlijst en het dossierdetail gebruiken dezelfde vaste debiteur-UUID als de opvraag met die bron-UUID. Bestaande dossiergegevens worden hiervoor niet samengevoegd.

Bij agenttoegang kan dezelfde oude debiteur-UUID bij meerdere opdrachtgevers voorkomen. Gebruik dan GET /api/debtor/{debtor}?creditor={creditor}. Zonder opdrachtgever volgt 409 LEGACY_ID_AMBIGUOUS. De UUID uit debtorUuid kan rechtstreeks worden opgevraagd.

Creditnota’s bevatten hasAttachment en invoice. Alleen zichtbare bijlagen tellen mee. invoice is null als geen factuurkoppeling is vastgelegd. Downloaden vereist daarnaast documentrechten; interne of geblokkeerde bestanden worden niet vrijgegeven.

GET /api/creditnote/{creditNote}/attachment

Testen met een testopdrachtgever

Testen gebeurt op hetzelfde API-adres met een aparte testopdrachtgever en een eigen klantsleutel. Gebruik uitsluitend fictieve dossiers en afgesproken testcontactgegevens. Een testsleutel hoort bij die opdrachtgever; het is geen toegang tot de echte klant. Er is geen aparte sandbox.

Laat Credifin een aparte testopdrachtgever aanmaken. Selecteer die in Koppelingen → API en maak een eigen sleutel aan. Een agentsleutel kan meerdere bedrijven omvatten; gebruik die niet om een test tot één bedrijf te beperken. Testdossiers volgen dezelfde verwerking als gewone dossiers. Gebruik voor webhooks alleen een testontvanger.

POST /api/dossier/{dossier}/close
Api-Key: YOUR_API_KEY
Idempotency-Key: withdrawal-your-unique-reference
Content-Type: application/json

{"reason":"incorrect_submission","note":"Incorrectly submitted by Ominimo; please stop collection."}

Complete debiteurenadressen

Stuur voor iedere debiteur de straat, het huisnummer met eventuele toevoeging, de postcode, de plaats en het land mee. Controleer dit voor alle bedrijven en vestigingen. Ontbrekende adresgegevens kunnen de dossierbehandeling blokkeren.

Bij de v1-dossieraanlevering staan deze velden verplicht in debtor.address. Een toevoeging kan apart in houseNumberAddition. De legacy-debiteurroutes gebruiken street, houseNumber (inclusief toevoeging), postalCode, city en country op het hoogste niveau. Dat legacy sommige velden technisch mag weglaten, betekent niet dat het adres compleet is.

Vul een bestaand adres aan met PUT /api/debtor/{debtor}, dossiers:create en een nieuwe Idempotency-Key per wijziging. Gebruik dezelfde sleutel en inhoud bij een retry. Een agentsleutel stuurt daarbij ook creditor mee. Lees de debiteur daarna opnieuw uit om de opgeslagen gegevens te controleren. POST /api/debtor werkt een bestaande debiteur niet bij.

PUT /api/debtor/{debtor}
Content-Type: application/json
Api-Key: <uw-api-key>
Idempotency-Key: debtor-address-1042-v1

{
  "creditor": "KLANT-1042",
  "street": "Keizersgracht",
  "houseNumber": "100 A",
  "postalCode": "1015CS",
  "city": "Amsterdam",
  "country": "NL"
}

Weggelaten velden blijven behouden; null of een lege waarde wist optionele velden. Bij 409 SHARED_DEBTOR wordt niets gewijzigd: stem de aanvulling met Credifin af. De wijziging geldt voor het gevonden debiteurrecord, niet automatisch voor afzonderlijke historische kopieën.

Authenticatie en veilige retries

Stuur de API-key alleen via HTTPS in de requestheader. Plaats sleutels nooit in een URL, browsercode of applicatielog.

Api-Key: <uw-api-key>
Idempotency-Key: order-73145-dossier-v1

Quickstart: veilig valideren

Sla de sleutel buiten uw shell-history op als CREDIFIN_API_KEY. Deze route controleert dezelfde velden als de productieroute, maar schrijft niets weg en start geen workflow.

test -n "$CREDIFIN_API_KEY" || { echo 'Sla uw API-key eerst veilig op als CREDIFIN_API_KEY.' >&2; exit 1; }

curl -X POST 'https://crm.credifin.nl/api/v1/dossiers/validate'   -H 'Content-Type: application/json'   -H "Api-Key: $CREDIFIN_API_KEY"   --data '{
    "reference": "DOS-2026-0042",
    "currency": "EUR",
    "debtor": {
      "reference": "KLANT-1042",
      "companyName": "Voorbeeld Handel B.V.",
      "language": "nl",
      "address": {
        "street": "Keizersgracht",
        "houseNumber": "100",
        "postalCode": "1015CS",
        "city": "Amsterdam",
        "country": "NL"
      }
    },
    "invoices": [{
      "reference": "INV-2026-0815",
      "date": "2026-12-01",
      "dueDate": "2026-12-31",
      "amount": 847.50
    }]
  }'

Extra dossiergegevens meesturen

Hoe meer gegevens in het dossier staan, hoe vaker Credifin een vraag van de debiteur direct kan beantwoorden.

U kiest de veldnamen zelf. Gebruik per soort gegeven steeds dezelfde naam. Hieronder staan voorbeelden.

Stuur deze velden mee bij het aanleveren, als lijst van naam en waarde:

"meta": [
  { "name": "kenteken", "value": "GF-132-X" },
  { "name": "opzegdatum", "value": "2026-05-01" }
]

Documenten zoals een opzegbrief, een bevestigingsmail (.eml of .msg) of een rekeningoverzicht stuurt u mee als bijlage.

Later aanvullen of wijzigen kan per dossier. Een veld met dezelfde naam wordt overschreven.

POST /api/dossier/{dossier}/meta
POST /api/dossier/{dossier}/attachment

Veelgebruikte flows

Vier patronen die vrijwel elke koppeling nodig heeft. Sla uw sleutel op als CREDIFIN_API_KEY en kopieer de voorbeelden.

curl -sS -D - 'https://crm.credifin.nl/api/dossier'   -H "Api-Key: $CREDIFIN_API_KEY"   -H 'X-API-FILTER-FROM: 2026-09-01 00:00:00'   -H 'X-API-PAGE-LIMIT: 200'   -H 'X-API-NEXT-PAGE: 1'

async function gewijzigdeDossiers(sinds) {
  const alles = [];
  let pagina = '1';
  while (pagina) {
    const antwoord = await fetch('https://crm.credifin.nl/api/dossier', {
      headers: {
        'Api-Key': process.env.CREDIFIN_API_KEY,
        'X-API-FILTER-FROM': sinds,
        'X-API-PAGE-LIMIT': '200',
        'X-API-NEXT-PAGE': pagina,
      },
    });
    if (!antwoord.ok) throw new Error('Credifin gaf ' + antwoord.status);
    alles.push(...(await antwoord.json()));
    pagina = antwoord.headers.get('X-API-NEXT-PAGE') || '';
  }
  return alles;
}

curl -sS 'https://crm.credifin.nl/api/dossier/c3069230-ff95-4c95-aa73-9c57945ae038/financial'   -H "Api-Key: $CREDIFIN_API_KEY"

curl -sS -X POST 'https://crm.credifin.nl/api/payment'   -H "Api-Key: $CREDIFIN_API_KEY"   -H 'Content-Type: application/json'   -H 'Idempotency-Key: betaling-2026-118'   --data '{ "dossier": "c3069230-ff95-4c95-aa73-9c57945ae038", "amount": 100, "date": "2026-07-03", "reference": "Bankafschrift 2026-118" }'

Statussen

De velden status en substatus in dossierresponses gebruiken de CollectOnline-namen. dossierClosed is een handige boolean voor gesloten en verloren dossiers.

Webhooks

Kies dossier.status.changed om statuswijzigingen automatisch te ontvangen. data bevat status, substatus, dossierClosed en previous. dossier.uuid identificeert het dossier en creditor.uuid de opdrachtgever. Gebruik GET /api/dossier/{dossier}/status om de actuele stand op te halen.

Webhooks worden asynchroon verwerkt. Verwerk dezelfde event-id slechts één keer en houd rekening met herhaalde of later ontvangen meldingen. Een webhook is een melding van een wijziging; aanvullende gegevens vraagt u via de beschreven API-routes op.

In plaats van te pollen laat u Credifin een bericht sturen zodra er iets in een dossier gebeurt. Een klantbeheerder voegt onder Koppelingen → Webhooks een URL toe, kiest de gebeurtenissen en krijgt eenmalig een geheim waarmee u elke melding controleert. Op dezelfde pagina ziet u elke verstuurde melding met inhoud, pogingen en een knop om opnieuw te versturen. U kunt meerdere webhooks registreren, bijvoorbeeld één per systeem. Credifin zet webhooks per opdrachtgever aan.

Agenten. Beheert u als agent meerdere klanten, dan registreert u één webhook voor uw hele agentschap. Die ontvangt de meldingen van al uw klanten, ook van klanten die u later aanmaakt; u hoeft per klant niets in te stellen. Elke melding bevat onder creditor het klantnummer en de naam van de klant en onder agency uw agentschap. Alleen voor agenten bestaat daarnaast de gebeurtenis creditor.created: er is een nieuwe klant onder uw agentschap aangemaakt. Credifin geeft webhooks per agent vrij.

Gebeurtenissen

De melding

Elke melding is een POST met JSON. dossier is een samenvatting van het dossier; data heeft dezelfde vorm als de bijbehorende API-resource, bijvoorbeeld een betaling bij payment.received. Bij debiteur- en klantgebeurtenissen en testmeldingen is dossier null. creditor noemt de opdrachtgever (uuid, klantnummer, naam) en agency het agentschap waar die onder valt, of null.

POST https://erp.uwbedrijf.nl/credifin/webhook
Content-Type: application/json
Credifin-Event: payment.received
Credifin-Event-Id: 5f1c4a2b-0d3e-4f6a-9b8c-7d6e5f4a3b2c
Credifin-Delivery-Id: e7c1b2a3-4d5e-4f60-8a7b-9c0d1e2f3a4b
Credifin-Timestamp: 1756729864
Credifin-Signature: t=1756729864,v1=2c3f…9a

{
  "id": "5f1c4a2b-0d3e-4f6a-9b8c-7d6e5f4a3b2c",
  "type": "payment.received",
  "version": 1,
  "occurredAt": "2026-09-01T12:30:00.000Z",
  "createdAt": "2026-09-01T12:31:04.000Z",
  "delivery": { "id": "e7c1b2a3-4d5e-4f60-8a7b-9c0d1e2f3a4b", "attempt": 1 },
  "creditor": { "uuid": "b1a7c8e2-1234-4f5a-8b9d-123456789abc", "reference": "106861", "name": "Voorbeeld B.V." },
  "agency": null,
  "dossier": {
    "uuid": "c3069230-ff95-4c95-aa73-9c57945ae038",
    "ownerReference": "IN146900",
    "reference": "ORDER-73145",
    "status": "open",
    "substatus": "IN_BEHANDELING",
    "dossierClosed": false,
    "balance": 747.5
  },
  "data": { "uuid": "a9c3d4e5-…", "amount": 100, "date": "2026-09-01", "receivedBy": "OWN_ACCOUNT" }
}

Handtekening controleren

Bereken HMAC-SHA256 over <timestamp>.<ruwe body> met uw geheim en vergelijk met v1 uit de header. Wijs meldingen af waarvan het tijdstempel meer dan vijf minuten afwijkt.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyCredifin(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((part) => part.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex');
  const actual = String(parts.v1 || '');
  return actual.length === expected.length && timingSafeEqual(Buffer.from(actual, 'hex'), Buffer.from(expected, 'hex'));
}

function verifyCredifin(string $secret, string $header, string $rawBody): bool {
  parse_str(str_replace(',', '&', $header), $parts);
  $timestamp = (int) ($parts['t'] ?? 0);
  if (abs(time() - $timestamp) > 300) return false;
  $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
  return hash_equals($expected, (string) ($parts['v1'] ?? ''));
}