Vestigingen

Een vestiging is een aangesloten garage binnen het Vakgarage-netwerk. Via deze endpoints haal je het volledige netwerk op, één specifieke garage, of de garage die het dichtst bij een plaats ligt.

De volledige request- en responsestructuur staat in de API-referentie, onder Franchises.

Endpoints#

Het franchiseId dat je hier terugkrijgt, gebruik je bij alle andere endpoints met een {franchiseId} in het pad. Zie Client types voor wie welke vestiging mag opvragen.

Alle vestigingen#

Verzoek#

GET /api/franchises

Antwoord#

Een platte lijst met alle vestigingen, gesorteerd op naam, zonder paginering.

Het voorbeeld hieronder is ingekort tot twee dagen; in het echte antwoord staan alle dagen van de week per afdeling.

[
  {
    "franchiseId": "123456",
    "name": "Vakgarage Voorbeeld",
    "streetName": "Dorpsstraat",
    "streetNumber": "1A",
    "postalCode": "1234 AB",
    "city": "Voorbeeldstad",
    "long": "5.12345600",
    "lat": "52.12345600",
    "phone": "(012) 345 67 89",
    "email": "info@vakgaragevoorbeeld.nl",
    "website": "www.vakgaragevoorbeeld.nl",
    "image": "https://cdn.example.com/vestigingen/123456.jpg",
    "openingHours": [
      {
        "department": "Algemeen",
        "days": [
          { "weekday": 1, "opens_at": "08:00", "closes_at": "20:00", "remarks": null },
          { "weekday": 7, "opens_at": null, "closes_at": null, "remarks": null }
        ]
      }
    ]
  }
]

Velden#

Coördinaten komen als string terug, niet als getal. Reken ze om voordat je ermee rekent.

Openingstijden#

openingHours is een lijst met één blok per afdeling. Elk blok heeft een department en een days met de zeven dagen van de week.

{
  "department": "Werkplaats",
  "days": [
    { "weekday": 1, "opens_at": "08:00", "closes_at": "17:30", "remarks": null },
    { "weekday": 6, "opens_at": "08:30", "closes_at": "12:00", "remarks": "zomer" },
    { "weekday": 7, "opens_at": null, "closes_at": null, "remarks": null }
  ]
}

Waar je op moet letten#

De afdelingen verschillen per garage. De ene heeft één blok Algemeen, de andere splitst in Werkplaats en Showroom, en er komen ook namen voor als Receptie, Wasstraat of Verhuur. Ga er dus niet van uit dat een bepaalde afdeling bestaat: loop de lijst af in plaats van te zoeken op naam.

Gesloten is opens_at en closes_at allebei null, niet een lege tekst. Een dag ontbreekt niet in de lijst; hij staat er met lege tijden in.

Eén vestiging#

Verzoek#

GET /api/franchises/123456

Antwoord#

Hetzelfde object als in de lijst, hier met alle dagen.

{
  "franchiseId": "123456",
  "name": "Vakgarage Voorbeeld",
  "streetName": "Dorpsstraat",
  "streetNumber": "1A",
  "postalCode": "1234 AB",
  "city": "Voorbeeldstad",
  "long": "5.12345600",
  "lat": "52.12345600",
  "phone": "(012) 345 67 89",
  "email": "info@vakgaragevoorbeeld.nl",
  "website": "www.vakgaragevoorbeeld.nl",
  "image": "https://cdn.example.com/vestigingen/123456.jpg",
  "openingHours": [
    {
      "department": "Algemeen",
      "days": [
        { "weekday": 1, "opens_at": "08:00", "closes_at": "20:00", "remarks": null },
        { "weekday": 2, "opens_at": "08:00", "closes_at": "18:00", "remarks": null },
        { "weekday": 3, "opens_at": "08:00", "closes_at": "20:00", "remarks": null },
        { "weekday": 4, "opens_at": "08:00", "closes_at": "20:00", "remarks": null },
        { "weekday": 5, "opens_at": "08:00", "closes_at": "18:00", "remarks": null },
        { "weekday": 6, "opens_at": "09:00", "closes_at": "12:00", "remarks": null },
        { "weekday": 7, "opens_at": null, "closes_at": null, "remarks": null }
      ]
    }
  ]
}

Onbekend klantnummer#

HTTP 404 Not Found

{
  "message": "Franchise not found"
}

Dichtstbijzijnde vestiging#

Handig voor een "vind een garage bij mij in de buurt"-functie. Je geeft een zoekterm op — een plaatsnaam, adres of postcode — en krijgt alle vestigingen terug, gesorteerd op afstand.

Verzoek#

GET /api/franchises/search/closest?query=Andersstad

Antwoord#

Dezelfde velden als hierboven, met distance erbij. De lijst is oplopend gesorteerd, dus het eerste element is de dichtstbijzijnde. Ook hier zijn de openingstijden in het voorbeeld ingekort.

[
  {
    "franchiseId": "234567",
    "name": "Vakgarage Tweede Voorbeeld",
    "streetName": "Stationsweg",
    "streetNumber": "12",
    "postalCode": "2345 CD",
    "city": "Andersstad",
    "long": "6.12345600",
    "lat": "53.12345600",
    "phone": "(023) 456 78 90",
    "email": "info@vakgaragetweedevoorbeeld.nl",
    "website": "www.vakgaragetweedevoorbeeld.nl",
    "image": "https://cdn.example.com/vestigingen/234567.jpg",
    "openingHours": [
      {
        "department": "Receptie",
        "days": [
          { "weekday": 1, "opens_at": "08:15", "closes_at": "17:30", "remarks": null }
        ]
      }
    ],
    "distance": 3.8474110595172726
  }
]

distance is de hemelsbrede afstand in kilometers — niet de rijafstand.

Let op#

Levert de zoekterm geen locatie op, dan krijg je een 500 met de melding dat de geocoding mislukte. Vang dat af en toon de volledige lijst als terugval.

Foto en openingstijden#

• image kan null zijn. Niet elke vestiging heeft een foto. Toon een terugval in plaats van een leeg vlak.
• De url wijst naar een externe opslag. Hij kan wijzigen; laad hem met een onerror-terugval en sla hem niet voor langere tijd op.
• openingHours kan een lege lijst zijn. Niet van elke vestiging zijn de tijden bekend.

Beide worden dagelijks bijgewerkt. Een wijziging is dus op zijn vroegst de volgende dag zichtbaar.