API v2 données entreprises belges + Webhooks

Pourquoi une v2 ?

Notre API v1 a tenu sa promesse : exposer proprement les données BCE et les enrichissements Espero-Soft. Mais l'usage nous a appris deux choses — les intégrateurs veulent du push plutôt que du polling, et ils veulent des référentiels stables plutôt qu'à chaque appel un paquet de codes à traduire.

Reference Data

Les codes NACE, les formes juridiques et les groupes d'activité sont désormais accessibles via des endpoints dédiés :

• GET /api/v2/reference/nace-codes?lang=fr
• GET /api/v2/reference/juridical-forms?lang=nl
• GET /api/v2/reference/activity-groups?lang=en

Ces tables changent rarement. Elles ont vocation à être cachées côté client (ETag + Cache-Control 24 h fournis). Vous ne demandez plus « décrivez-moi ce code » à chaque lookup d'entreprise : vous avez le dictionnaire en mémoire.

Validation de numéro de TVA belge

Endpoint très demandé : POST /api/v2/vat/validate. Il renvoie la version normalisée, le statut (valide / invalide / format incorrect), et le numéro d'entreprise associé. Utile pour valider un formulaire d'onboarding avant de créer un client en base.

Scoring du risque de paiement

GET /api/v2/companies/{enterpriseNumber}/payment-risk renvoie un score 0–100 et une catégorie (faible / modéré / élevé / critique), calculés à partir de signaux agrégés : âge de l'entreprise, taille, secteur, situation comptable, événements BCE récents.

Un widget front prêt à l'emploi est également disponible pour les équipes qui veulent intégrer visuellement l'information dans leur back-office sans tout construire.

Webhooks temps réel

La nouveauté la plus structurante. Vous pouvez vous abonner à des événements :

• company.updated
• company.status_changed
• company.filing_deposited
• establishment.created
• establishment.closed

Chaque événement part en POST vers votre URL, signé en HMAC SHA-256 avec un secret partagé. En-tête X-Espero-Signature. Retry exponentiel jusqu'à 24 h, page d'admin pour rejouer manuellement si besoin.

Authentification et quotas

L'authentification reste basée sur une paire clé publique + secret (pk_live_... / sk_live_...), inchangée depuis la v1. Les quotas sont plus généreux sur la v2, et le compteur est visible en temps réel dans votre tableau de bord.

Migration depuis la v1

La v1 reste supportée jusqu'à fin 2026. Les endpoints v2 sont disponibles en parallèle. Pour la majorité des cas :

• Remplacer /api/ par /api/v2/ dans vos URLs.
• Ajouter l'en-tête Accept: application/json (recommandé).
• Revoir les réponses enrichies (plus de champs par défaut, pas moins).

Pour qui ?

Les développeurs, les intégrateurs ERP, les data teams qui alimentent un data warehouse, les cabinets qui industrialisent leur collecte de données clients. Bref, tous ceux qui ne veulent plus coder leur propre connecteur BCE.