Qu'est-ce qu'un vestigingsnummer ?

Deux numéros, deux questions

Les données d’entreprises néerlandaises utilisent deux identifiants qui se ressemblent et répondent à des questions complètement différentes. Les confondre est l’erreur de modélisation la plus courante que nous voyons dans les intégrations construites depuis l’extérieur des Pays-Bas.

Le mot vestiging signifie établissement ou lieu d’activité. Une hoofdvestiging est l’établissement principal, une nevenvestiging est tout autre site. Le registre n’emploie pas le mot « succursale » au sens juridique qu’il a dans certains pays, où une succursale est une entité immatriculée séparément d’une société mère étrangère. Une nevenvestiging néerlandaise n’est pas une entité juridique distincte, n’a pas de personnalité juridique propre et ne peut pas contracter en son nom.

Si vous travaillez déjà avec des données françaises, l’analogie est proche : le SIREN est au SIRET ce que le numéro KvK est au vestigingsnummer. Si vous travaillez avec des données britanniques ou allemandes, il n’existe pas d’équivalent direct, ce qui explique précisément pourquoi les équipes de ces marchés ont tendance à ramener les entreprises néerlandaises à une seule adresse et à perdre des données.

Quand vous en avez réellement besoin

La plupart des intégrations n’ont jamais besoin d’un vestigingsnummer. Vous en avez besoin quand votre produit s’intéresse à un site précis plutôt qu’à la contrepartie juridique :

• Livraison et logistique. Un grossiste expédie vers un dépôt, pas vers le siège statutaire. Des vestigingsnummers différents, le même numéro KvK.
• Service sur le terrain et attribution de territoires. Les territoires commerciaux se dessinent sur des sites : une même entreprise peut donc légitimement relever de plusieurs commerciaux.
• Effectifs par site. Les chiffres employees enrichis d’une recherche portent sur l’inscription. Les effectifs par site se trouvent au niveau de l’établissement.
• Rapprochement avec les données de fournisseurs néerlandais. Certains systèmes néerlandais, notamment en facturation électronique et en marchés publics, identifient une contrepartie par établissement plutôt que par entreprise.

Si aucun de ces cas ne s’applique, utilisez le numéro KvK comme clé et passez à autre chose. Récupérer des données d’établissements que vous ne lisez jamais consomme du quota et ajoute une table à maintenir à jour.

Les obtenir

La liste des établissements se rattache à l’entreprise :

curl "https://api.kvkbase.nl/v1/lookup/68750110/branches" \
  -H "Authorization: Bearer YOUR_API_KEY"

Si vous voulez seulement savoir si la question mérite d’être posée, la recherche enrichie contient un compteur totalBranches :

curl "https://api.kvkbase.nl/v1/lookup/68750110?enrich=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Lire d’abord totalBranches et n’appeler /branches que s’il est supérieur à un est une optimisation peu coûteuse. En pratique, la grande majorité des inscriptions néerlandaises n’ont qu’un seul site : vous évitez donc le second appel la plupart du temps.

Le piège : un vestigingsnummer n’est pas stable lors d’un déménagement

Les équipes supposent que le vestigingsnummer se comporte comme le numéro KvK : attribué une fois, valable pour toujours. Ce n’est pas le cas. Il identifie un établissement, et un établissement est lié à un lieu. Une entreprise qui ferme un site et en ouvre un nouveau obtient un nouveau vestigingsnummer, même si rien d’autre ne change dans l’activité. L’ancien disparaît de la liste des établissements.

Cela compte si vous avez des contraintes de clé étrangère qui pointent vers lui. Ne faites pas du vestigingsnummer la clé primaire de votre table de sites et ne posez pas de clé étrangère NOT NULL dessus depuis votre table de commandes, sinon un déménagement ordinaire rendra orphelin un historique que vous aviez besoin de conserver. Stockez-le comme attribut de votre propre enregistrement de site, gardez le numéro KvK comme clé de jointure vers l’entreprise, et traitez la disparition d’un vestigingsnummer de la liste des établissements comme « ce site a fermé » plutôt que « ces données sont corrompues ».

L’habitude connexe à adopter : conservez un instantané de la liste des établissements avec un horodatage de récupération plutôt que de l’écraser. Quand un client demandera pourquoi une facture de mars est partie vers une adresse qui n’existe plus, vous voudrez pouvoir répondre.

Si vous commencez tout juste à modéliser des données néerlandaises, une première version raisonnable n’a aucune table de sites : une seule ligne d’entreprise, indexée sur le numéro KvK, avec l’adresse de l’établissement principal. Ajoutez les établissements quand un besoin réel apparaît : rajouter une table de sites après coup est simple, alors que démêler un schéma qui indexait les commandes sur un vestigingsnummer ne l’est pas.