Référence

La liste des routes vit dans l’API, pas ici

La recopier dans cette documentation garantirait seulement qu’un jour les deux se contrediraient, et c’est toujours la copie qu’on croit. Cette page décrit en revanche ce que la liste des routes ne dit pas : ce que toutes les routes ont en commun.

Les préfixes, et ce qu’ils annoncent

D’autres préfixes existent, réservés à l’exploitation de la plateforme par l’équipe Stratt. Ils ne sont pas documentés ici et ne sont pas destinés aux intégrations.

L’en-tête d’organisation

X-Organization-Id: <uuid-de-l-organisation>

Requis sur les routes métier, sur chaque requête — il n’y a pas de notion d’organisation « courante » retenue d’un appel à l’autre. Un client qui sert plusieurs collectivités n’a donc rien à basculer : il change d’en-tête. Voir Authentification.

L’enveloppe des réponses

Toutes les réponses partagent la même forme, et les trois champs sont mutuellement exclusifs en pratique :

{ "data": … }

{ "message": "token révoqué" }

{ "error": "description lisible" }

Un client qui lit data doit donc tolérer son absence, et ne pas confondre « champ absent » avec « collection vide ».

Pagination

Ce qui est constant :

• le numéro de page s’appelle page et commence à 1, jamais à 0 ;
• une valeur inférieure à 1 est ramenée à 1 plutôt que refusée ;
• la taille demandée est plafonnée par la route, silencieusement : demander 100 000 lignes ne produit pas d’erreur, seulement moins de lignes que demandé ;
• le nombre total d’éléments correspondant au filtre est renvoyé à côté de la page, sous total — c’est lui qui vous dit s’il reste des pages, et non la taille de la page reçue.

Ce qui varie :

• la taille de page s’appelle limit sur certaines routes, page_size sur d’autres ;
• le plafond diffère : de l’ordre de la centaine sur les journaux et les livraisons, bien plus large sur les listes destinées aux vues analytiques ;
• la collection n’est pas toujours sous la même clé. Selon la route, elle est sous items, ou sous un nom métier (logs, deliveries, mandats…) ;
• certaines routes ajoutent pages, le nombre de pages, d’autres non.

Il n’y a pas de pagination par curseur : une collection qui change pendant que vous la parcourez peut vous faire revoir ou manquer une ligne. Pour un export fidèle, préférez un filtre qui borne le jeu de données — un exercice budgétaire, un intervalle de dates — à un parcours de toutes les pages.

Tri

Il n’y a pas de paramètre de tri générique. Chaque route porte un ordre par défaut choisi pour elle, le plus souvent la date de création décroissante pour les journaux et les listes récentes.

Les routes qui laissent le choix exposent un paramètre nommé et une liste fermée de valeurs : la recherche dans les bordereaux de prix accepte ainsi un paramètre tri valant pertinence, prix_asc, prix_desc, date_valeur ou echeance, et refuse en 400 toute autre valeur. Un tri inconnu n’est donc jamais ignoré en silence.

Filtres

Les filtres sont des paramètres de requête, cumulatifs, et combinés par un et logique : plus vous en passez, moins vous recevez. Un filtre absent ne restreint rien ; un filtre présent mais vide est traité comme absent.

Leur sémantique, en revanche, est propre à chaque route et ne se devine pas : le même nom peut désigner une égalité stricte sur une route et une correspondance partielle sur une autre. Deux exemples, à lire comme des exemples et non comme une règle :

GET /api/v1/mandats?exercice=2026&service=601&search=voirie&page=1&page_size=50
GET /api/v1/audit?resource_type=marche&action=create&from=2026-01-01&page=1

Dates et fuseau

Trois règles à retenir :

1. Les bornes de filtrage s’écrivent AAAA-MM-JJ, et pas autrement : une date au format français n’est pas comprise. Une borne illisible est ignorée plutôt que refusée — le filtre disparaît alors sans message, ce qui donne bien plus de lignes qu’attendu.
2. Une borne de fin inclut la journée entière qu’elle nomme, jusqu’à son dernier instant. to=2026-12-31 comprend donc le 31 décembre.
3. Les bornes s’entendent en temps universel, et l’API n’accepte aucun paramètre de fuseau. Une journée de travail française se termine, en temps universel, dans la journée suivante : sur un intervalle long c’est négligeable, sur un seul jour c’est une à deux heures d’écart aux bords. Comparez des instants, et n’en déduisez pas une date locale sans convertir.

Les horodatages renvoyés sont au format RFC 3339. Lisez-les comme des instants ; l’enveloppe des webhooks, elle, est toujours exprimée en temps universel.

Les documents s’obtiennent par un lien dédié

Les rapports, fiches et exports ne se téléchargent pas par un appel ordinaire : l’API échange d’abord votre session contre un lien de courte durée et à usage unique.

curl -s -X POST https://api.stratt.fr/api/v1/exports/ticket \
  -H "Authorization: Bearer $STRATT_TOKEN" \
  -H "X-Organization-Id: $STRATT_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"document":"annuel","params":{"year":"2026"}}'

La réponse porte une URL relative — à préfixer de votre base d’API — et la date expires_at au-delà de laquelle elle n’ouvrira plus rien.

document se choisit dans une liste fermée : cartographie, annuel, nomenclature, dossier et audit. Toute autre valeur est refusée en 400. dossier demande en plus un params.id, l’identifiant du marché concerné.

Les droits ne sont pas contournés par ce détour : le module et la permission que la route exige sont contrôlés à l’ouverture du document comme à l’émission du lien.

Limites connues

• Pagination hétérogène (limit contre page_size) et clé de collection variable : un client générique doit s’adapter par route.
• Pas de pagination par curseur, pas de tri générique, pas d’en-tête de version.
• Les bornes de dates illisibles sont ignorées en silence.
• La description OpenAPI couvre les principaux points d’entrée publics, et non l’intégralité des routes : prenez-la comme une référence de travail, non comme un inventaire.