Vom ersten Schlüssel zur ersten Akte

In drei Schritten verbunden

Credifin gibt Schlüsselname, Berechtigungen und API-Adresse vor. Der Schlüssel gilt bis zum Widerruf und bleibt maskiert, kann jedoch von berechtigten Benutzern kopiert werden.

1. 1

   Credifin aktiviert die Anbindung

   Nach Aktivierung erscheint Anbindungen → API im Kundenportal.

2. 2

   Der Kundenadministrator erstellt den Schlüssel

   Klicken Sie auf API-Schlüssel erstellen. Name und Berechtigungen sind voreingestellt; der Schlüssel gilt bis zum Widerruf.

3. 3

   Kopieren und validieren

   Speichern Sie den Schlüssel im Secret-Manager und führen Sie den sicheren Validierungs-cURL aus. Das Präfix bleibt sichtbar; das Geheimnis bleibt verborgen und kann auf Anfrage kopiert werden.

API-Adresse

https://crm.credifin.nl

Authentifizierungsheader

Api-Key

Bevorzugte Route

POST /api/v1/dossiers

Die API-Adresse ist für alle Kunden gleich. Der Schlüssel ordnet jede Anfrage automatisch dem richtigen Kunden zu.

So funktioniert die API

Eine Adresse, ein Header, JSON rein und JSON raus. Alles Folgende gilt für jede Route.

Agenturen

Kunden und Agenturen verwenden dieselbe API und Dokumentation. Ein Kundenschlüssel gewährt Zugriff auf den eigenen Auftraggeber. Ein Agenturschlüssel umfasst die aktuell zugeordneten Unternehmen; ein Gruppenschlüssel umfasst auch die eigenen Niederlassungen. Der Zugriff wird bei jeder Anfrage erneut bestimmt.

POST /api/creditor: verwenden Sie creditors:create und Idempotency-Key zum Anlegen eines Unternehmens unter Ihrer eigenen Agentur. Verwenden Sie die zurückgegebene uuid oder reference anschließend als creditor. Diese Anfrage erstellt kein Benutzerkonto.

Wenn Sie als Agentur mehrere Kunden betreuen, erhalten Sie einen Schlüssel für die gesamte Agentur. Credifin aktiviert den Zugriff pro Agentur; der Administrator erstellt den Schlüssel unter Anbindungen → API. Neue Kunden innerhalb Ihrer Agentur fallen sofort unter denselben Schlüssel.

Umstieg von CollectOnline

Umstellung in fünf Schritten

1. Aktivierung anfordern. Credifin aktiviert die API für Ihren Auftraggeber und ordnet bestehende CollectOnline-Kennungen zu.
2. Schlüssel erstellen unter Anbindungen → API und speichern Sie ihn in Ihrem Secret Manager. Der alte CollectOnline-Schlüssel funktioniert hier nicht.
3. Ersetzen Sie die Adresse https://credifin.collectonline.eu durch https://crm.credifin.nl. Die Pfade unter /api/... bleiben unverändert.
4. Abnahmetest durchführen: Rufen Sie Ihre Aktenliste und eine einzelne Akte ab mit /financial und reichen Sie eine Testakte ein über POST /api/v1/dossiers/validate.
5. Unterschiede prüfen in der Tabelle unten und stellen Sie um. Teilen Sie uns Ihre Routen mit, damit wir diese gezielt prüfen.

Zinsen, Verlauf und Gutschriften

Diese Funktionen stehen allen Kunden und Agenturen mit den erforderlichen Rechten zur Verfügung. Sie gehören zur allgemeinen API; es gibt keine kundenspezifische Variante. Öffnen Sie die Route für Bedingungen, Felder und Antworten:

• Einen festen Zinsbetrag für eine Rechnung festlegen — PUT /api/invoice/{invoice}/interest
• Statusverlauf einer Akte lesen — GET /api/dossier/{dossier}/status/history
• Eine Gutschrift als PDF hochladen — POST /api/creditnote/{creditNote}/attachment

Bei diesen drei Routen bestimmt die UUID im Pfad, zu welchem Unternehmen die Anfrage gehört. Ein Agenturschlüssel muss hier keinen zusätzlichen creditor übermitteln. Die Zugriffsgrenzen für Akten und Kunden gelten weiterhin.

