Débiteurs - Finkare API

Tester en direct — Essayez ces endpoints dans la documentation interactive Scalar.

Lister les débiteurs

Scope requis : debtors:read

string

Recherche textuelle (nom, email, SIRET)

number

default:"1"

Numéro de page

number

default:"20"

Résultats par page (max 100)

curl -H "X-API-Key: fk_live_xxx" \
  "https://api.finkare.io/api/v1/debtors?search=Dupont&limit=20"

const debtors = await finkare.debtors.list({ search: 'Dupont', limit: '20' });

{
  "success": true,
  "data": [
    {
      "id": "b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c",
      "name": "Dupont & Fils SARL",
      "email": "comptabilite@dupont-fils.fr",
      "phone": "+33145678901",
      "siret": "44306184100047",
      "address": "12 rue de la Paix",
      "city": "Paris",
      "postalCode": "75002",
      "country": "FR",
      "createdAt": "2026-02-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "requestId": "req_d1e2f3",
  "timestamp": "2026-04-08T10:00:00Z"
}

Récupérer un débiteur

Scope requis : debtors:read

string

required

ID du débiteur (UUID)

curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/debtors/b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c

Créer un débiteur

Scope requis : debtors:write

string

required

Nom ou raison sociale (max 200 caractères). Exemple : Dupont & Fils SARL

string

required

Email de contact principal

string

Numéro de téléphone (format international). Exemple : +33145678901

string

Numéro SIRET (14 chiffres)

string

Adresse postale

string

Ville

string

Code postal

string

default:"FR"

Code pays ISO 3166-1 alpha-2

string

Notes internes (non visibles par le débiteur)

curl -X POST https://api.finkare.io/api/v1/debtors \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bernard Technologies SAS",
    "email": "tresorerie@bernard-tech.fr",
    "phone": "+33156789012",
    "siret": "91234567800034",
    "address": "8 rue de Rivoli",
    "city": "Lyon",
    "postalCode": "69001",
    "notes": "Contact principal : M. Bernard (DG)"
  }'

const debtor = await finkare.debtors.list(); // SDK create via invoice debtor field

Codes d’erreur possibles

Code	HTTP	Description
`VAL_001`	400	Données invalides (email, SIRET)
`AUTH_004`	403	Scope `debtors:write` requis

Mettre à jour un débiteur

Scope requis : debtors:write

string

required

ID du débiteur (UUID)

Mêmes champs que la création. Tous les champs sont modifiables.

curl -X PUT https://api.finkare.io/api/v1/debtors/b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+33698765432",
    "notes": "Nouveau contact : Mme Dupont (DAF)"
  }'

Factures d’un débiteur

Récupère toutes les factures associées à un débiteur. Scopes requis : debtors:read + invoices:read

string

required

ID du débiteur (UUID)

curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/debtors/b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c/invoices

{
  "success": true,
  "data": [
    {
      "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
      "invoiceNumber": "FAC-2026-001",
      "amountCents": 150000,
      "status": "in_recovery",
      "dueDate": "2026-03-31"
    },
    {
      "id": "d4e5f6a7-b1c2-8901-def0-234567890abc",
      "invoiceNumber": "FAC-2026-015",
      "amountCents": 85000,
      "status": "paid",
      "dueDate": "2026-02-28"
    }
  ],
  "requestId": "req_g4h5i6",
  "timestamp": "2026-04-08T10:00:00Z"
}

Score de risque

Récupère le score de risque calculé par l’IA (13 critères comportementaux, score 0-195). Scope requis : debtors:read

string

required

ID du débiteur (UUID)

curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/debtors/b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c/score

{
  "success": true,
  "data": {
    "debtorId": "b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c",
    "score": 72,
    "riskLevel": "medium",
    "factors": [
      "Historique de paiement irrégulier",
      "Ancienneté du compte > 2 ans"
    ],
    "lastUpdated": "2026-03-15T08:30:00Z"
  },
  "requestId": "req_a1b2c3d4",
  "timestamp": "2026-04-08T10:00:00Z"
}

number

Score de 0 à 195. Plus le score est élevé, plus le risque est élevé.

string

Niveau de risque : low (0-50), medium (51-100), high (101-150), critical (151-195)

array

Facteurs explicatifs du score (conformité AI Act — explicabilité)

Le score est recalculé automatiquement à chaque interaction significative (paiement, réponse, contestation). Les facteurs explicatifs respectent les exigences de l’AI Act (système high-risk).

​Lister les débiteurs

​Récupérer un débiteur

​Créer un débiteur

​Codes d’erreur possibles

​Mettre à jour un débiteur

​Factures d’un débiteur

​Score de risque

Lister les débiteurs

Récupérer un débiteur

Créer un débiteur

Codes d’erreur possibles

Mettre à jour un débiteur

Factures d’un débiteur

Score de risque