De la première clé au premier dossier

Connexion en trois étapes

Credifin fournit le nom, les droits et l’adresse API. La clé reste valide jusqu’à révocation et demeure masquée, mais les utilisateurs autorisés peuvent la copier.

1. 1

   Credifin active la connexion

   Après activation, vous verrez Connexions → API dans le portail client.

2. 2

   L’administrateur client crée la clé

   Cliquez sur Générer une clé API. Le nom et les droits sont préconfigurés ; la clé reste valide jusqu’à révocation.

3. 3

   Copier et valider

   Conservez la clé dans votre gestionnaire de secrets et exécutez le cURL de validation. Le préfixe reste visible ; le secret reste masqué et peut être copié sur demande.

Adresse API

https://crm.credifin.nl

En-tête d’authentification

Api-Key

Route recommandée

POST /api/v1/dossiers

L’adresse API est identique pour tous les clients. La clé associe automatiquement chaque requête au bon client.

Fonctionnement de l’API

Une adresse, un en-tête, du JSON en entrée et en sortie. Tout ce qui suit s’applique à chaque route.

Agences

Les clients et les agences utilisent la même API et la même documentation. Une clé client donne accès à son propre donneur d’ordre. Une clé d’agence couvre les entreprises qui lui sont actuellement rattachées ; une clé de groupe couvre aussi ses propres succursales. L’accès est déterminé à chaque requête.

POST /api/creditor: utilisez creditors:create et Idempotency-Key pour créer une entreprise sous votre propre agence. Utilisez la valeur renvoyée uuid ou reference comme creditor. Cette requête ne crée pas de compte utilisateur.

Si vous gérez plusieurs clients en tant qu’agence, une seule clé couvre toute l’agence. Credifin active l’accès par agence ; l’administrateur crée ensuite la clé sous Connexions → API. Les nouveaux clients de votre agence sont immédiatement couverts par la même clé.

Migration depuis CollectOnline

Migrer en cinq étapes

1. Demandez l’activation. Credifin active l’API pour votre client et associe vos identifiants CollectOnline existants.
2. Créer une clé sous Connexions → API et conservez-la dans votre gestionnaire de secrets. L’ancienne clé CollectOnline ne fonctionne pas ici.
3. Remplacez l’adresse https://credifin.collectonline.eu par https://crm.credifin.nl. Les chemins sous /api/... restent identiques.
4. Effectuer un test de réception: récupérez votre liste de dossiers, consultez un dossier avec /financial et transmettez un dossier de test via POST /api/v1/dossiers/validate.
5. Vérifier les différences dans le tableau ci-dessous et effectuez la migration. Indiquez-nous les routes utilisées afin que nous les vérifiions particulièrement.

Intérêts, historique et avoirs

Ces fonctions sont disponibles pour tous les clients et agences disposant des droits requis. Elles font partie de l’API générale ; il n’existe pas de version propre à un client. Ouvrez la route pour consulter les conditions, les champs et les réponses :

• Définir un montant fixe d’intérêts sur une facture — PUT /api/invoice/{invoice}/interest
• Consulter l’historique des statuts d’un dossier — GET /api/dossier/{dossier}/status/history
• Téléverser un avoir au format PDF — POST /api/creditnote/{creditNote}/attachment

Pour ces trois routes, l’UUID dans le chemin détermine l’entreprise concernée. Une clé d’agence n’a pas besoin d’envoyer un creditor supplémentaire. Les limites d’accès aux dossiers et aux clients restent applicables.

Un UUID CollectOnline associé reste utilisable dans le cadre de vos droits actuels. Une association source manquante ou une ressource hors de votre accès renvoie 404. Une association ambiguë renvoie 409. Signalez alors la route, l’UUID et le X-Request-Id à Credifin ; ne créez pas de dossier de remplacement.

L’historique utilise la date réelle du statut en heure locale néerlandaise. Le passage à lost indique une radiation ; closed signifie une clôture positive. Un historique vide ne prouve aucune date de radiation. Une note historique sans fichier a attachmentName: null ; aucun fichier ne peut alors être téléchargé.

Identités et pièces jointes des avoirs

Les dossiers importés peuvent avoir plusieurs fiches historiques de débiteur pour un même UUID source. La liste et le détail utilisent le même UUID de débiteur stable que la recherche par cet UUID source. Les dossiers existants ne sont pas fusionnés.

Avec un accès agent, le même ancien UUID de débiteur peut exister pour plusieurs clients. Utilisez alors GET /api/debtor/{debtor}?creditor={creditor}. Sans client, la réponse est 409 LEGACY_ID_AMBIGUOUS. L’UUID de debtorUuid peut être consulté directement.

Les avoirs incluent hasAttachment et invoice. Seules les pièces jointes visibles sont comptées. invoice vaut null lorsqu’aucun lien vers une facture n’est enregistré. Le téléchargement exige aussi l’accès aux documents ; les fichiers internes ou bloqués ne sont pas accessibles.

GET /api/creditnote/{creditNote}/attachment

Tester avec un client de test

Les tests utilisent la même adresse API avec un client de test distinct et sa propre clé client. Utilisez uniquement des dossiers fictifs et les coordonnées de test convenues. La clé appartient à ce client et ne donne pas accès au client réel. Il n’y a pas de sandbox séparée.

