> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Débiteurs

> Gestion des débiteurs : création, mise à jour, consultation du score de solvabilité IA et des factures associées.

<Info>**Tester en direct** — Essayez ces endpoints dans la [documentation interactive Scalar](https://api.finkare.io/docs).</Info>

## Lister les débiteurs

**Scope requis :** `debtors:read`

<ParamField query="search" type="string" optional>
  Recherche textuelle (nom, email, SIRET)
</ParamField>

<ParamField query="page" type="number" optional default="1">
  Numéro de page
</ParamField>

<ParamField query="limit" type="number" optional default="20">
  Résultats par page (max 100)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: fk_live_xxx" \
    "https://api.finkare.io/api/v1/debtors?search=Dupont&limit=20"
  ```

  ```typescript SDK theme={null}
  const debtors = await finkare.debtors.list({ search: 'Dupont', limit: '20' });
  ```
</CodeGroup>

```json theme={null}
{
  "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`

<ParamField path="id" type="string" required>
  ID du débiteur (UUID)
</ParamField>

```bash theme={null}
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`

<ParamField body="name" type="string" required>
  Nom ou raison sociale (max 200 caractères). Exemple : `Dupont & Fils SARL`
</ParamField>

<ParamField body="email" type="string" required>
  Email de contact principal
</ParamField>

<ParamField body="phone" type="string" optional>
  Numéro de téléphone (format international). Exemple : `+33145678901`
</ParamField>

<ParamField body="siret" type="string" optional>
  Numéro SIRET (14 chiffres)
</ParamField>

<ParamField body="address" type="string" optional>
  Adresse postale
</ParamField>

<ParamField body="city" type="string" optional>
  Ville
</ParamField>

<ParamField body="postalCode" type="string" optional>
  Code postal
</ParamField>

<ParamField body="country" type="string" optional default="FR">
  Code pays ISO 3166-1 alpha-2
</ParamField>

<ParamField body="notes" type="string" optional>
  Notes internes (non visibles par le débiteur)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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)"
    }'
  ```

  ```typescript SDK theme={null}
  const debtor = await finkare.debtors.list(); // SDK create via invoice debtor field
  ```
</CodeGroup>

### 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`

<ParamField path="id" type="string" required>
  ID du débiteur (UUID)
</ParamField>

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

```bash theme={null}
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`

<ParamField path="id" type="string" required>
  ID du débiteur (UUID)
</ParamField>

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

```json theme={null}
{
  "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`

<ParamField path="id" type="string" required>
  ID du débiteur (UUID)
</ParamField>

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

```json theme={null}
{
  "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"
}
```

<ResponseField name="data.score" type="number">
  Score de 0 à 195. Plus le score est élevé, plus le risque est élevé.
</ResponseField>

<ResponseField name="data.riskLevel" type="string">
  Niveau de risque : `low` (0-50), `medium` (51-100), `high` (101-150), `critical` (151-195)
</ResponseField>

<ResponseField name="data.factors" type="array">
  Facteurs explicatifs du score (conformité AI Act — explicabilité)
</ResponseField>

<Note>
  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).
</Note>