Documentatie / OpenAPI-spec

API BCE OpenAPI-specificatie voor Postman en clients

OpenAPI-specificatie van API BCE: download het OpenAPI 3-document om een getypeerde client te genereren of de API in Postman of Insomnia te importeren.

The whole API is described by an OpenAPI 3 document. Use it to generate clients, import the API into Postman or Insomnia, or browse it in any OpenAPI viewer.

Download the spec#

  • v2 (current): /assets/openapi-v2.json
  • Live, always current & multilingual: https://companybelgium.be/api/openapi/{lang} (fr · en · nl)

Generate a client#

Point any generator at the spec, e.g. with openapi-generator or openapi-typescript, to get typed bindings in your language.

Import into Postman#

  • Postman → Import → Link, then paste the spec URL.
  • Add a collection-level X-API-Key and X-API-Secret header.
  • Store both as collection variables so they never end up in shared requests.
ℹ️

Want to try calls without leaving the docs? Open the API Playground.

De OpenAPI-specificatie van API BCE in je workflow#

Het OpenAPI 3-document beschrijft alle endpoints, parameters en antwoorden. Je gebruikt het dus niet alleen om te lezen. Het is vooral een bouwsteen voor tooling. Er bestaat geen officiële SDK, maar met een generator maak je zelf een getypeerde client in je eigen taal.

Teams gebruiken de specificatie meestal op een van deze manieren:

  • Clientgeneratie: met openapi-generator of openapi-typescript types en functies genereren.
  • Verkenning: de API importeren in Postman of Insomnia om verzoeken handmatig te proberen.
  • Contracttests: in je CI controleren of je code nog overeenkomt met de gepubliceerde structuur.
  • Documentatie: de specificatie in een eigen OpenAPI-viewer tonen voor je interne team.

Goede praktijken bij clientgeneratie#

Genereer de client in een apart pakket of map. Zo blijft gegenereerde code gescheiden van je eigen logica. Bovendien kun je de client dan opnieuw genereren zonder iets te overschrijven. Leg daarnaast de versie van de specificatie vast in je repository. Zo zie je bij een update meteen welke wijzigingen er zijn.

Kies vervolgens bewust tussen de twee bronnen. Het bestand /assets/openapi-v2.json is een vaste kopie van v2. De live-versie op https://companybelgium.be/api/openapi/{lang} is altijd actueel en bestaat in het Frans, Engels en Nederlands. Voor reproduceerbare builds is een vaste kopie meestal veiliger.

Valkuilen#

Een gegenereerde client regelt meestal geen authenticatie voor je. Voeg de headers X-API-Key en X-API-Secret dus zelf toe, bij voorkeur op één centrale plaats. In Postman zet je ze ten slotte als collectievariabelen. Zo komen je sleutels nooit in gedeelde verzoeken terecht.

Let ook op strikte types. Velden zonder waarde worden weggelaten, en nieuwe velden kunnen bijkomen. Configureer je generator daarom zodat optionele en onbekende velden geen fouten geven. Zie ook de pagina Versies.

Voeg bovendien een time-out en je eigen foutafhandeling toe rond de gegenereerde functies. Een generator maakt de oproepen, maar weet niets van je beleid voor opnieuw proberen. Schrijf daarom een dunne laag erboven. Die laag leest de HTTP-status, past backoff toe bij een 429 of 5xx en logt fouten zonder je secret.

Veelgestelde vragen over API BCE en OpenAPI#

Bestaat er een officiële SDK voor API BCE?

Nee. Je genereert zelf een client uit het OpenAPI 3-document, of je gebruikt gewoon een HTTP-client in je taal.

Welke versie van de specificatie gebruik ik?

Voor reproduceerbare builds de vaste kopie /assets/openapi-v2.json. Wil je altijd de nieuwste beschrijving, gebruik dan de live-versie per taal.

Hoe stel ik authenticatie in Postman in?

Importeer de specificatie via een link en voeg op collectieniveau de headers X-API-Key en X-API-Secret toe, als collectievariabelen.