Demandez à Credifin de créer un client de test distinct. Sélectionnez-le dans Intégrations → API et créez sa propre clé. Une clé d’agence peut couvrir plusieurs entreprises ; ne l’utilisez pas pour limiter un test à une seule entreprise. Les dossiers de test suivent le même traitement que les dossiers ordinaires. Utilisez uniquement un destinataire de test pour les webhooks.

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

Adresses complètes des débiteurs

Pour chaque débiteur, transmettez la rue, le numéro avec son éventuel complément, le code postal, la ville et le pays. Vérifiez ces données pour toutes les entreprises et succursales. Des adresses incomplètes peuvent bloquer le traitement des dossiers.

Lors de la transmission v1, ces champs sont obligatoires dans debtor.address. Un complément peut être indiqué séparément dans houseNumberAddition. Les routes historiques des débiteurs utilisent street, houseNumber (complément inclus), postalCode, city et country au premier niveau. L’acceptation technique de champs omis ne garantit pas une adresse complète.

Complétez une adresse existante avec PUT /api/debtor/{debtor}, dossiers:create et un nouvel Idempotency-Key par modification. Réutilisez la même clé et le même contenu en cas de nouvelle tentative. Une clé d’agence doit aussi transmettre creditor. Relisez ensuite le débiteur pour vérifier les données enregistrées. POST /api/debtor ne met pas à jour un débiteur existant.

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

Les champs omis sont conservés ; null ou une valeur vide efface les champs facultatifs. Une réponse 409 SHARED_DEBTOR signifie qu’aucune modification n’a été faite : coordonnez la mise à jour avec Credifin. Elle s’applique au débiteur identifié, pas automatiquement aux copies historiques distinctes.

Authentification et tentatives sûres

Envoyez la clé API uniquement par HTTPS dans l’en-tête de requête. Ne placez jamais de clés dans une URL, du code navigateur ou un journal d’application.

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

Démarrage rapide : validation sûre

Enregistrez la clé en dehors de l’historique du terminal sous CREDIFIN_API_KEY. Cette route vérifie les mêmes champs que la route de production, sans enregistrer de données ni lancer de procédure.

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

Transmettre des informations complémentaires

Plus le dossier contient d’informations, plus Credifin peut répondre directement aux questions du débiteur.

Vous choisissez vous-même les noms des champs. Utilisez toujours le même nom pour le même type d’information. Vous trouverez des exemples ci-dessous.

Joignez ces champs lors de la transmission, sous forme de liste de noms et de valeurs :

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

Envoyez les documents tels qu’une lettre de résiliation, un e-mail de confirmation (.eml ou .msg) ou un relevé de compte en pièce jointe.

Vous pouvez compléter ou modifier les informations plus tard, par dossier. Un champ portant le même nom est remplacé.

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

Parcours courants

Quatre modèles utiles à presque toutes les connexions. Enregistrez votre clé sous CREDIFIN_API_KEY et copiez les exemples.

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

Statuts

Les champs status et substatus dans les réponses de dossier utilisent les noms CollectOnline. dossierClosed est un booléen utile pour les dossiers clôturés et perdus.

Webhooks

Choisissez dossier.status.changed pour recevoir automatiquement les changements de statut. data contient status, substatus, dossierClosed et previous. dossier.uuid identifie le dossier et creditor.uuid le client. Utilisez GET /api/dossier/{dossier}/status pour consulter l’état actuel.

Les webhooks sont traités de manière asynchrone. Traitez chaque identifiant d’événement une seule fois et prévoyez des notifications répétées ou tardives. Un webhook signale un changement ; les données complémentaires se récupèrent par les routes API documentées.

Au lieu d’interroger régulièrement l’API, laissez Credifin envoyer un message lors d’un événement. Un administrateur client ajoute sous Connexions → Webhooks une URL, choisit les événements et reçoit une fois un secret permettant de vérifier chaque notification. La même page affiche les envois, leur contenu, les tentatives et un bouton de renvoi. Vous pouvez enregistrer plusieurs webhooks, par exemple un par système. Credifin active les webhooks par créancier.

Agences. Si vous gérez plusieurs clients, enregistrez un webhook pour toute l’agence. Il reçoit les notifications de tous les clients, y compris futurs, sans configuration individuelle. Chaque notification contient sous creditor le numéro et le nom du client, et sous agency votre agence. L’événement suivant existe également uniquement pour les agents : creditor.created: un nouveau client a été créé sous votre agence. Credifin active les webhooks par agence.

Événements

La notification

Chaque notification est une POST avec du JSON. dossier est un résumé du dossier ; data a la même structure que la ressource API correspondante, par exemple un paiement pour payment.received. Pour les événements débiteur et client et les notifications de test, dossier est null. creditor identifie le créancier (UUID, numéro client, nom) et agency l’agence dont il dépend, ou 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" }
}

Vérifier la signature

Calculez HMAC-SHA256 sur <timestamp>.<ruwe body> avec votre secret et comparez avec v1 depuis l’en-tête. Rejetez les notifications dont l’horodatage diffère de plus de cinq minutes.

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