Eine verknüpfte CollectOnline-UUID bleibt innerhalb Ihrer aktuellen Zugriffsrechte nutzbar. Eine fehlende Quellverknüpfung oder eine Ressource außerhalb Ihres Zugriffs ergibt 404. Eine mehrdeutige Quellverknüpfung ergibt 409. Melden Sie dann Route, UUID und X-Request-Id an Credifin; legen Sie keine Ersatzakte an.

Der Statusverlauf verwendet den tatsächlichen Statuszeitpunkt in niederländischer Ortszeit. Der Übergang zu lost kennzeichnet eine Abschreibung; closed bedeutet positiv abgeschlossen. Ein leerer Verlauf belegt kein Abschreibungsdatum. Eine historische Notiz ohne Datei hat attachmentName: null; es gibt keine Datei zum Herunterladen.

Identitäten und Gutschriftanhänge

Importierte Akten können mehrere historische Schuldnerdatensätze zur selben Quell-UUID enthalten. Aktenliste und Detail verwenden dieselbe feste Schuldner-UUID wie die Abfrage über diese Quell-UUID. Bestehende Akten werden dafür nicht zusammengeführt.

Bei Agentenzugriff kann dieselbe alte Schuldner-UUID bei mehreren Auftraggebern vorkommen. Verwenden Sie dann GET /api/debtor/{debtor}?creditor={creditor}. Ohne Auftraggeber lautet die Antwort 409 LEGACY_ID_AMBIGUOUS. Die UUID aus debtorUuid kann direkt abgefragt werden.

Gutschriften enthalten hasAttachment und invoice. Nur sichtbare Anhänge werden gezählt. invoice ist null, wenn keine Rechnungsverknüpfung hinterlegt ist. Downloads erfordern zusätzlich Dokumentenrechte; interne oder gesperrte Dateien werden nicht freigegeben.

GET /api/creditnote/{creditNote}/attachment

Testen mit einem Testauftraggeber

Tests erfolgen unter derselben API-Adresse mit einem separaten Testauftraggeber und eigenem Kundenschlüssel. Verwenden Sie nur fiktive Akten und vereinbarte Testkontaktdaten. Der Testschlüssel gehört zu diesem Auftraggeber und gewährt keinen Zugriff auf den echten Kunden. Es gibt keine separate Sandbox.

Lassen Sie Credifin einen separaten Testauftraggeber anlegen. Wählen Sie ihn unter Anbindungen → API und erstellen Sie einen eigenen Schlüssel. Ein Agentenschlüssel kann mehrere Unternehmen umfassen; verwenden Sie ihn nicht, um einen Test auf ein Unternehmen zu begrenzen. Testakten werden wie reguläre Akten verarbeitet. Verwenden Sie für Webhooks nur einen Testempfänger.

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."}

Vollständige Schuldneradressen

Übermitteln Sie für jeden Schuldner Straße, Hausnummer mit eventuellem Zusatz, Postleitzahl, Ort und Land. Prüfen Sie dies für alle Unternehmen und Niederlassungen. Fehlende Adressdaten können die Aktenbearbeitung blockieren.

Bei der v1-Aktenübergabe sind diese Felder unter debtor.address erforderlich. Ein Zusatz kann separat in houseNumberAddition stehen. Die Legacy-Schuldnerrouten verwenden street, houseNumber (einschließlich Zusatz), postalCode, city und country auf oberster Ebene. Dass Legacy einzelne Felder technisch weglassen lässt, bedeutet nicht, dass die Adresse vollständig ist.

Ergänzen Sie eine bestehende Adresse mit PUT /api/debtor/{debtor}, dossiers:create und einem neuen Idempotency-Key pro Änderung. Verwenden Sie bei Wiederholungen denselben Schlüssel und Inhalt. Ein Agenturschlüssel muss auch creditor übermitteln. Lesen Sie den Schuldner danach erneut aus, um die gespeicherten Daten zu prüfen. POST /api/debtor aktualisiert keinen bestehenden Schuldner.

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"
}

Ausgelassene Felder bleiben erhalten; null oder ein leerer Wert löscht optionale Felder. Bei 409 SHARED_DEBTOR wird nichts geändert: stimmen Sie die Ergänzung mit Credifin ab. Die Änderung gilt für den gefundenen Schuldnerdatensatz, nicht automatisch für separate historische Kopien.

