Ir al contenido
API BCEAPI BCEAPI de datos de empresas belgas
Casos de usoPreciosDocumentaciónSandboxObtener clave
🇬🇧 English🇫🇷 Français🇳🇱 Nederlands🇩🇪 Deutsch🇪🇸 Español
Obtener clave
API BCE / Casos de uso / Vigilar empresas mediante webhooks

🔔 Vigilar empresas mediante webhooks

Verificar a un tercero una sola vez no basta: un cliente se muda, un proveedor cesa su actividad. Los webhooks te avisan en lugar de obligarte a consultar la API.

El problema#

Una cartera de clientes o proveedores envejece. Las direcciones cambian, las denominaciones evolucionan, las empresas cesan su actividad. La primera idea es consultar la API cada noche para todas las empresas de la cartera: consume cuota, y la mayoría de las respuestas no cambian nada.

Los webhooks invierten la lógica: declaras una vez los números que vigilar y es la API la que llama a tu servidor cuando una ficha vigilada cambia en el registro.

Los datos de la API que responden#

  • POST /webhook: crea un webhook (nombre, URL de recepción, números que vigilar). El secret de firma HMAC solo se devuelve una vez, en esta respuesta.
  • POST /webhook/{id}/subscriptions y DELETE /webhook/{id}/subscriptions: añaden o retiran números de empresa o de establecimiento.
  • GET /webhook/{id}/subscriptions: la lista de números que vigila un webhook.
  • POST /webhook/{id}/trigger: envía una entrega de prueba para comprobar tu receptor y tu verificación de firma.
  • GET /webhook/{id}/events: el registro de los últimos 100 intentos de entrega, con estado, código de respuesta y marca de tiempo.
  • PATCH /webhook/{id}/hmac-secret: renueva el secret de firma; el anterior deja de ser válido de inmediato.

Cada evento indica su tipo (creación, modificación o desactivación de la ficha, o entrega de prueba), el número afectado y el tipo de entidad, y va firmado con el secret del webhook. La verificación de la firma se describe paso a paso en la guía de webhooks.

Ejemplo de petición#

"tok-comment"># 1. Create the webhook with a first enterprise to watch
"tok-comment">#    (the hmacSecret is returned only once: store it)
curl -X POST https://companybelgium.be/api/v2/webhook \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Portfolio watch","url":"https://example.be/hooks/bce","entityNumbers":["1033.022.383"]}'
"tok-comment">
# 2. Add more enterprise numbers later
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/subscriptions \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"entityNumbers":["<another enterprise number>"]}'
"tok-comment">
# 3. Send a test delivery, then read the delivery log
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/trigger \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"
curl https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/events \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Implementación recomendada#

  • Verifica la firma de cada entrega antes de tenerla en cuenta, sobre el cuerpo en bruto de la petición.
  • Responde rápido con un código 2xx y procesa después el evento en segundo plano: vuelve a leer la ficha con GET /enterprise/{num} para conocer su nuevo estado.
  • Haz que el procesamiento sea idempotente: una misma entrega puede llegar más de una vez.
  • Añade los números al webhook cuando un cliente o proveedor entra en tu cartera y retíralos cuando termina la relación.
  • Consulta el registro de entregas cuando tu receptor no estuvo disponible y lanza una entrega de prueba después de cada despliegue.

Límites que conviene conocer#

  • Los eventos siguen las actualizaciones publicadas por la BCE: llegan después de que un cambio se inscriba en el registro, no en el momento de la decisión.
  • Un webhook indica que una ficha ha cambiado; para conocer el nuevo valor de un campo, vuelve a leer la ficha.
  • Las entregas fallidas se reintentan, pero un receptor que permanece inaccesible puede perder eventos: el registro de los últimos 100 intentos ayuda a recuperarlos.
  • Los webhooks vigilan números concretos. No señalan las nuevas empresas de un sector o de una región.

Preguntas frecuentes#

¿Qué cambios activan un webhook?

La creación, modificación o desactivación de la ficha de una empresa o establecimiento vigilado, tal como lo publica la BCE, además de las entregas de prueba que tú lances.

¿Cómo proteger el receptor?

Cada entrega va firmada con HMAC usando el secret del webhook. Verifica la firma sobre el cuerpo en bruto antes de procesar el evento y renueva el secret si se filtra.

¿Se pueden vigilar establecimientos?

Sí. Las suscripciones aceptan números de empresa y de establecimiento.

Llevarlo a la práctica

Crea una clave en el portal de desarrolladores y sigue después la documentación de referencia de cada endpoint citado.

Obtener una clave APILeer la documentación

Documentación de referencia

  • Guía de webhooks
  • API de webhooks

Otros casos de uso

  • Verificar un cliente o proveedor antes de trabajar con él
  • Enriquecer automáticamente un CRM a partir del número de empresa
  • Validar un número de IVA (VIES) al introducir una factura
  • KYC/KYB al abrir una cuenta de empresa

En esta página

El problemaLos datos de la API que respondenEjemplo de peticiónImplementación recomendadaLímites que conviene conocerPreguntas frecuentesLlevarlo a la práctica
API BCEAPI BCE

Un producto para desarrolladores de Espero-Soft Informatiques, basado en datos abiertos oficiales BCE/KBO.

Producto

Casos de usoPor qué API BCEPreciosFAQ

Desarrolladores

DocumentaciónReferencia APIPlayground de la APIRegistro de cambiosObtener clave

Empresa

Datos, cumplimiento y Peppol ↗Company Belgium ↗Espero-Soft ↗

Legal

Aviso legalCondiciones generales de uso y de ventaPolítica de privacidadPolítica de cookies
© 2026 Espero-Soft Informatiques SRL · Todos los derechos reservados.Hecho en Bélgica 🇧🇪