Hoofdvestiging en nevenvestiging

Het verschil

Elke inschrijving in het Handelsregister heeft één hoofdvestiging. Dat is de locatie van waaruit de onderneming hoofdzakelijk wordt gedreven, en de KVK registreert die bij inschrijving. Een zzp’er die vanuit huis werkt heeft een hoofdvestiging, net als een keten met dertig winkels.

Nevenvestigingen zijn alle andere locaties waar de onderneming duurzaam activiteiten uitvoert: filialen, magazijnen, werkplaatsen, een tweede kantoor. Ze zijn geen aparte inschrijving en hebben geen eigen KVK-nummer, wel een eigen vestigingsnummer van twaalf cijfers.

Een nevenvestiging kan een eigen handelsnaam voeren. Dat is de reden dat je in de praktijk winkelketens tegenkomt waar het filiaal in de stad een andere naam op de gevel heeft dan de vennootschap op de factuur.

Wat je terugkrijgt

Een gewone lookup geeft het adres van de hoofdvestiging in address, en met enrich=true ook een postalAddress als dat afwijkt. Er is geen manier om een lookup op een nevenvestiging te richten: het KVK-nummer wijst naar de inschrijving, en de inschrijving heeft één hoofdadres.

Het aantal vestigingen zit in totalBranches, en dat veld is enrich-only:

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

De lijst zelf hangt aan een eigen endpoint:

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

Heb je coördinaten nodig voor een kaart of een afstandsberekening, dan voegt geo=true lat/lon toe aan adressen:

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

Een detail dat kosten scheelt: totalBranches telt de vestigingen, inclusief de hoofdvestiging. Een bedrijf met één locatie heeft dus de waarde 1 en niet 0. Gebruik dat als drempel voordat je de branches-endpoint aanroept, dan doe je die tweede call alleen waar hij iets oplevert.

Het patroon dat werkt

De verleiding is om bij elke klant meteen de vestigingslijst op te halen. Dat is verspilling: de overgrote meerderheid van de inschrijvingen in Nederland heeft precies één vestiging, en dan is de lijst een herhaling van het adres dat je al hebt.

Doe het in twee stappen. Verrijk bij onboarding, lees totalBranches, en haal de lijst alleen op als die groter is dan één en je usecase het nodig heeft:

const company = await lookup(kvk, { enrich: true });
if ((company.totalBranches ?? 1) > 1 && needsBranchPicker) {
  const branches = await lookupBranches(kvk);
  // toon een keuzelijst
}

Let op de ?? 1 in dat voorbeeld. Ontbreekt totalBranches, bijvoorbeeld omdat een call zonder enrich is gedaan of omdat het veld voor deze inschrijving niet gevuld is, dan is undefined > 1 gewoon false en gaat het goed. Schrijf je in plaats daarvan company.totalBranches === 0, dan krijg je een tak die nooit klopt.

Waar het misgaat in productie

Adressen die stil verlopen. Overgenomen adressen verouderen zonder foutmelding. Een bedrijf verhuist, jouw factuuradres blijft staan, en de post komt maanden later terug. Ververs adressen periodiek in plaats van ze één keer bij registratie over te nemen.

Het bezorgadres van de hoofdvestiging gebruiken. Bij een keten is de hoofdvestiging vaak het hoofdkantoor en niet de plek waar de goederen heen moeten. Vraag de gebruiker om de vestiging te kiezen als totalBranches groter is dan één, in plaats van het hoofdadres te prefillen en te hopen.

Een gesloten filiaal aanzien voor een open filiaal. Vestigingen sluiten zonder dat de inschrijving eindigt. isActive op het profiel zegt niets over een individuele vestiging, en de data is tot 24 uur gecachet. Voor een routeplanning of een servicebezoek is dat een marge waar je rekening mee moet houden.

Vestigingen als klanten opvoeren. In een webshop of CRM is de verleiding groot om elk filiaal een eigen account te geven met een eigen KVK-nummer. Dat nummer bestaat niet. Modelleer het als één debiteur met meerdere afleveradressen, en bewaar het vestigingsnummer bij het adres. Voor een webshop doet een WooCommerce-integratie dat werk in de checkout.

De hoofdvestiging aanzien voor het postadres. Dat zijn twee velden, address en postalAddress, en ze wijken vaker af dan verwacht: een postbus voor de administratie, een bedrijventerrein voor de goederen. Facturen naar postalAddress als die er is, leveringen naar address.