API BCE especificación OpenAPI para Postman y clientes
Especificación OpenAPI de API BCE: descarga el documento OpenAPI 3 para generar un cliente tipado, importar la API en Postman o Insomnia, o explorarla.
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-KeyandX-API-Secretheader. - 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.
Sacar partido de la especificación OpenAPI de API BCE#
La especificación describe los endpoints, los parámetros y las respuestas en un formato estándar. Por eso sirve para mucho más que leer. Primero, genera un cliente tipado en tu lenguaje y evita errores en los nombres de campos. Luego, importa la especificación en Postman o Insomnia para explorar la API con tu equipo. Además, puedes usarla como base para tus mocks en los tests.
Existen dos fuentes. El archivo /assets/openapi-v2.json describe la v2. La versión en directo, en https://companybelgium.be/api/openapi/{lang}, se mantiene siempre al día en francés, inglés y neerlandés.
Buenas prácticas#
- Guarda en tu repositorio la copia de la especificación que usaste para generar el cliente.
- Regenera el cliente cuando el registro de cambios anuncie campos nuevos.
- En Postman, guarda
X-API-KeyyX-API-Secretcomo variables de la colección. - Configura el generador para que tolere propiedades adicionales en las respuestas.
- Crea un entorno de prueba con la URL
https://api-bce.be/test/v2.
Errores frecuentes#
Un error habitual es compartir una colección de Postman con las claves incluidas. Por tanto, usa siempre variables y no exportes sus valores. Otro problema es generar el cliente una vez y olvidarlo. Con el tiempo, aparecen campos nuevos que tu cliente no conoce. Por último, algunos generadores producen tipos estrictos que rechazan valores null. Revisa esa opción, porque los campos de contacto valen null cuando no se conocen.
Ejemplo: tests con mocks generados
Muchos equipos generan un servidor simulado a partir de la especificación. Así los tests de interfaz no dependen de la red. Sin embargo, un mock generado devuelve datos genéricos. Por eso conviene combinarlo con el modo de prueba, que ofrece casos concretos como una quiebra o un 429. Primero, usa el mock para los tests rápidos de cada commit. Luego ejecuta una suite contra la API de prueba antes de cada despliegue. Por último, compara de vez en cuando tu copia de la especificación con la versión en directo. Una diferencia te avisa de campos nuevos que todavía no aprovechas.
Preguntas frecuentes sobre API BCE y OpenAPI#
¿Qué versión de OpenAPI usa API BCE?
La especificación es un documento OpenAPI 3, compatible con los generadores y visores habituales.
¿Qué generador conviene usar?
La documentación cita como ejemplos openapi-generator y openapi-typescript. En general, cualquier generador compatible con OpenAPI 3 sirve.
¿Existe la especificación en español?
La versión en directo está disponible en francés, inglés y neerlandés. Los nombres de campos y parámetros, en cualquier caso, son los mismos.