Import de factures - Finkare API

Vue d’ensemble

Finkare propose deux modes d’import :

Mode	Endpoint	Max par requête	Usage
Unitaire	`POST /api/v1/invoices`	1 facture	Import ponctuel, webhook ERP
En masse	`POST /api/v1/invoices/bulk`	100 factures	Import batch quotidien

Scope requis : invoices:write

Import unitaire

Idéal pour les intégrations ERP en temps réel (webhook à chaque nouvelle facture échue).

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: erp-sync-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",
      "contract_id": "CTR-2025-180"
    }
  }'

Utilisez le header Idempotency-Key avec une référence unique (ex : numéro ERP) pour éviter les doublons en cas de retry réseau.

Import en masse

Scénario : vous exportez chaque matin les factures échues depuis votre ERP et les importez en batch.

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: daily-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",
          "siret": "52345678100023"
        }
      },
      {
        "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",
          "phone": "+33156789012"
        }
      },
      {
        "invoiceNumber": "FAC-2026-102",
        "amountCents": 42500,
        "issueDate": "2026-03-20",
        "dueDate": "2026-04-20",
        "debtor": {
          "name": "Petit Commerce EURL",
          "email": "gerant@petit-commerce.fr"
        }
      }
    ],
    "autoStartWorkflow": true
  }'

Avec le SDK TypeScript

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

const finkare = new FinkareClient('fk_live_xxx');

// Importer les factures par lots de 100
async function importFromERP(invoices: CreateInvoiceDto[]) {
  const batchSize = 100;
  const results = [];

  for (let i = 0; i < invoices.length; i += batchSize) {
    const batch = invoices.slice(i, i + batchSize);
    const result = await finkare.invoices.bulkImport({
      invoices: batch,
      autoStartWorkflow: true,
    });
    results.push(result);
    console.log(`Lot ${Math.floor(i / batchSize) + 1} : ${batch.length} factures importées`);
  }

  return results;
}

Format des montants

Tous les montants sont exprimés en centimes (integer) pour éviter les erreurs d’arrondi :

Montant affiché	Valeur `amountCents`
1 500,00 EUR	`150000`
42,50 EUR	`4250`
10 000,00 EUR	`1000000`

Débiteur existant ou nouveau

Si vous connaissez l’ID d’un débiteur déjà enregistré, passez-le dans debtor.id :

{
  "invoiceNumber": "FAC-2026-200",
  "amountCents": 95000,
  "issueDate": "2026-04-01",
  "dueDate": "2026-05-01",
  "debtor": {
    "id": "b7e3c2a1-8f4d-4e6a-9c1b-2d3e4f5a6b7c",
    "name": "Dupont & Fils SARL",
    "email": "comptabilite@dupont-fils.fr"
  }
}

Si le débiteur n’existe pas encore, Finkare le crée automatiquement à partir des informations fournies.

Données immuables

Une fois importée, les données financières d’une facture sont immuables :

Champ	Modifiable ?
`amountCents`	Non
`invoiceNumber`	Non
`issueDate`	Non
`dueDate`	Non
`currency`	Non
`debtor`	Non
`notes`	Oui
`metadata`	Oui

Pour annuler un recouvrement, utilisez POST /api/v1/invoices/:id/cancel.

Bonnes pratiques

Idempotency-Key : utilisez toujours une clé unique par facture pour l’import (ex : erp-sync-{invoiceNumber})
Lots de 100 max : pour l’import en masse, ne dépassez pas 100 factures par requête
Body size : le bulk import accepte jusqu’à 10 Mo (vs 1 Mo pour les autres endpoints)
Metadata : stockez vos références internes dans le champ metadata pour faciliter la réconciliation
Webhook de confirmation : configurez un webhook sur invoice.created pour confirmer chaque import dans votre SI

​Vue d’ensemble

​Import unitaire

​Import en masse

​Avec le SDK TypeScript

​Format des montants

​Débiteur existant ou nouveau

​Données immuables

​Bonnes pratiques

Vue d’ensemble

Import unitaire

Import en masse

Avec le SDK TypeScript

Format des montants

Débiteur existant ou nouveau

Données immuables

Bonnes pratiques