Settlements non exportés — get_settlements

# Settlements non exportés — get_settlements

## Les 3 états d'un settlement

| État | Signification | exportedAt |
|------|--------------|-----------|
| `created` | Clearé dans Spendesk, pas encore exporté vers l'ERP | null |
| `exported` | Envoyé vers l'ERP avec succès | date ISO |
| `failedToExport` | Export tenté mais échoué | null |

## Rappel important

"Clearé dans Spendesk" ≠ "prêt pour l'export GL". Le workflow comptable (export GL) repose sur `bookkeepingStatus` des **payables**, pas sur les settlements. Les settlements servent à la **réconciliation bancaire** — ils représentent les mouvements de cash réels.

## Appel — settlements non exportés (created)

```json
{
  "tool": "get_settlements",
  "params": {
    "companyId": "<companyId>",
    "state": ["created"],
    "pageSize": 50
  }
}
```

## Appel — échecs d'export (failedToExport)

```json
{
  "tool": "get_settlements",
  "params": {
    "companyId": "<companyId>",
    "state": ["failedToExport"],
    "pageSize": 50
  }
}
```

## Découverte : settlements "created" datant de 2017

Sur ce compte, les settlements en `state: "created"` remontent jusqu'en **mai 2017** — soit 9 ans de settlements non exportés. Cela peut signifier :
1. L'export GL via settlements n'a jamais été activé sur ce compte (il utilise l'export via payables `bookkeepingStatus` à la place)
2. Ces anciens settlements sont historiquement antérieurs à la mise en place de l'intégration ERP

→ `state: "created"` ne signifie pas forcément "en attente d'action" — peut être un état permanent pour les comptes sans intégration ERP settlements.

## Découverte : failedToExport avec statusUpdatedAt = null

Les settlements `failedToExport` ont tous `statusUpdatedAt: null`. Il est impossible de savoir **quand** l'export a échoué depuis les données retournées. Les échecs datent de 2020.

```json
{
  "exportedAt": null,
  "statusUpdatedAt": null,
  "state": "failedToExport"
}
```

→ Pour auditer les échecs récents, utiliser le filtre date `clearedFrom`/`clearedTo` pour isoler une période.

## Champs retournés

```json
{
  "id": "uuid",
  "type": "payment | reimbursement | refund | cashReturn",
  "medium": "card | wiretransfer",
  "paidFrom": "spendeskAccount | externalAccount",
  "transactionDescription": "description",
  "clearedAt": "2024-01-15T00:00:00.000Z",
  "currency": "EUR",
  "billingCurrency": "EUR",
  "billingExchangeRate": 1,
  "state": "created | exported | failedToExport",
  "exportedAt": null,
  "statusUpdatedAt": null,
  "amount": { "amount": 21146, "currency": "EUR", "precision": 2 },
  "billingAmount": { "amount": 21146, "currency": "EUR", "precision": 2 },
  "allocations": [
    {
      "amount": { "amount": 21146, "currency": "EUR", "precision": 2 },
      "currency": "EUR",
      "payableId": "uuid-du-payable"
    }
  ]
}
```

## Montants négatifs

Un settlement peut avoir un montant négatif (`amount: -175780`) — c'est un **remboursement** ou **refund** (ex: annulation de réservation, avoir fournisseur). L'exemple observé : 3 refunds MWC Barcelona suite à l'annulation de l'événement COVID.

## Filtrer par période de clearing

```json
{
  "state": ["created"],
  "clearedFrom": "2026-01-01",
  "clearedTo": "2026-06-30"
}
```

→ Pour la réconciliation mensuelle, toujours filtrer par `clearedFrom`/`clearedTo` — sans filtre, on obtient toute l'historique.

## paidFrom : externalAccount vs spendeskAccount

| Valeur | Signification |
|--------|--------------|
| `spendeskAccount` | Payé depuis le wallet Spendesk (cartes, virements Spendesk) |
| `externalAccount` | Payé depuis un compte bancaire externe (remboursements manuels) |

## Exemples de prompts utilisateur

- "Quels settlements n'ont pas encore été exportés vers notre ERP ?"
- "Y a-t-il des échecs d'export à corriger ?"
- "Donne-moi tous les mouvements clearés en juin 2026 pour la réconciliation bancaire"