Skip to main content
Tester en direct — Essayez ces endpoints dans la documentation interactive Scalar.

​
Lister les factures

​
status
string
Filtrer par statut : draft, imported, lrar_sent, in_recovery, paid, partial, disputed, written_off, judicial
​
debtorId
string
Filtrer par ID du débiteur (UUID)
​
fromDate
string
Date de début d’émission (ISO 8601). Exemple : 2026-01-01
​
toDate
string
Date de fin d’émission (ISO 8601). Exemple : 2026-03-31
​
minAmount
number
Montant minimum en centimes
​
maxAmount
number
Montant maximum en centimes
​
search
string
Recherche textuelle (numéro de facture, nom du débiteur)
​
page
number
default:"1"
Numéro de page
​
limit
number
default:"20"
Résultats par page (max 100)
​
sortBy
string
default:"created_at"
Champ de tri : created_at, due_date, amount_cents, status
​
sortOrder
string
default:"desc"
Ordre : asc ou desc
Scope requis : invoices:read 
curl -H "X-API-Key: fk_live_xxx" \
  "https://api.finkare.io/api/v1/invoices?status=in_recovery&page=1&limit=20"

​
Récupérer une facture

​
id
string
required
ID de la facture (UUID)
Scope requis : invoices:read 
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/invoices/c3d4e5f6-a1b2-7890-cdef-1234567890ab

​
Créer une facture

Crée une nouvelle facture et démarre automatiquement le workflow de recouvrement. Scope requis : invoices:write
​
invoiceNumber
string
required
Numéro de facture unique. Exemple : FAC-2026-001
​
amountCents
number
required
Montant total TTC en centimes. Exemple : 150000 (1 500,00 EUR)
​
currency
string
default:"EUR"
Devise ISO 4217
​
issueDate
string
required
Date d’émission (ISO 8601). Exemple : 2026-03-01
​
dueDate
string
required
Date d’échéance (ISO 8601). Exemple : 2026-03-31
​
description
string
Description de la facture (max 500 caractères)
​
debtor
object
required
Informations du débiteur
​
metadata
object
Données personnalisées (clé-valeur)
curl -X POST https://api.finkare.io/api/v1/invoices \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-fac-2026-042" \
  -d '{
    "invoiceNumber": "FAC-2026-042",
    "amountCents": 285000,
    "issueDate": "2026-02-15",
    "dueDate": "2026-03-15",
    "description": "Audit de conformité RGPD - Février 2026",
    "debtor": {
      "name": "Martin Consulting SAS",
      "email": "direction@martin-consulting.fr",
      "phone": "+33678901234",
      "siret": "83965478200012",
      "address": "45 avenue des Champs-Élysées",
      "city": "Paris",
      "postalCode": "75008"
    },
    "metadata": {
      "erp_ref": "ERP-2026-042",
      "department": "juridique"
    }
  }'
​
data
object

​
Codes d’erreur possibles

CodeHTTPDescription
VAL_001400Données invalides
VAL_003400Champ obligatoire manquant
AUTH_004403Scope invoices:write requis
RATE_001429Rate limit dépassé

​
Import en masse

Importe jusqu’à 100 factures en une seule requête. Scopes requis : invoices:write
​
invoices
array
required
Tableau de factures (même format que la création unitaire, max 100)
​
autoStartWorkflow
boolean
default:"true"
Démarrer automatiquement le workflow pour chaque facture
curl -X POST https://api.finkare.io/api/v1/invoices/bulk \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bulk-import-2026-04-08" \
  -d '{
    "invoices": [
      {
        "invoiceNumber": "FAC-2026-100",
        "amountCents": 75000,
        "issueDate": "2026-03-01",
        "dueDate": "2026-04-01",
        "debtor": {
          "name": "Lefebvre SARL",
          "email": "compta@lefebvre.fr"
        }
      },
      {
        "invoiceNumber": "FAC-2026-101",
        "amountCents": 320000,
        "issueDate": "2026-03-15",
        "dueDate": "2026-04-15",
        "debtor": {
          "name": "Moreau Industries SA",
          "email": "finance@moreau-industries.fr",
          "siret": "75234567800019"
        }
      }
    ],
    "autoStartWorkflow": true
  }'
Le body size maximum est de 10 Mo pour l’import en masse (vs 1 Mo pour les autres endpoints).

​
Mettre à jour une facture

Met à jour les metadata et notes uniquement. Les données financières (montant, dates, débiteur) sont immuables après import. Scope requis : invoices:write
​
id
string
required
ID de la facture (UUID)
​
notes
string
Notes internes (max 2000 caractères)
​
metadata
object
Données personnalisées
curl -X PUT https://api.finkare.io/api/v1/invoices/c3d4e5f6-a1b2-7890-cdef-1234567890ab \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Relance téléphonique effectuée le 08/04/2026 — débiteur absent",
    "metadata": { "priority": "high" }
  }'
Les champs amount, invoiceNumber, issueDate, dueDate, currency et debtor ne peuvent pas être modifiés. Toute tentative retourne une erreur FORBIDDEN_FIELD_MODIFICATION.

​
Annuler un recouvrement

Annule complètement le workflow de recouvrement : arrêt des relances planifiées, annulation des emails/SMS/LRAR en attente, mise à jour du statut. Scopes requis : invoices:write + workflow:trigger
​
id
string
required
ID de la facture (UUID)
​
reason
string
required
Motif d’annulation (max 500 caractères)
​
notifyDebtor
boolean
default:"false"
Notifier le débiteur par email de l’annulation
curl -X POST https://api.finkare.io/api/v1/invoices/c3d4e5f6-a1b2-7890-cdef-1234567890ab/cancel \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Paiement reçu directement sur notre compte bancaire",
    "notifyDebtor": false
  }'

{
  "success": true,
  "data": {
    "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "reference": "FAC-2026-001",
    "previousStatus": "in_recovery",
    "newStatus": "cancelled",
    "cancelledAt": "2026-04-08T15:30:00Z",
    "summary": {
      "actionsCancelled": 5,
      "voiceCallsCancelled": 1,
      "debtorNotified": false
    }
  }
}

​
Supprimer une facture

Supprime une facture uniquement si le workflow n’est pas encore lancé. Scope requis : invoices:delete 
curl -X DELETE https://api.finkare.io/api/v1/invoices/c3d4e5f6-a1b2-7890-cdef-1234567890ab \
  -H "X-API-Key: fk_live_xxx"
Retourne 204 No Content en cas de succès.
Si le workflow est déjà lancé, utilisez POST /v1/invoices/:id/cancel à la place.

​
Statistiques

Récupère un résumé statistique de vos factures. Scope requis : reports:read 
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/invoices/stats/summary

{
  "success": true,
  "data": {
    "totalInvoices": 342,
    "totalAmountCents": 4850000,
    "byStatus": {
      "in_recovery": 45,
      "paid": 280,
      "partial": 12,
      "disputed": 5
    },
    "recoveryRate": 87.4
  }
}