Documentation / Spécification OpenAPI

API BCE : spécification OpenAPI 3 pour Postman et clients

Spécification OpenAPI API BCE : téléchargez le document OpenAPI 3 pour générer un client typé, importer l’API dans Postman ou Insomnia, ou l’explorer.

Toute l’API est décrite par un document OpenAPI 3. Utilisez-le pour générer des clients, importer l’API dans Postman ou Insomnia, ou l’explorer dans n’importe quel visualiseur OpenAPI.

Télécharger la spécification#

  • v2 (actuelle) : /assets/openapi-v2.json
  • En direct, toujours à jour & multilingue : https://companybelgium.be/api/openapi/{lang} (fr · en · nl)

Générer un client#

Pointez n’importe quel générateur vers la spécification, par exemple openapi-generator ou openapi-typescript, pour obtenir des bindings typés dans votre langage.

Importer dans Postman#

  • Postman → Import → Link, puis collez l’URL de la spécification.
  • Ajoutez un en-tête X-API-Key et X-API-Secret au niveau de la collection.
  • Stockez-les comme variables de collection pour qu’ils n’apparaissent jamais dans les requêtes partagées.
ℹ️

Envie de tester des appels sans quitter la doc ? Ouvrez le Playground API.

Tirer parti de la spécification OpenAPI API BCE#

La spécification OpenAPI est la description la plus complète des endpoints. Elle sert d’abord à générer du code, mais pas seulement. Par exemple, elle alimente vos tests de contrat, votre documentation interne ou votre passerelle d’API. Ainsi, une seule source de vérité décrit l’intégration pour toute l’équipe.

  • Client typé : générez des types avec openapi-typescript ou un client complet avec openapi-generator.
  • Tests de contrat : vérifiez que les réponses reçues respectent les schémas de la spécification.
  • Exploration : importez l’API dans Postman ou Insomnia pour la parcourir sans écrire de code.
  • Documentation interne : intégrez la spécification dans le portail de votre équipe.

Choisir la bonne version du document#

Deux sources sont proposées. Le fichier /assets/openapi-v2.json est stable : versionnez-en une copie dans votre dépôt. Vous savez alors exactement contre quel contrat votre code a été généré. En revanche, la version en direct https://companybelgium.be/api/openapi/{lang} est toujours à jour et disponible en français, anglais et néerlandais. Elle convient mieux à l’exploration et à la détection de nouveautés.

Bonnes pratiques de génération#

D’abord, régénérez votre client dans une tâche dédiée, puis relisez le diff avant de l’intégrer. Ensuite, configurez le générateur pour tolérer les champs inconnus. En effet, la politique de versions permet d’ajouter des champs dans la v2. Enfin, enveloppez le client généré dans votre propre module. Vous y ajouterez l’authentification, les nouveaux essais et la lecture de l’enveloppe, sans modifier le code produit par le générateur.

Côté Postman, stockez la clé et le secret comme variables de collection. Ils n’apparaîtront donc jamais dans une requête partagée.

Garder votre client API BCE synchronisé#

Un client généré vieillit vite si personne ne le met à jour. Automatisez donc la comparaison : une tâche récupère la spécification en direct, la compare à la copie versionnée et signale les différences. Ensuite, un développeur décide s’il faut régénérer le client. Ainsi, vous découvrez les nouveaux endpoints sans attendre une demande métier. Par ailleurs, la spécification en direct existe en trois langues. Choisissez-en une pour la génération et gardez-la, sinon les descriptions changeraient à chaque comparaison.

Questions fréquentes sur OpenAPI et API BCE#

Existe-t-il un SDK officiel ?

Cette documentation ne mentionne pas de SDK officiel. La méthode proposée consiste à générer un client depuis la spécification OpenAPI 3.

La spécification couvre-t-elle la v1 ?

Le fichier proposé au téléchargement décrit la v2. Les endpoints v1 hérités sont listés dans la page Versions.

Puis-je pointer l’API de test depuis un client généré ?

Oui, puisque l’API de test reprend les mêmes routes. Configurez simplement l’URL de base sur https://api-bce.be/test/v2 avec une clé de test.