Conventions

Un champ absent n'est ni un zéro ni une estimation : la source ne l'a pas renseigné.

Le territoire

• Une seule granularité par appel. localisation.region couvre tous ses départements en un appel : ne les énumérez pas. localisation.dept prend deux chiffres, ou 2A et 2B, ou 971 à 978. localisation.commune prend un nom de commune ; Paris, Lyon et Marseille réunissent leurs arrondissements.
• Le national, c'est omettre localisation. Les outils de marchés et de PV ignorent all et france et cherchent alors au national : n'écrivez ni l'une ni l'autre.
• Département, région et commune ne sont pas interchangeables, et insee est explicite.

Une requête, un sujet

Le texte libre exige tous les mots de la requête. Deux thèmes dans la même requête ne renvoient presque rien : faites deux appels, puis réunissez les résultats. Seule exception, la recherche par le sens : mairies_deliberations, et marches_dce quand il cherche dans tous les dossiers, sans marche_id.

{ "query": "BIM" }

{ "query": "géomètre" }

plutôt que { "query": "BIM géomètre" }.

Liste et fiche

Les outils de recherche ont deux modes. La liste prend une requête et des filtres, et rend une page de résultats. La fiche prend un identifiant (UUID, SIREN à 9 chiffres, SIRET à 14, code INSEE, pv_id) et rend le détail structuré, jamais un vidage brut.

Pagination

Les listes se paginent par curseur, à reprendre tel quel avec les mêmes filtres : voir Pagination.

Ne rien inventer

Trois garde-fous que le serveur transmet à l'agent avec ses instructions, à l'ouverture de la session et avec le premier résultat :

• Ne jamais fabriquer une adresse de téléchargement : les liens signés durent une heure, ne sont pas des adresses durables et ne se stockent pas.
• « Dossier consultable » veut dire lisible par marches_dce, pas le lien vers la plateforme de l'acheteur.
• Citer les identifiants renvoyés : SIREN, SIRET, marche_id, référence DECP.

Erreurs et événements

Noms

Les outils portent des noms stables, rangés par module, sans préfixe : marches_rechercher, annuaire_entreprises, evenements_lire. Ils se citent tels quels. Les anciens noms en prescriptio_ restent appelables, sans être listés : voir Versions et compatibilité.

Questions