Vous intégrez des données d'entreprises belges dans un CRM, un ERP ou un formulaire d'inscription ? Notre API v2 ajoute des référentiels stables, la validation des numéros de TVA, un score de risque de paiement et surtout des webhooks en temps réel. Voici ce qui change, comment migrer depuis la v1 et les bonnes pratiques pour une intégration solide.
Pourquoi une API v2 ?
La première version a tenu sa promesse : exposer proprement les données BCE et les enrichissements Espero-Soft. Mais l'usage nous a appris deux choses. D'abord, les intégrateurs veulent du push plutôt que du polling. Ensuite, ils préfèrent des référentiels stables à un paquet de codes à traduire à chaque appel.
Reference Data : des référentiels à mettre en cache
Les codes NACE, les formes juridiques et les groupes d'activité disposent désormais d'endpoints dédiés. Tous les chemins ci-dessous commencent par /api/v2 :
- GET /reference/nace-codes?lang=fr
- GET /reference/juridical-forms?lang=nl
- GET /reference/activity-groups?lang=en
Ces tables changent rarement. Chargez-les donc une fois, puis gardez-les en cache côté client : notre API v2 fournit un en-tête ETag et un Cache-Control de 24 h. Vous ne demandez plus la signification d'un code à chaque recherche d'entreprise, car le dictionnaire reste en mémoire. De plus, l'ETag vous permet de vérifier si une table a changé avant de la télécharger à nouveau.
Validation des numéros de TVA belges
Endpoint très demandé : POST /vat/validate. Il renvoie la version normalisée du numéro, son statut (valide, invalide ou format incorrect) et le numéro d'entreprise associé. En Belgique, le numéro de TVA reprend le numéro d'entreprise BCE à dix chiffres, précédé de BE. Validez-le dès le formulaire d'inscription, avant de créer le client dans votre base ou d'émettre une facture électronique via Peppol.
Score de risque de paiement
La route GET /companies/{enterpriseNumber}/payment-risk renvoie un score de 0 à 100 et une catégorie : faible, modéré, élevé ou critique. Notre API v2 calcule ce score à partir de signaux agrégés : âge de l'entreprise, taille, secteur, situation comptable et événements BCE récents.
Un widget prêt à l'emploi permet aussi d'afficher ce score dans votre back-office sans tout développer. Utilisez-le comme un signal d'alerte, par exemple pour exiger un acompte, et non comme un verdict automatique.
API v2 : des webhooks en temps réel
C'est la nouveauté la plus structurante. Vous vous abonnez aux événements qui vous intéressent :
- 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é, dans l'en-tête X-Espero-Signature. En cas d'échec, nous relançons l'envoi avec un délai exponentiel pendant 24 h. Une page d'administration permet en outre de rejouer un événement manuellement.
Bonnes pratiques côté récepteur
- Vérifiez la signature sur le corps brut de la requête, avant tout traitement.
- Répondez vite avec un code 2xx, puis traitez l'événement en arrière-plan.
- Gérez les doublons : un nouvel essai peut livrer deux fois le même événement.
- Surveillez les échecs et rejouez les événements manqués depuis la page d'administration.
Authentification et quotas
L'authentification repose toujours sur une paire clé publique et clé secrète (pk_live_... et sk_live_...), inchangée depuis la v1. Gardez la clé secrète côté serveur, jamais dans une application mobile ou un script front. Par ailleurs, les quotas augmentent sur notre API v2 et le compteur reste visible en temps réel dans votre tableau de bord.
Migration depuis la v1
La v1 reste supportée jusqu'à fin 2026 et les endpoints v2 fonctionnent en parallèle. Dans la majorité des cas, la migration tient en trois gestes :
- remplacer /api/ par /api/v2/ dans vos URL ;
- ajouter l'en-tête Accept: application/json (recommandé) ;
- relire les réponses enrichies : elles contiennent plus de champs par défaut, jamais moins.
Testez d'abord la bascule sur un environnement de préproduction, puis migrez le trafic de production progressivement.
Pour qui ?
Notre API v2 s'adresse aux développeurs, aux intégrateurs ERP, aux équipes data qui alimentent un entrepôt de données et aux cabinets qui industrialisent la collecte d'informations clients. Bref, à tous ceux qui ne veulent plus coder leur propre connecteur BCE. Attention cependant : les données des entrepreneurs personnes physiques restent des données personnelles, soumises au RGPD.
Quelques usages typiques :
- Onboarding client : pré-remplir la fiche à partir du numéro d'entreprise et valider la TVA.
- Gestion du risque : recevoir un webhook dès qu'un client change de statut.
- Comptabilité : savoir quand un client dépose de nouveaux comptes annuels.
Besoin d'aide pour brancher ces flux sur vos outils ? Notre équipe de développement IT sur mesure peut réaliser l'intégration pour vous.
