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

# Factures

> Création, import et suivi des factures à recouvrer. Import unitaire et en masse (jusqu'à 100 factures par requête).

<Info>**Tester en direct** — Essayez ces endpoints dans la [documentation interactive Scalar](https://api.finkare.io/docs).</Info>

## Lister les factures

<ParamField query="status" type="string" optional>
  Filtrer par statut : `draft`, `imported`, `lrar_sent`, `in_recovery`, `paid`, `partial`, `disputed`, `written_off`, `judicial`
</ParamField>

<ParamField query="debtorId" type="string" optional>
  Filtrer par ID du débiteur (UUID)
</ParamField>

<ParamField query="fromDate" type="string" optional>
  Date de début d'émission (ISO 8601). Exemple : `2026-01-01`
</ParamField>

<ParamField query="toDate" type="string" optional>
  Date de fin d'émission (ISO 8601). Exemple : `2026-03-31`
</ParamField>

<ParamField query="minAmount" type="number" optional>
  Montant minimum en centimes
</ParamField>

<ParamField query="maxAmount" type="number" optional>
  Montant maximum en centimes
</ParamField>

<ParamField query="search" type="string" optional>
  Recherche textuelle (numéro de facture, nom du débiteur)
</ParamField>

<ParamField query="page" type="number" optional default="1">
  Numéro de page
</ParamField>

<ParamField query="limit" type="number" optional default="20">
  Résultats par page (max 100)
</ParamField>

<ParamField query="sortBy" type="string" optional default="created_at">
  Champ de tri : `created_at`, `due_date`, `amount_cents`, `status`
</ParamField>

<ParamField query="sortOrder" type="string" optional default="desc">
  Ordre : `asc` ou `desc`
</ParamField>

**Scope requis :** `invoices:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: fk_live_xxx" \
    "https://api.finkare.io/api/v1/invoices?status=in_recovery&page=1&limit=20"
  ```

  ```typescript SDK theme={null}
  const invoices = await finkare.invoices.list({
    status: 'in_recovery',
    page: '1',
    limit: '20',
  });
  ```
</CodeGroup>

***

## Récupérer une facture

<ParamField path="id" type="string" required>
  ID de la facture (UUID)
</ParamField>

**Scope requis :** `invoices:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: fk_live_xxx" \
    https://api.finkare.io/api/v1/invoices/c3d4e5f6-a1b2-7890-cdef-1234567890ab
  ```

  ```typescript SDK theme={null}
  const invoice = await finkare.invoices.get('c3d4e5f6-a1b2-7890-cdef-1234567890ab');
  ```
</CodeGroup>

***

## Créer une facture

Crée une nouvelle facture et démarre automatiquement le workflow de recouvrement.

**Scope requis :** `invoices:write`

<ParamField body="invoiceNumber" type="string" required>
  Numéro de facture unique. Exemple : `FAC-2026-001`
</ParamField>

<ParamField body="amountCents" type="number" required>
  Montant total TTC en centimes. Exemple : `150000` (1 500,00 EUR)
</ParamField>

<ParamField body="currency" type="string" optional default="EUR">
  Devise ISO 4217
</ParamField>

<ParamField body="issueDate" type="string" required>
  Date d'émission (ISO 8601). Exemple : `2026-03-01`
</ParamField>

<ParamField body="dueDate" type="string" required>
  Date d'échéance (ISO 8601). Exemple : `2026-03-31`
</ParamField>

<ParamField body="description" type="string" optional>
  Description de la facture (max 500 caractères)
</ParamField>

<ParamField body="debtor" type="object" required>
  Informations du débiteur

  <Expandable title="Propriétés">
    <ParamField body="debtor.name" type="string" required>
      Nom ou raison sociale. Exemple : `Dupont & Fils SARL`
    </ParamField>

    <ParamField body="debtor.email" type="string" required>
      Email de contact principal
    </ParamField>

    <ParamField body="debtor.phone" type="string" optional>
      Téléphone (format international). Exemple : `+33612345678`
    </ParamField>

    <ParamField body="debtor.siret" type="string" optional>
      Numéro SIRET (14 chiffres)
    </ParamField>

    <ParamField body="debtor.address" type="string" optional>
      Adresse postale
    </ParamField>

    <ParamField body="debtor.city" type="string" optional>
      Ville
    </ParamField>

    <ParamField body="debtor.postalCode" type="string" optional>
      Code postal
    </ParamField>

    <ParamField body="debtor.country" type="string" optional default="FR">
      Code pays ISO 3166-1 alpha-2
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object" optional>
  Données personnalisées (clé-valeur)
</ParamField>

<CodeGroup>
  ```bash cURL 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: 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"
      }
    }'
  ```

  ```typescript SDK theme={null}
  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' },
  });
  ```
</CodeGroup>

<ResponseField name="data" type="object">
  <Expandable title="Propriétés">
    <ResponseField name="id" type="string">UUID de la facture créée</ResponseField>
    <ResponseField name="invoiceNumber" type="string">Numéro de facture</ResponseField>
    <ResponseField name="amountCents" type="number">Montant en centimes</ResponseField>
    <ResponseField name="status" type="string">Statut initial (`imported`)</ResponseField>
    <ResponseField name="workflowStarted" type="boolean">Indique si le workflow a démarré</ResponseField>
    <ResponseField name="createdAt" type="string">Date de création ISO 8601</ResponseField>
  </Expandable>
</ResponseField>

### 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`

<ParamField body="invoices" type="array" required>
  Tableau de factures (même format que la création unitaire, max 100)
</ParamField>

<ParamField body="autoStartWorkflow" type="boolean" optional default="true">
  Démarrer automatiquement le workflow pour chaque facture
</ParamField>

<CodeGroup>
  ```bash cURL 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: 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
    }'
  ```

  ```typescript SDK theme={null}
  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,
  });
  ```
</CodeGroup>

<Note>
  Le body size maximum est de **10 Mo** pour l'import en masse (vs 1 Mo pour les autres endpoints).
</Note>

***

## 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`

<ParamField path="id" type="string" required>
  ID de la facture (UUID)
</ParamField>

<ParamField body="notes" type="string" optional>
  Notes internes (max 2000 caractères)
</ParamField>

<ParamField body="metadata" type="object" optional>
  Données personnalisées
</ParamField>

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

<Warning>
  Les champs `amount`, `invoiceNumber`, `issueDate`, `dueDate`, `currency` et `debtor` ne peuvent pas être modifiés. Toute tentative retourne une erreur `FORBIDDEN_FIELD_MODIFICATION`.
</Warning>

***

## 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`

<ParamField path="id" type="string" required>
  ID de la facture (UUID)
</ParamField>

<ParamField body="reason" type="string" required>
  Motif d'annulation (max 500 caractères)
</ParamField>

<ParamField body="notifyDebtor" type="boolean" optional default="false">
  Notifier le débiteur par email de l'annulation
</ParamField>

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

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

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

<Warning>
  Si le workflow est déjà lancé, utilisez `POST /v1/invoices/:id/cancel` à la place.
</Warning>

***

## Statistiques

Récupère un résumé statistique de vos factures.

**Scope requis :** `reports:read`

```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/invoices/stats/summary
```

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