Journal des changements de l'API

Ce journal couvre l'API REST (/api/v1) et le serveur MCP (/api/mcp). La référence est dans la documentation de l'API et dans la documentation du serveur MCP. Les entrées sont classées de la plus récente à la plus ancienne.

Règle de dépréciation

Préavis de 90 jours avant tout retrait ou changement incompatible : nom de champ, route, code d'erreur, périmètre, sens d'un paramètre. Le préavis est annoncé :

• dans ce journal, avec la date de début et la date de fin du préavis ;
• par e-mail aux titulaires des clés actives.

Ce qui est compatible ne demande pas de préavis, mais figure ici : l'ajout d'un champ à une réponse, d'une route, d'un outil MCP, d'une valeur d'énumération, d'un paramètre optionnel. Votre client doit donc ignorer les champs et les valeurs qu'il ne connaît pas.

2026-10-10 : descriptions des routes enrichies dans le document OpenAPI

Changement compatible, sans préavis.

• Les descriptions du document /api/v1/openapi.json sont plus détaillées ; aucun champ, route ni comportement ne change.

2026-10-10 : adresse de l'API et du serveur MCP

Changement compatible, sans préavis.

• L'API est annoncée à l'adresse https://publikconnect.fr/api/v1, et le serveur MCP à l'adresse https://publikconnect.fr/api/mcp.
• Le document OpenAPI ne déclare plus que ce serveur, nommé « Production ».
• L'adresse utilisée auparavant continue de répondre, mais elle n'est plus annoncée : utilisez de préférence les adresses ci-dessus.

2026-10-09 : six collectivités d'outre-mer dans les départements

Changement compatible (valeurs d'énumération ajoutées), sans préavis.

• Le filtre departement accepte 975, 977, 978, 986, 987 et 988 (Saint-Pierre-et-Miquelon, Saint-Barthélemy, Saint-Martin, Wallis-et-Futuna, Polynésie française, Nouvelle-Calédonie). Il les refusait (400).
• GET /departements passe de 101 à 107 lignes, avec le nombre d'avis ouverts de chacune.
• Le champ departement des avis, attributions, contrats et acheteurs, qui valait null pour ces codes, porte désormais le code. Environ 90 avis ouverts sont concernés.

2026-10-08 : origine deduit du SIRET acheteur

Changement compatible (valeur d'énumération ajoutée), sans préavis.

• origines.acheteur.siret.origine peut valoir deduit, avec source = publikconnect : le SIRET de l'acheteur n'est pas publié par la source de l'avis ni par une autre publication, et PublikConnect l'a rattaché à la fiche acheteur liée (nom compatible, département identique ou inconnu). Précédence : publié, puis jumeau, puis deduit.
• Rattrapage initial, le 2026-10-08 : environ 1 000 avis ouverts reçoivent un SIRET deduit. Leur version avance une fois : une synchronisation par updated_since les renvoie une fois, avec le SIRET et l'origine renseignés. Aucun autre champ ne change.
• Ensuite, la règle s'applique chaque nuit à 05:10 UTC, après l'ingestion des avis : les avis nouvellement rattachés avancent aussi d'une version. Si la source publie plus tard un SIRET différent, il remplace le SIRET déduit et origine disparaît.

2026-10-08 : jeu complet de routes de lecture

Cette version fait passer l'API de quatre ressources à un jeu complet de lecture. Les changements ci-dessous sont annoncés sans préavis, car la première version, décrite plus bas, n'a jamais été ouverte en production.

Routes ajoutées

• GET /avis, GET /avis/{id} : tous les avis des sources du registre (18 sources), doublons filtrés, sans fenêtre de publication. Deux modes : recherche par page, et parcours par curseur avec updated_since pour synchroniser (avis clos et retire compris).
• GET /opportunites : le fil noté du compte, avec score, raisons, verdict et statut_utilisateur.
• GET /prestataires : recherche des titulaires de marchés. GET /prestataires/{slug} gagne principaux_acheteurs et contrats_a_echeance.
• GET /acheteurs/{siret} : fiche d'un acheteur public.
• GET /attributions : avis d'attribution. GET /contrats : contrats de la commande publique (DECP), avec un filtre indexé obligatoire.
• GET /sources : registre des sources (licence, mention, état, complétude moyenne).
• GET /moi : clé, plan, quota du jour.
• GET /sante : état de l'API, sans clé.

Changements de comportement

• GET /marches et GET /marches/{id} sont remplacées par /avis, /avis/{id} et /opportunites. Le compteur de GET /departements s'appelle désormais avis_ouverts (il s'appelait marches_ouverts).
• Le champ diffusion et le niveau de détail réduit selon la source n'existent plus : toutes les sources actives sont servies en entier. Chaque avis porte licence, mention, version, completude, publie_aussi_sur, origines et liens.
• Périmètres de clé : avis:read, opportunites:read, prestataires:read, acheteurs:read, decp:read. Usage d'une clé : interne ou rediffusion.
• Quota journalier en enregistrements servis, deux familles : general (50 000 par défaut) et decp (2 000 par défaut), réglables par compte. En-têtes X-Quota-Limit et X-Quota-Remaining. Code d'erreur quota_exceeded.
• Pagination : per_page jusqu'à 100 (50 au plus dans la première version). Codes d'erreur ajoutés : filter_required, page_too_deep, invalid_cursor, resync_required.
• Protection du service : délai de 5 secondes en base, mémoire de 60 secondes sur certaines listes, plafond de requêtes simultanées, en-tête X-Request-Id sur toute réponse.

Outils MCP

• Renommés : search_marches devient search_avis, get_marche devient get_avis.
• Ajoutés : list_opportunites, search_prestataires, get_acheteur, search_attributions, search_contrats, list_sources, mon_compte.
• Inchangés : get_prestataire, list_departements.
• Total : onze outils, filtrés selon les périmètres de la clé.

2026-10-08 : première version

Première version, réservée à des clés de test et jamais ouverte en production.

• GET /marches, GET /marches/{id} : avis des sources officielles (BOAMP, TED, PLACE), en mode général ou en mode profil.
• GET /prestataires/{slug} : fiche publique d'un titulaire.
• GET /departements : départements et nombre de marchés ouverts.
• GET /openapi.json : document OpenAPI 3.1.
• Serveur MCP à quatre outils : search_marches, get_marche, get_prestataire, list_departements.
• Authentification par X-API-Key ou Authorization: Bearer, limite de 60 requêtes par minute et par clé.