Skip to main content

​
Vue d’ensemble

Finkare propose deux modes d’import :
ModeEndpointMax par requêteUsage
UnitairePOST /api/v1/invoices1 factureImport ponctuel, webhook ERP
En massePOST /api/v1/invoices/bulk100 facturesImport 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 EUR150000
42,50 EUR4250
10 000,00 EUR1000000

​
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 :
ChampModifiable ?
amountCentsNon
invoiceNumberNon
issueDateNon
dueDateNon
currencyNon
debtorNon
notesOui
metadataOui
Pour annuler un recouvrement, utilisez POST /api/v1/invoices/:id/cancel.

​
Bonnes pratiques

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