Recherche API / Documentation (Swagger)
Recherche API / Documentation (Swagger)
Parcourez, trouvez et comprenez les routes et schémas exposés par l’API
Consultez la documentation intégrée, recherchez une operationId, et vérifiez si une route demande des règles de sécurité. Utile pour développeurs et intégrateurs qui doivent comprendre et réutiliser les routes disponibles.
Courte introduction La fonctionnalité “Recherche API / Documentation (Swagger” vous permet de consulter la documentation interactive de l’API, de rechercher une opération précise (operationId) et de savoir si une route requiert un niveau de sécurité particulier. C’est l’outil pratique pour retrouver rapidement les routes, leurs paramètres et les schémas des requêtes/réponses.
Note importante : l’accès à l’interface Swagger est désormais restreint côté serveur via AppServiceProvider. Selon l’environnement et la configuration de l’application, la page de documentation peut être désactivée ou restreinte (renvoi 404/403) pour les utilisateurs non autorisés. Si vous ne parvenez pas à y accéder, consultez la section FAQ ci‑dessous pour les actions possibles.
De plus, la définition Swagger a été modifiée pour marquer le paramètre session_id comme required : il apparaîtra désormais comme obligatoire dans l’interface et dans les snippets auto‑générés pour les opérations concernées (notamment certains callbacks et endpoints de paiement). Veillez à fournir ce paramètre lors de vos tests et intégrations.
Nouveaux endpoints API : Growth Limit, Horiio, URSSAF Payments, Qonto et paramètre attach_invoice
Depuis la mise à jour du RouteServiceProvider, plusieurs groupes de routes supplémentaires sont exposés dans la documentation Swagger :
-
Growth Limit
- operationId exposés : growthLimit.check, growthLimit.report
- Exemples d’URL (référencées dans Swagger) : /api/growth-limit/check, /api/growth-limit/report
- Sécurité : ces endpoints exigent une authentification API (Bearer token / security scheme “bearerAuth”) et peuvent également déclarer une extension feature_flag nommée “growth_limit”. Le contrôle du flag est appliqué par FeatureFlagGuardMiddleware (clé ‘feature’) et, si le flag n’est pas actif pour l’application, l’accès renvoie un 404.
-
Horiio
- operationId exposés : horiio.webhook, horiio.callback
- Exemples d’URL (référencées dans Swagger) : /api/horiio/webhook, /api/horiio/callback
- Sécurité : ces endpoints sont destinés à des webhooks et sont protégés par une vérification de signature envoyée via un en-tête (ex. X-Horiio-Signature). La documentation Swagger précise l’en-tête attendu et la méthode de vérification. Ces routes peuvent être publiques côté réseau mais requièrent la signature correcte pour être acceptées.
-
URSSAF Payments (mise à jour)
- Objet : la définition Swagger a été mise à jour pour les opérations liées aux paiements URSSAF. Les chemins concernés apparaissent sous /api/urssaf/payments dans la documentation.
- operationId exposés (exemples — vérifiez la définition pour les noms exacts) : urssaf.payments.create, urssaf.payments.status, urssaf.payments.callback.
- Exemples d’URL (référencées dans Swagger) : /api/urssaf/payments, /api/urssaf/payments/{paymentId}, /api/urssaf/payments/callback
- Sécurité et mapping : ces endpoints requièrent une authentification API (Bearer token / “bearerAuth”) ; les callbacks peuvent également exiger une signature via en‑tête. Notez que certains operationId et schémas request/response ont été modifiés lors de cette mise à jour : vérifiez attentivement les noms d’operationId, les champs obligatoires et les codes de réponse avant d’intégrer ou de déployer des mappings automatiques. Si vous maintenez un tableau de correspondance (mapping) entre operationId et vos traitements internes, adaptez‑le aux nouveaux operationId et aux éventuels changements de payload (ex. champ d’identifiant, structure du statut).
-
Sales Documents (mise à jour)
- Objet : la définition Swagger a été mise à jour pour les endpoints relatifs aux documents commerciaux (schéma SalesDocumentModel). Les chemins concernés apparaissent sous /api/sales/documents dans la documentation.
- operationId exposés (exemples — vérifiez la définition pour les noms exacts) : sales.documents.create, sales.documents.update, sales.documents.get, sales.documents.search.
- Exemples d’URL (référencées dans Swagger) : /api/sales/documents, /api/sales/documents/{documentId}, /api/sales/documents/search
- Sécurité et schéma : ces endpoints requièrent une authentification API (Bearer token / “bearerAuth”). Le schéma SalesDocumentModel a été modifié — de nouvelles propriétés et/ou champs requis peuvent avoir été ajoutés ou renommés. Avant d’intégrer ces endpoints ou de générer des clients, vérifiez attentivement la définition du modèle, les champs obligatoires et les exemples fournis dans Swagger.
-
Qonto (nouveau service)
- Objet : ajout d’un groupe de routes pour l’intégration Qonto (flux OAuth, enregistrement et webhooks).
- operationId exposés (exemples) : qonto.oauth.authorize, qonto.oauth.callback, qonto.webhook, qonto.registration, qonto.registration.confirm
- Exemples d’URL (référencées dans Swagger) : /api/qonto/oauth/authorize, /api/qonto/oauth/callback, /api/qonto/webhook, /api/qonto/registration, /api/qonto/registration/confirm
- Sécurité et usage :
- OAuth : le flux OAuth comprend une route d’autorisation (qonto.oauth.authorize) qui initie la redirection vers Qonto, et une route de callback (qonto.oauth.callback) qui reçoit le code d’autorisation et l’état (state). Consultez la fiche opération pour les paramètres attendus (state, redirect_uri) et le comportement en cas d’erreur.
- Webhooks : les événements entrants sont exposés via qonto.webhook et attendent une vérification de signature transmise dans un en‑tête (ex. X-Qonto-Signature). La documentation précise l’en‑tête attendu et la méthode de vérification.
- Enregistrement : les opérations d’enregistrement (qonto.registration et qonto.registration.confirm) exigent généralement une authentification API (Bearer token / “bearerAuth”) ; la route de confirmation complète le flux d’inscription. Consultez la fiche de chaque opération dans Swagger pour connaître les exigences exactes d’en‑têtes, d’authentification et le format des payloads.
-
Paramètre attach_invoice (nouveau)
- Objet : un nouveau paramètre attach_invoice a été ajouté à certains endpoints d’envoi de factures (ex. endpoints d’envoi individuel et en masse de factures sous /api/accounting/billing/…).
- Type et usage : il s’agit d’un indicateur boolean (true/false) — ce paramètre est exposé comme paramètre de requête (query) nommé attach_invoice et indique si la facture PDF doit être jointe au message/envoi. Vérifiez s’il est requis dans la définition.
- Remarque connexe : la définition Swagger marque désormais également le paramètre session_id comme obligatoire (required) pour certaines opérations (notamment des callbacks et des endpoints de paiement) ; la fiche d’opération indiquera “required” et l’interface vous demandera de le fournir dans les exemples/snippets auto‑générés.
Capacités clés
Charger et mettre en cache le YAML
Charge la définition Swagger et la met en cache pour accélérer les recherches et réduire les temps d’attente. Le mécanisme de cache utilise désormais un résolveur de clés (CacheKeyResolver) et un stockage dédié (CacheStorage) : la clé intègre des informations d’environnement et un identifiant lié au contenu du fichier resources/swagger.yaml (hash/mtime), ce qui évite les collisions entre environnements. Si vous modifiez le YAML, utilisez l’option “forcer la mise à jour” ou purgez le cache applicatif côté serveur (voir FAQ). Attention : la définition peut également être mise en cache côté client (Nuxt runtime / service worker ou cache HTTP). Si la mise à jour côté serveur est correctement effectuée mais que vous voyez encore l’ancienne version dans le navigateur, il peut être nécessaire d’invalider le cache navigateur/service worker (hard reload, désenregistrer le service worker ou vider les données du site).
Rechercher par operationId
Retrouvez en un clic la route, la méthode HTTP, les paramètres attendus et les exemples associés à un operationId précis.
Vérifier la sécurité d’une route
Identifiez si la route nécessite authentification, logging, une feature flag ou autres règles (ex. limitation, désactivation de la sanitisation). Les routes peuvent utiliser une extension de sécurité “feature_flag” indiquant qu’une fonctionnalité doit être active pour accéder à l’endpoint. Le contrôle est effectué par le middleware FeatureFlagGuardMiddleware (enregistré sous la clé ‘feature’ dans app/Http/Kernel.php) qui renvoie un 404 si la fonctionnalité est désactivée ou si l’application n’est pas autorisée.
Consulter schémas et exemples
Affiche les schémas de requête/réponse, les champs obligatoires et les exemples pour implémenter ou tester rapidement.
Trouver l’operationId à partir d’un contrôleur
Recherchez par nom de contrôleur ou d’action pour obtenir l’operationId utilisable dans vos scripts ou générateurs.
Navigation pour intégrateurs
Interface pensée pour les développeurs et intégrateurs : recherche textuelle, filtres et vue détaillée d’une opération.
How to use it
Suivez ces étapes pour les actions principales : charger la documentation, rechercher une opération, vérifier la sécurité et récupérer un operationId.
Étapes détaillées
Ouvrir la documentation API
- Aller dans le menu “Développeurs” (ou “API / Documentation”) de l’application.
- Cliquez sur “Documentation API” ou “Explorateur API”.
- Ce panneau affiche la liste des routes et un champ de recherche en haut.
- Résultat : vous voyez l’arborescence des routes et un bouton pour charger/rafraîchir la définition.
- Remarque importante : l’accès à cette interface peut être restreint côté serveur (AppServiceProvider). Si la page renvoie un 404 ou 403, cela signifie que la documentation est désactivée ou non accessible depuis votre environnement/utilisateur. Dans ce cas, utilisez un environnement de développement/local ou contactez l’équipe d’exploitation pour obtenir l’accès.
Charger / rafraîchir le contenu Swagger (YAML)
- Si la documentation n’est pas encore chargée, cliquez sur “Charger la définition” ou sur l’icône de rafraîchissement.
- Optionnel : cochez “forcer la mise à jour” si vous savez qu’une définition a été modifiée récemment. Cette option demande au backend d’ignorer la version mise en cache et de re-parcourir le fichier resources/swagger.yaml pour régénérer la clé de cache liée au contenu.
- Ce que vous verrez ensuite : barre de progression, puis la liste complète des chemins et schémas. Le contenu est mis en cache pour accélérer les recherches.
- Si après un “forcer la mise à jour” vous voyez toujours une version ancienne, il est possible que la cache applicative persistante doive être purgée côté serveur (ex. php artisan cache:clear) ou que le fichier resources/swagger.yaml doive être modifié/touché pour mettre à jour son horodatage. En outre, la configuration runtime du front (Nuxt) peut mettre en cache la route /api/swagger.yaml (service worker, cache HTTP ou runtime caching). Dans ce cas, effectuez un hard reload (Ctrl/Cmd+F5), désenregistrez le service worker depuis les outils de développement, videz les données du site ou ajoutez temporairement un paramètre de cache-busting (ex. /api/swagger.yaml?ts=…) pour forcer le chargement d’une nouvelle version. Le cache utilise maintenant des clés dépendant de l’environnement et du contenu du YAML, ce qui réduit les risques de collision entre environnements.
Rechercher une opération par operationId
- Dans le champ de recherche, collez ou tapez l’operationId (ou une partie du nom). Vous pouvez aussi chercher par mot-clé lié à l’action (ex. “invoices.list”).
- Appuyez sur Entrée ou cliquez sur l’icône loupe.
- Résultat : la vue se positionne sur la route trouvée et affiche méthode HTTP, URL, description, paramètres, corps attendu et exemples.
Vérifier si une route requiert une sécurité spécifique
- Dans la fiche d’une opération, cherchez la section “Sécurité” ou “Security”.
- Vous verrez des mentions claires comme : “Authentification requise”, “Logging activé”, “Sans sanitisation”, “Limitation appliquée” — et éventuellement une extension “feature_flag”.
- Si une route déclare une feature_flag, la documentation indique le nom du flag (par ex. “facturx_v2”). Ce flag signifie que l’accès dépend d’une configuration de fonctionnalité côté serveur.
- Le middleware chargé de ce contrôle s’appelle FeatureFlagGuardMiddleware et est exposé comme middleware de route sous la clé ‘feature’ dans app/Http/Kernel.php. Il vérifie la configuration (config/features.php) et, si le flag est une liste d’apps, tente de retrouver l’identifiant de l’application dans la requête (paramètre de route, champ de requête ou attribut de requête). Si le contrôle échoue, la requête est interrompue par un 404 afin de masquer l’existence de l’endpoint.
- Action : notez les exigences (par ex. token d’authentification, en-têtes à fournir) et vérifiez si la feature_flag doit être activée pour l’app avant d’utiliser la route.
Trouver l’operationId depuis le nom du contrôleur / action
- Si vous connaissez le nom du contrôleur ou de l’action (par ex. “TransactionsController@list”), utilisez le filtre “Par contrôleur” ou saisissez le nom dans la recherche.
- La documentation affiche alors l’operationId correspondant ; copiez‑le pour l’utiliser dans vos scripts, tests ou génération de client.
- Astuce : la recherche accepte des fragments de nom — pratique si vous ne connaissez pas l’orthographe exacte.
Consulter et réutiliser les schémas (request/response)
- Dans la fiche opération, ouvrez les onglets “Paramètres”, “Request body” et “Responses”.
- Identifiez les champs obligatoires (required) et les types (string, integer, objets imbriqués).
- Vous pouvez copier un exemple JSON pour le coller dans vos outils de test ou pour générer des modèles de données.
- Remarque importante : certaines définitions ont récemment été modifiées (ex. modèles liés aux paiements URSSAF et au modèle SalesDocumentModel). Vérifiez toujours la version actuelle du schéma dans Swagger : de nouvelles propriétés ou champs requis peuvent impacter vos intégrations. Notez également l’ajout de nouveaux endpoints pour le service Qonto (flux OAuth, webhooks et flux d’enregistrement comprenant une route de confirmation) et l’introduction du paramètre attach_invoice (paramètre de requête “attach_invoice”, boolean) pour certains endpoints d’envoi de factures — vérifiez leur emplacement exact et leur type dans la définition.
- À noter spécifiquement : le paramètre session_id est désormais marqué comme required dans la définition Swagger pour certaines opérations (notamment callbacks et endpoints de paiement) ; la fiche d’opération indiquera ce statut et les snippets/examples générés le noteront comme obligatoire.
Utiliser un operationId pour générer de la documentation ou des clients
- Copiez l’operationId depuis la fiche opération.
- Collez‑le dans votre outil de génération (ou transmettez‑le à l’intégrateur) pour produire stubs, tests ou documentation ciblée.
- Vérifiez la section “Sécurité” et ajoutez les en‑têtes requis lors de la génération.
Astuce pro
Si vous travaillez sur plusieurs environnements (staging/production), rafraîchissez la définition seulement après une mise à jour officielle. Conservez une copie locale de l’exemple de requête pour accélérer vos tests. Utilisez l’operationId copié pour lier facilement vos tests automatisés à la documentation.
Limites et règles importantes
- Le contenu Swagger est mis en cache pour améliorer les performances : il peut donc ne pas refléter les modifications récentes tant que vous n’avez pas forcé un rafraîchissement.
- Le mécanisme de cache utilise désormais un résolveur et un stockage dédiés ; la clé de cache tient compte de l’environnement et du contenu du fichier resources/swagger.yaml, ce qui réduit les risques de collisions entre environnements mais peut nécessiter une purge explicite du cache applicatif si la version affichée reste obsolète malgré un rafraîchissement via l’UI. Pour forcer une purge côté serveur, exécutez la commande de nettoyage du cache applicatif (ex. php artisan cache:clear) ou mettez à jour/touchez le fichier resources/swagger.yaml lors d’un déploiement.
- De plus, la configuration runtime du front (Nuxt) peut mettre en cache la ressource exposée (/api/swagger.yaml) via un service worker, un cache HTTP ou un mécanisme de runtime caching déclaré dans nuxt.config.ts. Si la version côté serveur est mise à jour mais que vous continuez à voir l’ancienne version dans votre navigateur, effectuez un hard reload, désenregistrez le service worker (DevTools > Application > Service Workers), videz les données du site ou utilisez un paramètre de cache-busting (ex. /api/swagger.yaml?ts=…) pour contourner le cache client.
- Les vérifications de sécurité et les indications (ex. “authentification requise”) proviennent de la définition Swagger : si la définition est incorrecte, les indications peuvent être inexactes. Toujours valider en testant la route avec les en-têtes d’authentification appropriés.
- L’accès à l’interface Swagger peut être restreint par AppServiceProvider : dans certains environnements (notamment en production) la documentation peut être désactivée ou retournée comme introuvable/non autorisée. Si vous rencontrez un 404/403 en tentant d’ouvrir la documentation, suivez les consignes de la FAQ pour obtenir ou rétablir l’accès.