Les états en 3 étapes

Ce qu'est un état, comment le choisir, le prévisualiser et le générer, et le vocabulaire minimal pour s'y retrouver.

Ce qu'est un état

Un état est un tableau de données extrait de la plateforme sur une période, livré en PDF, CSV ou XLSX : liste des quittances du mois, récapitulatif de production par compagnie, encaissements, impayés, bordereau de coassurance… Les états sont calculés à la demande à partir des données réelles (contrats, avenants, paiements, répartitions) et limités au périmètre de votre compte.

Il y a deux façons d'obtenir un état :

Un état prédéfini du catalogue : vous donnez son code et une période, tout le reste est déjà réglé. C'est le cas d'usage le plus simple et il couvre la grande majorité des besoins.
Un état personnalisé : vous décrivez vous-même la source, les colonnes, les filtres, les regroupements. Voir États personnalisés.

Les trois étapes

Choisir un état dans le catalogue

curl -s $API/provider/reports/catalog -H "Authorization: Bearer $TOKEN"

Le catalogue renvoie des familles (Production, Récapitulatifs Pool, Renouvellements, Encaissements & quittances, Gestion) contenant des cartes. Chaque carte a un code, un titre, une description, les formats autorisés et la source dont elle dépend.

{
  "families": [
    {
      "key": "FINANCES", "label": "Encaissements & quittances",
      "cards": [
        { "code": "QUITTANCEMENT", "title": "Quittancement", "formats": ["PDF", "CSV", "XLSX"], "sourceCode": "RECEIPTS", "popular": true }
      ]
    }
  ]
}

La liste complète des 24 états explique ce que chacun contient et sur quelle date il se base.

Prévisualiser

curl -s -X POST $API/provider/reports/preview \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "definitionCode": "QUITTANCEMENT",
    "scope": { "relativeRange": "PREVIOUS_MONTH" },
    "page": 0, "size": 20
  }'

L'aperçu renvoie les colonnes, une page de lignes, les totaux (summary), la période réellement appliquée (resolvedFrom, resolvedTo) et une estimation de la taille du fichier. C'est le moyen de vérifier ce que vous allez générer sans produire de fichier.

Générer puis télécharger

curl -s -X POST $API/provider/reports/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "definitionCode": "QUITTANCEMENT", "scope": { "relativeRange": "PREVIOUS_MONTH" }, "format": "XLSX" }'

La génération est synchrone : la réponse 201 contient une exécution (execution.id, status: SUCCESS, fileName, rowCount, checksumSha256). Le fichier se télécharge ensuite :

curl -s -o quittancement.xlsx -H "Authorization: Bearer $TOKEN" \
  $API/provider/reports/executions/{execution.id}/file

Le vocabulaire en une page

Terme	Clé JSON	Ce que c'est
État (définition)	`definitionCode`	Une carte du catalogue, ex. `QUITTANCEMENT`. Porte des réglages par défaut (source, colonnes, filtres, période, tri).
Source	`sourceCode`	La table de données interrogée, ex. `RECEIPTS` (une ligne = une quittance). Neuf sources existent.
Champ	`fieldName`	Une colonne disponible dans une source, ex. `netPremium`. Chaque champ dit s'il est filtrable, triable, groupable, totalisable.
Période (scope)	`scope`	La fenêtre de dates : une ancre (`basedOn`, ex. date d'émission) et des bornes relatives (`relativeRange`) ou absolues (`dateRange`).
Filtre	`filters[]`	Condition sur un champ : `{ fieldName, operator, values }`.
Regroupement	`grouping[]`	Champs de rupture. Avec `options.aggregated=true`, une ligne par groupe (mode récapitulatif).
Spécification	`columns`, `filters`, `scope`, `grouping`, `sorting`, `options`	L'ensemble des réglages d'un état.
Modèle	`modelId`	Une spécification enregistrée sous un nom, réutilisable et planifiable.
Exécution	`executionId`	Une génération réalisée, avec son fichier archivé.
Planification	schedule	L'envoi automatique récurrent d'un modèle par e-mail.

Ce qu'il faut retenir

Le plus court chemin : definitionCode + scope + format, et vous avez votre fichier.
Tout ce que vous ne précisez pas prend la valeur par défaut de l'état (colonnes, tri, filtres, ancre de date). Tout ce que vous précisez la remplace.
Les montants viennent des avenants émis et des répartitions réelles, jamais de l'en-tête du contrat. Chaque carte du catalogue documente sa règle dans methodologyNote.
Un compte compagnie ne voit que ses données ; un compte Pool voit tout et peut générer un fichier par compagnie en une fois (scopeMode: PER_COMPANY).
Le PDF est limité à 25 000 lignes ; au-delà, prenez XLSX ou CSV, ou réduisez la période.