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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.