Abonnements SaaS — payableType=subscription

# 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 le **plafond de la carte dédiée**, pas 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": { "field": "payableType", "operator": "=", "value": ["subscription"] },
  "fromDate": "2026-01-01",
  "toDate": "2026-06-30",
  "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": { "field": "payableType", "operator": "=", "value": ["subscription"] }
}
```

⚠️ `groupBy=supplier` retourne des IDs (pas des noms) — un appel `get_suppliers(ids=[...])` est nécessaire pour l'affichage (voir skill S05).

## 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 |
| `state` | 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 ?"