Vue d'ensemble - Finkare API

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

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

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

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

​Base URL

​Format des réponses

​Succès

​Erreur

​Pagination

​Idempotence

​Codes d’erreur

​Authentification

​Rate Limiting

​Validation

​Ressources

​Logique métier

​Webhooks

​Système

​Headers de requête

​Headers de réponse

​Endpoints disponibles

Base URL

Format des réponses

Succès

Erreur

Pagination

Idempotence

Codes d’erreur

Authentification

Rate Limiting

Validation

Ressources

Logique métier

Webhooks

Système

Headers de requête

Headers de réponse

Endpoints disponibles