Skip to main content
Testez les endpoints en direct — Notre documentation interactive Scalar vous permet d’executer des requetes en temps reel depuis votre navigateur.

​
Base URL

EnvironnementURL
Productionhttps://api.finkare.io
Sandboxhttps://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

{
  "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

Les endpoints de liste retournent un objet 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 '{ ... }'
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

CodeDescription
AUTH_001API key manquante dans le header X-API-Key
AUTH_002API key invalide
AUTH_003Token expiré (OAuth)
AUTH_004Scope insuffisant pour cette action
AUTH_005IP non autorisée (whitelist)
AUTH_006Client API désactivé
AUTH_007Action réservée à la production

​
Rate Limiting

CodeDescription
RATE_001Limite par minute dépassée
RATE_002Quota journalier épuisé
RATE_003Trop de requêtes simultanées

​
Validation

CodeDescription
VAL_001Validation des données échouée
VAL_002Valeur de paramètre invalide
VAL_003Champ obligatoire manquant
VAL_004Format de données invalide
VAL_005Payload trop volumineux

​
Ressources

CodeDescription
RES_001Ressource non trouvée
RES_002Ressource déjà existante
RES_003Conflit sur la ressource
RES_004Ressource verrouillée

​
Logique métier

CodeDescription
BIZ_001Facture déjà payée
BIZ_002Workflow déjà démarré
BIZ_003Débiteur non trouvé
BIZ_004Transition de statut invalide

​
Webhooks

CodeDescription
WH_001Livraison du webhook échouée
WH_002URL de webhook invalide
WH_003Signature de webhook invalide

​
Système

CodeDescription
SVC_001Service temporairement indisponible
SVC_002Timeout du service
SVC_003Erreur interne du service
SYS_001Erreur interne
SYS_002Mode maintenance
SYS_003Endpoint déprécié

​
Headers de requête

HeaderObligatoireDescription
X-API-KeyOui*Clé API Finkare
AuthorizationOui*Bearer token OAuth 2.1
Content-TypeOui (POST/PUT)application/json
Idempotency-KeyNonClé d’idempotence (POST uniquement)
X-Request-IdNonID de requête personnalisé
*L’un des deux est requis.

​
Headers de réponse

HeaderDescription
X-Request-IdIdentifiant unique de la requête
X-RateLimit-LimitLimite par minute
X-RateLimit-RemainingRequêtes restantes
X-RateLimit-ResetTimestamp de réinitialisation
X-RateLimit-Daily-RemainingRequêtes restantes (jour)
Retry-AfterDélai en secondes avant retry (429)

​
Endpoints disponibles

GroupeBase pathEndpointsDescription
Invoices/api/v1/invoices7Gestion des factures
Debtors/api/v1/debtors6Gestion des débiteurs
Payments/api/v1/payments4Consultation des paiements
Workflow/api/v1/workflow5Pilotage du workflow IA
Webhooks/api/v1/webhooks9Configuration des webhooks
Agent/api/v2/agent3Assistant IA Bob
API Keys/api/v1/api-keys4Gestion des clés API
OAuth/api/oauth5Authentification OAuth 2.1