Skip to main content

​
Vue d’ensemble

L’API Finkare supporte deux méthodes d’authentification :
MéthodeUsageComplexité
API KeyIntégrations serveur-à-serveur (M2M)Simple
OAuth 2.1Applications tierces, flux utilisateurAvancé

​
API Key

Méthode recommandée pour les intégrations backend. Incluez votre clé dans le header X-API-Key : 
curl -H "X-API-Key: fk_live_abc123def456ghi789jkl012mno345" \
  https://api.finkare.io/api/v1/invoices

​
Préfixes

PréfixeEnvironnementDescription
fk_live_ProductionActions réelles (envois email, SMS, LRAR)
fk_test_SandboxAucune action réelle, données de test

​
Gestion des clés

EndpointMéthodeDescriptionScope requis
POST /api/v1/api-keysCréerGénère une nouvelle clé (retournée une seule fois)webhooks:manage
GET /api/v1/api-keysListerListe les clés masquéeswebhooks:manage
POST /api/v1/api-keys/:id/rotateRotationGénère une nouvelle clé, désactive l’anciennewebhooks:manage
DELETE /api/v1/api-keys/:idRévoquerDésactive une clé (soft delete)webhooks:manage
La clé API est affichée une seule fois à la création. Stockez-la dans un gestionnaire de secrets (AWS Secrets Manager, HashiCorp Vault, etc.). Ne la commitez jamais dans votre code source.

​
Exemple de rotation

curl -X POST https://api.finkare.io/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate \
  -H "X-API-Key: fk_live_votre_cle_admin"

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "apiKey": "fk_live_nouveau_secret_genere_ici_abc",
    "prefix": "fk_live_nouv...e_abc"
  },
  "message": "Key rotated. Save the new key — it will not be shown again."
}

​
OAuth 2.1

Pour les applications tierces qui agissent au nom d’un utilisateur Finkare. Trois grant types supportés :

​
Client Credentials (M2M)

Authentification serveur-à-serveur sans intervention utilisateur. 
curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "fk_client_abc123",
    "client_secret": "fk_secret_xyz789",
    "scope": "invoices:read payments:read workflow:read"
  }'
Réponse : 
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:read payments:read workflow:read"
}
Utilisez ensuite le token Bearer : 
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.finkare.io/api/v1/invoices

​
Authorization Code + PKCE

Pour les applications qui nécessitent le consentement de l’utilisateur. Seule la méthode PKCE S256 est supportée (conformité OAuth 2.1).
1

Générer le code challenge

import crypto from 'crypto';

const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');
2

Rediriger vers l'écran de consentement

GET https://api.finkare.io/api/oauth/authorize
  ?response_type=code
  &client_id=fk_client_abc123
  &redirect_uri=https://votre-app.com/callback
  &scope=invoices:read+payments:read
  &state=random_state_string
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
3

Échanger le code contre un token

curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "fk_client_abc123",
    "client_secret": "fk_secret_xyz789",
    "code": "auth_code_recu_dans_callback",
    "redirect_uri": "https://votre-app.com/callback",
    "code_verifier": "le_code_verifier_original"
  }'

​
Refresh Token

Renouvelez un access token expiré sans redemander le consentement : 
curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "fk_client_abc123",
    "refresh_token": "fk_rt_abc123xyz789"
  }'

​
Révocation et introspection

EndpointDescription
POST /api/oauth/revokeRévoque un token (RFC 7009, idempotent)
POST /api/oauth/introspectVérifie la validité d’un token (RFC 7662)

​
Scopes

Chaque clé API ou token OAuth est associé à un ensemble de scopes qui définissent les permissions :
ScopeDescription
invoices:readLire les factures et leurs statuts
invoices:writeCréer et mettre à jour des factures
invoices:deleteSupprimer des factures (avant lancement workflow)
debtors:readLire les informations des débiteurs
debtors:writeCréer et mettre à jour des débiteurs
payments:readConsulter les paiements reçus
payments:writeGérer les paiements
workflow:readConsulter le statut et l’historique des workflows
workflow:triggerDéclencher des actions (start, pause, resume, escalate)
webhooks:manageGérer les webhooks et les clés API
reports:readAccéder aux statistiques et rapports
agent:chatInteragir avec l’assistant IA Bob
lrar:sendDéclencher l’envoi de LRAR
notifications:sendEnvoyer des notifications (email, SMS)
scoring:readConsulter les scores de solvabilité IA
Appliquez le principe du moindre privilège : n’attribuez que les scopes strictement nécessaires à votre intégration.

​
Rate Limiting

Les limites varient selon votre tier de souscription :
TierRequêtes/minRequêtes/jourImport en masse
Starter6010 000100 factures/requête
Pro300100 000100 factures/requête
Enterprise1 000+Illimité100 factures/requête

​
Headers de réponse

Chaque réponse inclut les headers de rate limiting :
HeaderDescription
X-RateLimit-LimitLimite par minute pour votre tier
X-RateLimit-RemainingRequêtes restantes dans la fenêtre
X-RateLimit-ResetTimestamp UNIX de réinitialisation
X-RateLimit-Daily-RemainingRequêtes restantes pour la journée
Retry-AfterSecondes à attendre (si code 429)

​
Gestion du rate limiting

// Le SDK gère automatiquement le retry sur 429
const finkare = new FinkareClient('fk_live_xxx', {
  maxRetries: 3, // Retry jusqu'à 3 fois avec backoff exponentiel
});
En cas de dépassement (429 Too Many Requests), attendez le nombre de secondes indiqué par le header Retry-After avant de retenter.

​
Sécurité

  • HTTPS obligatoire : toutes les requêtes doivent utiliser HTTPS
  • IP Whitelist : restreignez l’accès à vos IPs de production
  • Rotation régulière : faites tourner vos clés tous les 90 jours
  • Idempotency-Key : utilisez le header Idempotency-Key sur les POST pour éviter les doublons en cas de retry réseau
  • X-Request-Id : chaque réponse contient un ID unique pour le support