Quickstart

Vous preferez explorer l’API visuellement ? Ouvrez la documentation interactive Scalar pour tester les endpoints en direct.

Pré-requis

Un compte Finkare avec accès API (contactez-nous)
Une clé API (préfixe fk_test_ pour le sandbox, fk_live_ pour la production)

Étape 1 — Vérifier votre clé API

Testez la connexion avec le endpoint de santé :

curl -H "X-API-Key: fk_test_votre_cle_ici" \
  https://api-sandbox.finkare.io/health

import { FinkareClient } from '@finkare/api-sdk';

const finkare = new FinkareClient('fk_test_votre_cle_ici', {
  baseUrl: 'https://api-sandbox.finkare.io',
});

Réponse attendue :

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-04-08T10:00:00Z"
}

Étape 2 — Créer une facture

Importez votre première facture avec les informations du débiteur :

curl -X POST https://api-sandbox.finkare.io/api/v1/invoices \
  -H "X-API-Key: fk_test_votre_cle_ici" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-facture-001" \
  -d '{
    "invoiceNumber": "FAC-2026-001",
    "amountCents": 150000,
    "currency": "EUR",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "description": "Prestation de conseil - Mars 2026",
    "debtor": {
      "name": "Dupont & Fils SARL",
      "email": "comptabilite@dupont-fils.fr",
      "phone": "+33145678901",
      "siret": "44306184100047",
      "address": "12 rue de la Paix",
      "city": "Paris",
      "postalCode": "75002",
      "country": "FR"
    }
  }'

const invoice = await finkare.invoices.create({
  invoiceNumber: 'FAC-2026-001',
  amount: 150000,
  currency: 'EUR',
  issueDate: '2026-03-01',
  dueDate: '2026-03-31',
  debtor: {
    name: 'Dupont & Fils SARL',
    email: 'comptabilite@dupont-fils.fr',
    phone: '+33145678901',
    siret: '44306184100047',
    address: '12 rue de la Paix',
    city: 'Paris',
    postalCode: '75002',
    country: 'FR',
  },
});

console.log(invoice.data.id); // UUID de la facture créée

Réponse :

{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "invoiceNumber": "FAC-2026-001",
    "amountCents": 150000,
    "currency": "EUR",
    "status": "imported",
    "workflowStarted": true,
    "createdAt": "2026-04-08T10:00:00Z"
  },
  "requestId": "req_abc123",
  "timestamp": "2026-04-08T10:00:00Z"
}

Le workflow de recouvrement démarre automatiquement à la création. L’IA analyse le profil du débiteur et planifie la cascade de relances optimale.

Étape 3 — Suivre le workflow

Consultez l’état du recouvrement :

curl -H "X-API-Key: fk_test_votre_cle_ici" \
  https://api-sandbox.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab

const status = await finkare.workflow.getStatus(
  'c3d4e5f6-a1b2-7890-cdef-1234567890ab'
);
console.log(status.data.currentStep); // ex: "relance_email_1"

Réponse :

{
  "success": true,
  "data": {
    "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "status": "in_recovery",
    "currentStep": "relance_email_1",
    "startedAt": "2026-04-08T10:00:00Z",
    "actionsCompleted": 1,
    "nextActionAt": "2026-04-11T08:00:00Z"
  },
  "requestId": "req_def456",
  "timestamp": "2026-04-08T10:05:00Z"
}

Étape 4 — Configurer un webhook

Recevez les notifications en temps réel :

curl -X POST https://api-sandbox.finkare.io/api/v1/webhooks \
  -H "X-API-Key: fk_test_votre_cle_ici" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-serveur.com/webhooks/finkare",
    "events": ["payment.received", "invoice.status_changed", "workflow.action_triggered"],
    "description": "Webhook principal"
  }'

const webhook = await finkare.webhooks.create({
  url: 'https://votre-serveur.com/webhooks/finkare',
  events: ['payment.received', 'invoice.status_changed', 'workflow.action_triggered'],
  description: 'Webhook principal',
});

// Sauvegardez le secret — il ne sera plus affiché
console.log(webhook.data.secret); // whsec_a1b2c3d4e5f6...

Le secret de signature est retourné une seule fois à la création. Sauvegardez-le immédiatement dans vos variables d’environnement.

Et ensuite ?

Authentification

API Key vs OAuth 2.1, scopes, rate limiting

Import en masse

Importer 50+ factures depuis votre ERP

Webhooks avancés

Vérification HMAC, retry, événements

SDK TypeScript

Installation, configuration, pagination

Get Started

Changelog

Pré-requis

Étape 1 — Vérifier votre clé API

Étape 2 — Créer une facture

Étape 3 — Suivre le workflow

Étape 4 — Configurer un webhook

Et ensuite ?

Authentification

Import en masse

Webhooks avancés

SDK TypeScript

​Pré-requis

​Étape 1 — Vérifier votre clé API

​Étape 2 — Créer une facture

​Étape 3 — Suivre le workflow

​Étape 4 — Configurer un webhook

​Et ensuite ?

Authentification

Import en masse

Webhooks avancés

SDK TypeScript

Pré-requis

Étape 1 — Vérifier votre clé API

Étape 2 — Créer une facture

Étape 3 — Suivre le workflow

Étape 4 — Configurer un webhook

Et ensuite ?