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

# Vue d'ensemble

> Architecture, conventions et format des réponses de l'API Finkare.

<Tip>
  **Testez les endpoints en direct** — Notre [documentation interactive Scalar](https://api.finkare.io/docs) vous permet d'executer des requetes en temps reel depuis votre navigateur.
</Tip>

## Base URL

| Environnement  | URL                              |
| -------------- | -------------------------------- |
| **Production** | `https://api.finkare.io`         |
| **Sandbox**    | `https://api-sandbox.finkare.io` |

Tous les endpoints de l'API sont préfixés par `/api/v1/` (ou `/api/v2/` pour les endpoints Agent).

## Format des réponses

Toutes les réponses suivent un format standardisé :

### Succès

```json theme={null}
{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "invoiceNumber": "FAC-2026-001",
    "amountCents": 150000,
    "status": "imported"
  },
  "requestId": "req_abc123",
  "timestamp": "2026-04-08T10:30:00Z"
}
```

### Erreur

```json theme={null}
{
  "success": false,
  "error": {
    "code": "AUTH_002",
    "message": "Invalid API key. Please check your credentials."
  },
  "requestId": "req_abc123",
  "timestamp": "2026-04-08T10:30:00Z"
}
```

### Pagination

Les endpoints de liste retournent un objet `pagination` :

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 342,
    "totalPages": 18,
    "hasNext": true,
    "hasPrev": false
  },
  "requestId": "req_xyz789",
  "timestamp": "2026-04-08T10:30:00Z"
}
```

## Idempotence

Les endpoints de création (`POST`) supportent le header `Idempotency-Key` pour éviter les doublons en cas de retry réseau :

```bash theme={null}
curl -X POST https://api.finkare.io/api/v1/invoices \
  -H "X-API-Key: fk_live_xxx" \
  -H "Idempotency-Key: import-fac-2026-001" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Si une requête avec le même `Idempotency-Key` est rejouée, l'API retourne la réponse originale sans re-traiter.

## Codes d'erreur

### Authentification

| Code       | Description                                  |
| ---------- | -------------------------------------------- |
| `AUTH_001` | API key manquante dans le header `X-API-Key` |
| `AUTH_002` | API key invalide                             |
| `AUTH_003` | Token expiré (OAuth)                         |
| `AUTH_004` | Scope insuffisant pour cette action          |
| `AUTH_005` | IP non autorisée (whitelist)                 |
| `AUTH_006` | Client API désactivé                         |
| `AUTH_007` | Action réservée à la production              |

### Rate Limiting

| Code       | Description                  |
| ---------- | ---------------------------- |
| `RATE_001` | Limite par minute dépassée   |
| `RATE_002` | Quota journalier épuisé      |
| `RATE_003` | Trop de requêtes simultanées |

### Validation

| Code      | Description                    |
| --------- | ------------------------------ |
| `VAL_001` | Validation des données échouée |
| `VAL_002` | Valeur de paramètre invalide   |
| `VAL_003` | Champ obligatoire manquant     |
| `VAL_004` | Format de données invalide     |
| `VAL_005` | Payload trop volumineux        |

### Ressources

| Code      | Description              |
| --------- | ------------------------ |
| `RES_001` | Ressource non trouvée    |
| `RES_002` | Ressource déjà existante |
| `RES_003` | Conflit sur la ressource |
| `RES_004` | Ressource verrouillée    |

### Logique métier

| Code      | Description                   |
| --------- | ----------------------------- |
| `BIZ_001` | Facture déjà payée            |
| `BIZ_002` | Workflow déjà démarré         |
| `BIZ_003` | Débiteur non trouvé           |
| `BIZ_004` | Transition de statut invalide |

### Webhooks

| Code     | Description                   |
| -------- | ----------------------------- |
| `WH_001` | Livraison du webhook échouée  |
| `WH_002` | URL de webhook invalide       |
| `WH_003` | Signature de webhook invalide |

### Système

| Code      | Description                         |
| --------- | ----------------------------------- |
| `SVC_001` | Service temporairement indisponible |
| `SVC_002` | Timeout du service                  |
| `SVC_003` | Erreur interne du service           |
| `SYS_001` | Erreur interne                      |
| `SYS_002` | Mode maintenance                    |
| `SYS_003` | Endpoint déprécié                   |

## Headers de requête

| Header            | Obligatoire    | Description                         |
| ----------------- | -------------- | ----------------------------------- |
| `X-API-Key`       | Oui\*          | Clé API Finkare                     |
| `Authorization`   | Oui\*          | Bearer token OAuth 2.1              |
| `Content-Type`    | Oui (POST/PUT) | `application/json`                  |
| `Idempotency-Key` | Non            | Clé d'idempotence (POST uniquement) |
| `X-Request-Id`    | Non            | ID de requête personnalisé          |

\*L'un des deux est requis.

## Headers de réponse

| Header                        | Description                         |
| ----------------------------- | ----------------------------------- |
| `X-Request-Id`                | Identifiant unique de la requête    |
| `X-RateLimit-Limit`           | Limite par minute                   |
| `X-RateLimit-Remaining`       | Requêtes restantes                  |
| `X-RateLimit-Reset`           | Timestamp de réinitialisation       |
| `X-RateLimit-Daily-Remaining` | Requêtes restantes (jour)           |
| `Retry-After`                 | Délai en secondes avant retry (429) |

## Endpoints disponibles

| Groupe       | Base path          | Endpoints | Description                |
| ------------ | ------------------ | --------- | -------------------------- |
| **Invoices** | `/api/v1/invoices` | 8         | Gestion des factures       |
| **Debtors**  | `/api/v1/debtors`  | 6         | Gestion des débiteurs      |
| **Payments** | `/api/v1/payments` | 4         | Consultation des paiements |
| **Workflow** | `/api/v1/workflow` | 5         | Pilotage du workflow IA    |
| **Webhooks** | `/api/v1/webhooks` | 8         | Configuration des webhooks |
| **Agent**    | `/api/v2/agent`    | 3         | Assistant IA Bob           |
| **API Keys** | `/api/v1/api-keys` | 4         | Gestion des clés API       |
| **OAuth**    | `/api/oauth`       | 5         | Authentification OAuth 2.1 |