Authentifizierung und sichere Wiederholungen

Senden Sie den API-Schlüssel ausschließlich per HTTPS im Anfrageheader. Schlüssel gehören niemals in URLs, Browsercode oder Anwendungsprotokolle.

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

Schnellstart: sichere Validierung

Speichern Sie den Schlüssel außerhalb Ihres Shell-Verlaufs als CREDIFIN_API_KEY. Diese Route prüft dieselben Felder wie die Produktivroute, speichert jedoch nichts und startet keinen Ablauf.

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
    }]
  }'

Zusätzliche Aktendaten mitsenden

Je mehr Daten die Akte enthält, desto öfter kann Credifin eine Frage des Schuldners sofort beantworten.

Sie wählen die Feldnamen selbst. Verwenden Sie für dieselbe Angabe immer denselben Namen. Beispiele finden Sie unten.

Senden Sie diese Felder bei der Einreichung als Liste aus Name und Wert mit:

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

Unterlagen wie ein Kündigungsschreiben, eine Bestätigungs-E-Mail (.eml oder .msg) oder einen Kontoauszug senden Sie als Anhang mit.

Ergänzungen oder Änderungen sind später pro Akte möglich. Ein Feld mit demselben Namen wird überschrieben.

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

Häufige Abläufe

Vier Muster, die fast jede Anbindung benötigt. Speichern Sie Ihren Schlüssel als CREDIFIN_API_KEY und kopieren Sie die Beispiele.

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" }'

Statuswerte

Die Felder status und substatus in Aktenantworten verwenden die CollectOnline-Namen. dossierClosed ist ein praktischer boolescher Wert für geschlossene und verlorene Akten.

Webhooks

Wählen Sie dossier.status.changed, um Statusänderungen automatisch zu erhalten. data enthält status, substatus, dossierClosed und previous. dossier.uuid identifiziert die Akte und creditor.uuid den Auftraggeber. Verwenden Sie GET /api/dossier/{dossier}/status, um den aktuellen Stand abzurufen.

Webhooks werden asynchron verarbeitet. Verarbeiten Sie jede Ereignis-ID nur einmal und berücksichtigen Sie wiederholte oder verspätete Meldungen. Ein Webhook informiert über eine Änderung; weitere Daten rufen Sie über die dokumentierten API-Routen ab.

Statt regelmäßig abzufragen, lassen Sie Credifin bei Ereignissen in einer Akte eine Nachricht senden. Ein Kundenadministrator fügt unter Anbindungen → Webhooks eine URL hinzu, wählt Ereignisse und erhält einmalig ein Geheimnis zur Prüfung jeder Meldung. Dieselbe Seite zeigt alle Zustellungen mit Inhalt, Versuchen und Wiederholungsschaltfläche. Sie können mehrere Webhooks registrieren, etwa einen pro System. Credifin aktiviert Webhooks je Auftraggeber.

Agenturen. Wenn Sie als Agentur mehrere Kunden betreuen, registrieren Sie einen Webhook für die ganze Agentur. Er empfängt Meldungen aller Kunden, auch später angelegter; keine Einrichtung pro Kunde nötig. Jede Meldung enthält unter creditor die Kundennummer und den Kundennamen und unter agency Ihre Agentur. Nur für Agenturen gibt es außerdem das Ereignis creditor.created: Ein neuer Kunde wurde unter Ihrer Agentur angelegt. Credifin gibt Webhooks pro Agentur frei.

Ereignisse

Die Benachrichtigung

Jede Benachrichtigung ist eine POST mit JSON. dossier ist eine Zusammenfassung der Akte; data hat dieselbe Struktur wie die zugehörige API-Ressource, etwa eine Zahlung bei payment.received. Bei Schuldner- und Kundenereignissen sowie Testmeldungen ist dossier null. creditor nennt den Auftraggeber (UUID, Kundennummer, Name) und agency die zugehörige Agentur oder 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" }
}

Signatur prüfen

HMAC-SHA256 berechnen über <timestamp>.<ruwe body> mit Ihrem Geheimnis und vergleichen Sie mit v1 aus dem Header. Lehnen Sie Meldungen ab, deren Zeitstempel mehr als fünf Minuten abweicht.

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'] ?? ''));
}