Pagination et données

Lire toutes les pages, utiliser les filtres exacts et interpréter les types métier.

Formes de pagination

La référence de chaque route indique ses valeurs par défaut, bornes et filtres. Les limites ne sont pas uniformes : n’appliquez pas une valeur globale à toutes les ressources.

Forme	Lecture
Objet avec items, total, limit, offset	Parcourir items, puis augmenter offset du nombre d’éléments reçus jusqu’à atteindre total ou une page vide.
Tableau JSON	Lire le tableau et avancer avec offset jusqu’à une page plus courte que limit ou vide. Les listes fonds et SPV exposent aussi X-Marko-Limit, X-Marko-Offset et X-Marko-Has-More; la liste opérations n’expose pas ces headers.
Paramètre page	Respecter le numéro de première page et la limite de la route; ne pas mélanger page et offset.

Un parcours paginé n’est pas un instantané transactionnel : des modifications peuvent intervenir entre deux lectures. Conservez les identifiants, dédupliquez vos résultats et effectuez une nouvelle lecture si votre traitement dépend d’un état courant.

curl --fail-with-body --get "$MARKO_API_BASE_URL/operations" \
  -H "Authorization: Bearer $MARKO_ACCESS_TOKEN" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

MARKO_API_BASE_URL contient le préfixe /v1, par exemple https://partner-api.marko.fr/v1.

Recherche et filtres

GET /operations et GET /spvs proposent name pour une correspondance exacte insensible à la casse et aux espaces périphériques. GET /operateurs distingue name exact et search partiel; ces deux filtres sont mutuellement exclusifs. Une recherche par nom avant création ne garantit pas l’unicité concurrente. Pour une synchronisation, préférez les identifiants externes.

Les filtres de statut utilisent les codes retournés par les taxonomies. Le filtre status=active de la liste opérations est un raccourci documenté vers les cinq statuts canoniques actifs. Ne traduisez pas un libellé d’interface pour fabriquer un code.

Encodez les valeurs des paramètres et segments d’URL avec la bibliothèque HTTP utilisée. Pour les paramètres booléens, utilisez true ou false; la référence enrichie indique leur type réel.

Identifiants, dates et valeurs

Les UUID MARKO et les identifiants externes sont deux valeurs différentes. Les identifiants utilisateur peuvent être des chaînes non UUID. Le schéma de la route fait autorité.

Les dates sont en ISO 8601. Une date métier YYYY-MM-DD ne porte pas de fuseau; une date-heure telle que 2026-10-01T10:00:00Z en porte un. Les notes externes ont des règles de normalisation spécifiques décrites dans Imports et notes.

Un champ absent et un champ null ne sont pas interchangeables dans une mutation. N’envoyez que les propriétés que vous souhaitez traiter et respectez le modèle d’update de la route. Certains montants décimaux sont sérialisés en chaîne pour préserver leur précision; respectez le type de réponse, sans convertir systématiquement en flottant.

Champs métier extensibles

data, certains résumés, configurations de workflow et métadonnées sont des objets JSON ouverts par conception. Pour les champs métier des opérations, interrogez GET /field-definitions ou GET /field-definitions/by-key/{field_key} : le référentiel décrit les clés et leurs métadonnées métier. Vérifiez l’unité, le type et la disponibilité d’un champ avant de l’écrire; ne déduisez pas une unité monétaire ou un pourcentage de son nom.

Unités des snapshots financiers

Le champ kpi_snapshot utilise les unités de stockage des indicateurs. Les valeurs décimales peuvent être fournies sous forme numérique ou de chaîne décimale selon le schéma.

Champ	Unité à transmettre	Exemple
ltv, ltc	Fraction entre 0 et 2.	0.65 signifie 65 %, pas 65.
debt_yield	Fraction.	0.08 signifie 8 %.
dscr, icr	Multiple de couverture.	1.25 signifie 1,25 fois.
pct_perte_estimee	Fraction entre 0 et 1.	0.03 signifie 3 %.
risk_score_simple	Points entre 0 et 100.	35 est un score de 35 points.
crd_total_source	Origine du capital restant dû.	financing_tranches ou operation_data.

crd_total, crd_senior, crd_mezzanine, valeur_venale, noi et service_dette sont des valeurs financières. Garder des unités monétaires cohérentes et aligner les périodes du NOI et du service de la dette. Le schéma du snapshot ne porte pas de champ de conversion de devise; confirmer cette convention pour les données importées.

Les clés des KPI appartiennent au snapshot. Les placer dans kpi_snapshot rend leur rôle explicite; elles ne doivent pas être traitées comme de simples champs JSON indépendants dans data.