Client types

Veel endpoints zijn gebonden aan één vestiging. Die herken je aan de {franchiseId} in het pad:

GET /api/{franchiseId}/occasions
GET /api/{franchiseId}/planner/available-dates
GET /api/{franchiseId}/reviews/all

Dit artikel geldt voor al die endpoints. Bij de losse endpoint-artikelen staat het daarom niet nog eens herhaald.

Wat is een franchiseId#

De franchiseId is het klantnummer van een vestiging, en het adres waarop de hele externe API vestigingen aanspreekt.

Geldige waarden haal je op via de vestigingen-endpoints; zie Vestigingen. Een franchiseId verzinnen heeft geen zin — een onbekende waarde levert een 404 op:

{
  "message": "Franchise not found"
}

Toegang per client type#

Welke vestigingen je mag aanspreken hangt af van het type van je API client.

establishment#

Je client is aan één vestiging gekoppeld. Alleen de franchiseId van die vestiging werkt; elke andere levert een 403 op:

{
  "message": "Access denied, it looks like you are using a authorization token for a different establishment"
}

Dit is de gebruikelijke opzet voor een dealerwebsite of een applicatie die op één garage gericht is.

global#

Je client heeft toegang tot alle vestigingen en kan elke franchiseId gebruiken. Dit is de opzet voor partijen die het volledige netwerk ontsluiten.

Welk type je hebt en welke endpoints daarbij horen, staat in Permissies.

Wat de API achter de schermen doet#

Bij elk verzoek op een {franchiseId}-endpoint gebeurt hetzelfde:

1. De API controleert of jouw client deze vestiging mag aanspreken.
2. De vestiging wordt opgehaald, inclusief haar koppelingen.
3. Op basis van die koppelingen wordt de juiste achterliggende partij aangeroepen — de planner van die garage, de voertuigfeed, het reviewplatform.
4. Je krijgt een genormaliseerd antwoord terug, ongeacht welk systeem die vestiging gebruikt.

Dat laatste is het punt van deze opzet: welk plannersysteem of welke voertuigfeed een garage gebruikt, merk je niet aan de API.

Ontbrekende koppeling#

Heeft een vestiging de koppeling niet die bij het endpoint hoort, dan krijg je een 400 in plaats van een leeg antwoord:

{
  "message": "Franchise heeft geen voertuig-integratie ingesteld."
}

Zo is het verschil zichtbaar tussen "deze garage heeft niets" en "deze garage doet hier niet aan mee".