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.
Base URL
| Environnement | URL |
|---|
| Production | https://api.finkare.io |
| Sandbox | https://api-sandbox.finkare.io |
/api/v1/ (ou /api/v2/ pour les endpoints Agent).
Toutes les réponses suivent un format standardisé :
Succès
{
"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
{
"success": false,
"error": {
"code": "AUTH_002",
"message": "Invalid API key. Please check your credentials."
},
"requestId": "req_abc123",
"timestamp": "2026-04-08T10:30:00Z"
}
pagination :
{
"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 :
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 '{ ... }'
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é |
| 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é |
| 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 |
