Lister les abonnements et leur coût

# Abonnements SaaS — payableType=subscription

## Requête de base

```json
{
  "companyId": "<companyId>",
  "filters": {
    "field": "payableType",
    "operator": "=",
    "value": ["subscription"]
  },
  "pageSize": 20
}
```

→ `hasNextPage: true` si plus de 20 résultats — paginer avec le curseur pour tout récupérer.

## ⚠️ spendingAmount ≠ montant de l'abonnement

C'est le piège principal sur les subscriptions. `spendingAmount` est décrit par le serveur comme le montant dans la devise de la carte ; sur les abonnements il a été observé très supérieur au montant facturé, donc ne pas le traiter comme le montant facturé :

| Description | amount (réel) | spendingAmount (plafond carte) |
|-------------|---------------|---------------------------------|
| Google Apps subscription | 32,26 EUR | 4 500 EUR |
| Auto-recharge on Twilio | 14,65 EUR | 50 EUR |
| MessageBird | 27,36 EUR | 5 000 EUR |
| CRM 5 utilisateurs | 276,25 USD → 257 EUR | 400 USD |

→ **Ne JAMAIS sommer `spendingAmount`** pour calculer le coût total des abonnements — le résultat serait 10 à 200× supérieur à la réalité.
→ Toujours utiliser `amount` (devise locale) ou `functionalAmount` (EUR) pour les montants réels.

```json
// Bonne pratique
const totalEUR = payables.reduce((sum, p) => sum + p.functionalAmount.amount / Math.pow(10, p.functionalAmount.precision), 0)

// À ne pas faire
const totalFaux = payables.reduce((sum, p) => sum + p.spendingAmount.amount / ..., 0)  // peut être 100× trop élevé
```

## Devises : majorité en USD (SaaS internationaux)

Les abonnements SaaS sont majoritairement facturés en USD. Utiliser `functionalAmount` pour le total EUR :

```json
{
  "currency": "USD",
  "functionalCurrency": "EUR",
  "functionalExchangeRate": 0.9315,
  "amount": { "amount": 27625, "currency": "USD", "precision": 2 },
  "functionalAmount": { "amount": 25722, "currency": "EUR", "precision": 2 }
}
```

→ Sommer `functionalAmount` pour obtenir le total EUR consolidé toutes devises.

## Filtrer par période

Pour les abonnements d'une période donnée :

```json
{
  "companyId": "<companyId>",
  "filters": { "operator": "and", "subfilters": [
    { "field": "payableType", "operator": "=", "value": ["subscription"] },
    { "field": "payableDate", "operator": "between", "value": { "from": "2026-01-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.999Z" } }
  ] },
  "pageSize": 20
}
```

## Lier abonnement → fournisseur

Chaque payable expose `counterparty.supplierId` (pas de nom) :

```json
{ "counterparty": { "type": "supplier", "supplierId": "S1mrHIIp" } }
```

→ `get_supplier_by_id("S1mrHIIp")` pour obtenir le nom (`legalName`), l'IBAN, le numéro de TVA.

## Analyse agrégée avec spendesk_analyze_spend

Pour un total rapidement groupé par fournisseur :

```json
{
  "companyId": "<companyId>",
  "fromDate": "2026-01-01",
  "toDate": "2026-06-30",
  "groupBy": ["supplier"],
  "filters": { "payableTypes": ["subscription"] }
}
```

`groupBy=supplier` retourne le nom du fournisseur dans `key` et son ID dans `id`. Les IDs bruts n'apparaissent dans `key` que si le token n'a pas le scope de lecture fournisseurs : `summary.limitations` le signale alors (type `unresolved-names`).

## Champs utiles

| Champ | Description |
|-------|-------------|
| `description` | Libellé de l'abonnement |
| `amount` / `functionalAmount` | Montant réel en devise locale / EUR (coefficient entier / 10^precision) |
| `spendingAmount` | Plafond de la carte — ne pas utiliser pour les totaux |
| `counterparty.supplierId` | ID du fournisseur SaaS |
| `currency` | Devise de facturation (souvent USD) |
| `functionalExchangeRate` | Taux de change appliqué |
| `creationDate` | Date du payable |
| `bookkeepingStatus` | Statut comptable (`exported`, `toExport`, `toPrepare`) |

## Exemples de prompts

- "Quels sont nos abonnements SaaS et leur coût mensuel ?"
- "Montre-moi le total dépensé en abonnements au premier trimestre"
- "Quels abonnements sont encore actifs ?" (filtrer par `fromDate` récente)
- "Liste tous les abonnements facturés en USD"
- "Quel est le coût mensuel moyen de notre abonnement Google Apps ?"