Factures - Finkare API

Tester en direct — Essayez ces endpoints dans la documentation interactive Scalar.

Lister les factures

string

Filtrer par statut : draft, imported, lrar_sent, in_recovery, paid, partial, disputed, written_off, judicial

string

Filtrer par ID du débiteur (UUID)

string

Date de début d’émission (ISO 8601). Exemple : 2026-01-01

string

Date de fin d’émission (ISO 8601). Exemple : 2026-03-31

number

Montant minimum en centimes

number

Montant maximum en centimes

string

Recherche textuelle (numéro de facture, nom du débiteur)

number

default:"1"

Numéro de page

number

default:"20"

Résultats par page (max 100)

string

default:"created_at"

Champ de tri : created_at, due_date, amount_cents, status

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"

const invoices = await finkare.invoices.list({
  status: 'in_recovery',
  page: '1',
  limit: '20',
});

Récupérer une facture

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

const invoice = await finkare.invoices.get('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

string

required

Numéro de facture unique. Exemple : FAC-2026-001

number

required

Montant total TTC en centimes. Exemple : 150000 (1 500,00 EUR)

string

default:"EUR"

Devise ISO 4217

string

required

Date d’émission (ISO 8601). Exemple : 2026-03-01

string

required

Date d’échéance (ISO 8601). Exemple : 2026-03-31

string

Description de la facture (max 500 caractères)

object

required

Informations du débiteur

Show Propriétés

string

required

Nom ou raison sociale. Exemple : Dupont & Fils SARL

string

required

Email de contact principal

string

Téléphone (format international). Exemple : +33612345678

string

Numéro SIRET (14 chiffres)

string

Adresse postale

string

Ville

string

Code postal

string

default:"FR"

Code pays ISO 3166-1 alpha-2

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"
    }
  }'

const invoice = await finkare.invoices.create({
  invoiceNumber: 'FAC-2026-042',
  amount: 285000,
  issueDate: '2026-02-15',
  dueDate: '2026-03-15',
  debtor: {
    name: 'Martin Consulting SAS',
    email: 'direction@martin-consulting.fr',
    phone: '+33678901234',
    siret: '83965478200012',
    address: '45 avenue des Champs-Élysées',
  },
  metadata: { erp_ref: 'ERP-2026-042' },
});

object

Show Propriétés

string

UUID de la facture créée

string

Numéro de facture

number

Montant en centimes

string

Statut initial (imported)

boolean

Indique si le workflow a démarré

string

Date de création ISO 8601

Codes d’erreur possibles

Code	HTTP	Description
`VAL_001`	400	Données invalides
`VAL_003`	400	Champ obligatoire manquant
`AUTH_004`	403	Scope `invoices:write` requis
`RATE_001`	429	Rate limit dépassé

Import en masse

Importe jusqu’à 100 factures en une seule requête. Scopes requis : invoices:write

array

required

Tableau de factures (même format que la création unitaire, max 100)

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
  }'

const result = await finkare.invoices.bulkImport({
  invoices: [
    {
      invoiceNumber: 'FAC-2026-100',
      amount: 75000,
      issueDate: '2026-03-01',
      dueDate: '2026-04-01',
      debtor: { name: 'Lefebvre SARL', email: 'compta@lefebvre.fr' },
    },
    {
      invoiceNumber: 'FAC-2026-101',
      amount: 320000,
      issueDate: '2026-03-15',
      dueDate: '2026-04-15',
      debtor: { name: 'Moreau Industries SA', email: 'finance@moreau-industries.fr' },
    },
  ],
  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

string

required

ID de la facture (UUID)

string

Notes internes (max 2000 caractères)

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

string

required

ID de la facture (UUID)

string

required

Motif d’annulation (max 500 caractères)

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
  }
}

​Lister les factures

​Récupérer une facture

​Créer une facture

​Codes d’erreur possibles

​Import en masse

​Mettre à jour une facture

​Annuler un recouvrement

​Supprimer une facture

​Statistiques

Lister les factures

Récupérer une facture

Créer une facture

Codes d’erreur possibles

Import en masse

Mettre à jour une facture

Annuler un recouvrement

Supprimer une facture

Statistiques