--- title: "Gestion des versions" description: "Comment l'API Matchai gère ses versions : /v1 dans l'URL, les changements sans nouvelle version, ce qui est incompatible et l'avis des mises en obsolescence." last_updated: "2026-10-21" lang: "fr-CA" status: "coming-soon" canonical: "https://matchai.co/docs/fr/developers/versioning" --- # Gestion des versions > Comment l'API Matchai gère ses versions : /v1 dans l'URL, les changements sans nouvelle version, ce qui est incompatible et l'avis des mises en obsolescence. **Bientôt disponible. Cette fonctionnalité est documentée avant son lancement pour que vous puissiez planifier votre intégration; elle n’est pas encore offerte.** Source: https://matchai.co/docs/fr/developers/versioning L'API Matchai gère ses versions pour qu'une intégration que vous bâtissez continue de fonctionner. Cette page explique ce qui reste pareil, ce qui peut changer sous vos pieds, et comment vous êtes avisé des changements qui demandent votre attention. ## La version est dans le chemin [#the-version-is-in-the-path] La version majeure fait partie de chaque adresse : ```text title="Base URL" https://api.matchai.co/v1 ``` Les événements webhook portent la même version dans leur corps, sous la forme `"api_version": "v1"`. Une adresse qui commence par `/v1` se comporte comme le décrit cette documentation tant que `/v1` existe. Tant que l'API n'est pas ouverte, cette documentation est un aperçu. Le fichier de contrat porte la version `1.0.0-preview`, et des détails peuvent encore changer avant le lancement. Une fois l'API ouverte, les règles de cette page s'appliquent à `/v1`. ## Les changements qui ne demandent pas de nouvelle version [#changes-that-do-not-need-a-new-version] Matchai peut livrer ces changements en tout temps, sans nouvelle version et sans autre avis que le [journal des modifications](https://matchai.co/docs/fr/developers/changelog) : - De nouveaux points de terminaison, de nouveaux types d'événements webhook et de nouvelles portées. Une connexion n'obtient jamais une portée qui ne lui a pas été accordée. - De nouveaux champs de requête facultatifs et de nouveaux paramètres de requête. - De nouveaux champs dans les réponses et dans le contenu des événements webhook. - De nouvelles valeurs dans une énumération, comme un nouveau `status`, une nouvelle profession ou un nouveau type d'événement. - De nouveaux codes d'erreur et de nouveaux types d'erreurs. - Un ordre différent des champs dans un objet JSON. - Des changements de longueur ou de format des identifiants et des curseurs. Les identifiants sont opaques. - La correction d'un comportement qui ne correspondait pas à cette documentation. Écrivez donc votre client pour qu'il s'y attende : - **Ignorez les champs que vous ne connaissez pas.** - **Traitez une valeur d'énumération inconnue comme « autre ».** Ne plantez pas, et n'essayez pas de deviner son sens. - **N'analysez et ne construisez jamais d'identifiants.** Conservez-les et renvoyez-les tels quels. - **Basez-vous sur le `code` d'une erreur, et rabattez-vous sur son `type` et son statut** quand vous rencontrez un code que vous ne connaissez pas. Consultez [Erreurs](https://matchai.co/docs/fr/developers/errors). - **Ignorez les événements webhook que vous ne traitez pas.** Répondez `2xx` et passez à autre chose. ## Changements incompatibles [#breaking-changes] Un changement incompatible est un changement qui peut empêcher une intégration correcte de fonctionner. Ces changements sont toujours livrés dans une nouvelle version majeure, à côté de l'ancienne : - Retirer ou renommer un point de terminaison, un champ, un paramètre de requête, une valeur d'énumération, un type d'événement ou une portée. - Changer le type, le format ou le sens d'un champ existant. - Rendre obligatoire un champ de requête facultatif, ou ajouter un nouveau champ obligatoire. - Refuser des requêtes qui étaient acceptées auparavant, en resserrant la validation. - Changer le statut HTTP ou le `code` que produit une situation existante. - Changer le fonctionnement de l'authentification, ou restreindre ce qu'une portée permet. Une nouvelle version majeure, comme `/v2`, fonctionne à côté de `/v1`. Elle ne remplace jamais `/v1` sur place, et rien n'y est transféré à votre place. ## Mise en obsolescence [#deprecation] Matchai ne retire pas une version, un point de terminaison ou un champ sans vous en aviser d'abord. Une mise en obsolescence est **annoncée à l'avance dans le journal des modifications**, et chaque avis indique : - ce qui est retiré, et ce qui le remplace; - comment faire la transition; - ce que vous devez faire, s'il y a lieu. L'avis est publié bien avant que l'ancien comportement soit retiré, pour vous laisser le temps de faire la transition. Lisez le [journal des modifications](https://matchai.co/docs/fr/developers/changelog) quand vous planifiez une mise en production, et quand vous n'avez pas eu de nouvelles depuis un moment. ## Le serveur MCP a ses propres versions [#the-mcp-server-is-versioned-separately] Le [serveur MCP](https://matchai.co/docs/fr/developers/mcp-server) indique sa propre version dans `serverInfo.version`, un numéro de version sémantique qui change quand un outil ou un champ est ajouté ou change de forme. Les outils sont décrits à l'assistant chaque fois qu'il se connecte, alors un client bien conçu découvre les nouveaux outils sans aucun changement de votre côté. Là où les changements et les mises en obsolescence sont annoncés. Comment gérer des codes dont la liste peut s'allonger avec le temps. Le contrat de /v1, et le fichier OpenAPI à télécharger. ## Sitemap - [Toutes les pages de la documentation Matchai](https://matchai.co/docs/sitemap.md) - [llms.txt](https://matchai.co/docs/fr/llms.txt)