Documentation / OpenAPI spec

API BCE OpenAPI specification for Postman and SDK clients

API BCE OpenAPI specification: download the OpenAPI 3 document to generate a typed client, import the API into Postman or Insomnia, or browse it.

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.

What to do with the API BCE specification#

An OpenAPI 3 document describes every route, parameter and response. As a result, many tools can read it directly, without manual setup.

  • Typed clients: generate bindings with openapi-generator or openapi-typescript.
  • API clients: import the API into Postman or Insomnia in a few clicks.
  • Contract tests: validate real responses against the schemas in your test suite.
  • Internal docs: browse the endpoints in any OpenAPI viewer your team already uses.

In addition, a shared specification gives backend, frontend and QA teams the same vocabulary. So, reviews and bug reports refer to the exact field names that the API returns.

Choosing the right file#

Two sources exist. The static file /assets/openapi-v2.json suits builds, because you can pin it in your repository. In contrast, the live document at https://companybelgium.be/api/openapi/{lang} is always current and comes in French, English and Dutch. Therefore, a good routine is to pin the static copy and compare it with the live one from time to time. That way, you spot new fields before you need them.

Pitfalls with generated clients#

First, a generated client does not know your credentials. So, configure X-API-Key and X-API-Secret once, in a shared place. Second, fields without a value are omitted from responses, therefore generated models must mark them as optional. Third, strict deserialisers can fail when a new field appears. Instead, set them to ignore unknown properties.

In Postman, also store both credentials as collection variables. As a result, they never end up in a shared request or an exported file.

Keeping generated code up to date#

A generated client ages like any dependency. Therefore, regenerate it when the changelog announces new fields or routes, then run your tests. In addition, commit the spec file next to the generated code, so a reviewer sees what changed. For example, a diff on the spec shows a new optional field in a few lines, while the generated diff can be long. Finally, wrap the generated client in a thin layer of your own. As a result, your business code does not depend on generator details.

API BCE OpenAPI FAQ#

Is there an official SDK for API BCE?

The documentation does not list one. Instead, generate a typed client from the OpenAPI 3 document in the language you use.

In which languages is the live specification available?

The live document exists in French, English and Dutch, through the {lang} segment of its URL.

Can I use the specification with the test API?

Yes. The test API serves the same routes, so change the server URL to https://api-bce.be/test/v2 and use a test key.