> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import de factures

> Guide complet pour importer vos factures dans Finkare — unitaire ou en masse depuis votre ERP.

## 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).

```bash theme={null}
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"
    }
  }'
```

<Tip>
  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.
</Tip>

## Import en masse

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

```bash theme={null}
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

```typescript theme={null}
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` :

```json theme={null}
{
  "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

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