PechPlan Platform API v1

Integratiehandleiding voor formules — beheer garages en bestelling van pechhulppassen vanuit één API-koppeling.

Voor wie is deze API?

De Platform API (https://platform.pechplan.nl) is bedoeld voor formules die op grotere schaal garages beheren binnen het PechPlan-netwerk. De endpoints zijn identiek aan die van api.pechplan.nl, met als toevoeging dat formules nieuwe garages kunnen aanmaken via de API en zo zelf hun keten kunnen uitbreiden.

Basis-URL en formaat

https://platform.pechplan.nl

Alle requests en responses zijn JSON (Content-Type: application/json, Accept: application/json). Bedragen zijn in euro's en worden als string met twee decimalen geleverd. Datums zijn ISO-8601 (YYYY-MM-DD). Identifiers zijn UUID-strings.

Authenticatie — één formule-token voor alles

De Platform API gebruikt één Bearer-token per formule. Met dat token kun je álle endpoints aanroepen:

POST /garages — een nieuwe garage aanmaken binnen je formule. De response bevat de id (UUID) van de zojuist aangemaakte garage.
GET /garages — alle garages binnen je formule ophalen.
GET /roadside-products?garage_id=… — beschikbare producten voor een specifieke garage binnen je formule.
POST /roadside-passes — pas aanmaken of verlengen voor een eindklant; je geeft in de body op voor welke garage_id het is.
GET /roadside-passes — de actieve passen ophalen: over de hele formule, of met ?garage_id=… beperkt tot één garage.
PATCH /roadside-passes/{id}/auto-renew — automatische verlenging aan- of uitzetten bij een bestaande actieve pas.
PATCH /roadside-passes/{id}/kenteken — het kenteken van een bestaande actieve pas tussentijds wijzigen; de voertuiggegevens worden automatisch via de RDW ververst.
GET /garages/balance?garage_id=… — het actuele saldo van de reservepot van een garage binnen je formule opvragen.
GET /garages/roadside-settings?garage_id=… — de pechhulpinstellingen (openingstijden, werkgebied-straal, telefoonnummers) van een garage opvragen.
PUT /garages/roadside-settings?garage_id=… — diezelfde pechhulpinstellingen aanpassen.

De API valideert bij elk verzoek dat de opgegeven garage_id aan de formule van het token is gekoppeld — je kunt dus nooit per ongeluk acties uitvoeren op een garage van een andere formule.

Workflow: maak eerst een garage aan via POST /garages. Bewaar de geretourneerde id. Gebruik die id vervolgens als garage_id bij GET /roadside-products en POST /roadside-passes om namens die garage te handelen.

Headers

Alle endpoints (behalve deze pagina) vereisen de volgende headers:

Authorization: Bearer <formule-token>
Content-Type: application/json
Accept: application/json

Tokens worden door PechPlan-beheer aangemaakt voor je formule en zijn éénmalig zichtbaar. Bewaar ze versleuteld at-rest en lever ze nooit terug aan de eindgebruiker.

POST /garages

Maakt een nieuwe garage aan die direct actief is en gekoppeld is aan de formule waarvan het token is uitgegeven. Bewaar de geretourneerde id — die heb je nodig als garage_id bij alle andere endpoints.

Request body

Veld	Type	Verplicht	Beschrijving
`bedrijfsnaam`	string	ja	Handelsnaam van de garage, max 255 tekens.
`straatnaam`	string	ja	Straatnaam zonder huisnummer.
`huisnummer`	string	ja	Huisnummer, max 10 tekens.
`huisnummer_toevoeging`	string	nee	Toevoeging (bijv. "A", "bis").
`postcode`	string	ja	Nederlandse postcode, format `1234 AB` of `1234AB`.
`plaatsnaam`	string	ja	Vestigingsplaats.
`telefoonnummer`	string	ja	Algemeen contactnummer van de garage.
`emailadres`	string	ja	Algemeen mailadres van de garage.
`iban`	string	nee	Voor toekomstige betalingen, max 34 tekens.
`can_sell_roadside_assistance`	boolean	nee	Standaard `true` voor via platform aangemaakte garages.
`can_sell_insurances`	boolean	nee	Standaard `true` voor via platform aangemaakte garages.

Voorbeeld-request

curl -X POST https://platform.pechplan.nl/garages \
  -H "Authorization: Bearer <formule-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "bedrijfsnaam": "Autobedrijf De Zwaan",
    "straatnaam": "Industrieweg",
    "huisnummer": "42",
    "postcode": "1234 AB",
    "plaatsnaam": "Amsterdam",
    "telefoonnummer": "+31201234567",
    "emailadres": "info@dezwaan.nl",
    "can_sell_roadside_assistance": true
  }'

Response — `201 Created`

{
  "id": "9c8b7a6e-1234-5678-9abc-def012345678",
  "bedrijfsnaam": "Autobedrijf De Zwaan",
  "straatnaam": "Industrieweg",
  "huisnummer": "42",
  "huisnummer_toevoeging": null,
  "postcode": "1234 AB",
  "plaatsnaam": "Amsterdam",
  "telefoonnummer": "+31201234567",
  "emailadres": "info@dezwaan.nl",
  "iban": null,
  "is_active": true,
  "formula_id": "...",
  "created_at": "2026-05-28T10:42:00+02:00"
}

Bewaar de id in je systeem — die heb je nodig bij het aanmaken van pashouders namens deze garage.

Tip: de garage is direct actief omdat het formule-token impliceert dat PechPlan de formule (en daarmee de toegevoegde garages) vertrouwt. Je kunt direct pashouders aanmaken voor deze garage zonder verdere goedkeuring.

GET /garages

Levert alle garages die aan je formule zijn gekoppeld. Handig om in jullie systeem een actueel overzicht van je keten te synchroniseren of om de id van een bestaande garage op te zoeken voor de andere endpoints.

Voorbeeldverzoek

curl "https://platform.pechplan.nl/garages" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Accept: application/json"

Voorbeeldantwoord — `200 OK`

{
  "data": [
    {
      "id": "9c8b7a6e-1234-5678-9abc-def012345678",
      "bedrijfsnaam": "Autobedrijf De Zwaan",
      "straatnaam": "Industrieweg",
      "huisnummer": "42",
      "huisnummer_toevoeging": null,
      "postcode": "1234 AB",
      "plaatsnaam": "Amsterdam",
      "telefoonnummer": "+31201234567",
      "emailadres": "info@dezwaan.nl",
      "iban": null,
      "is_active": true,
      "can_sell_roadside_assistance": true,
      "can_sell_insurances": true,
      "created_at": "2026-05-28T10:42:00+02:00"
    }
  ]
}

Veldbeschrijving

Veld	Type	Beschrijving
`id`	string (UUID)	Stabiele identifier van de garage. Gebruik deze als `garage_id` bij de andere endpoints.
`bedrijfsnaam`	string	Handelsnaam van de garage.
`is_active`	boolean	Of de garage actief is binnen het PechPlan-netwerk.
`can_sell_roadside_assistance`	boolean	Of de garage pechhulppassen mag verkopen.
`can_sell_insurances`	boolean	Of de garage verzekeringen mag verkopen.
De overige velden (`straatnaam`, `huisnummer`, `huisnummer_toevoeging`, `postcode`, `plaatsnaam`, `telefoonnummer`, `emailadres`, `iban`, `created_at`) zijn identiek aan de respons van `POST /garages`.

GET /garages/balance

Levert het actuele saldo van de reservepot van een garage binnen je formule. Dit is hetzelfde saldo dat in het PechPlan-portaal zichtbaar is: het loopt op met afdrachten en daalt met uitbetalingen/kosten en kan negatief zijn.

Query-parameters

Parameter	Verplicht	Beschrijving
`garage_id`	ja	UUID van de garage binnen je formule. Verkregen uit het antwoord van `POST /garages` of bij eerder aangemaakte garages bekend in jullie systeem.

Voorbeeldverzoek

curl "https://platform.pechplan.nl/garages/balance?garage_id=9c8b7a6e-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Accept: application/json"

Voorbeeldantwoord — `200 OK`

{
  "garage_id": "9c8b7a6e-1234-5678-9abc-def012345678",
  "bedrijfsnaam": "Autobedrijf De Zwaan",
  "balance": "1240.50",
  "currency": "EUR"
}

Veldbeschrijving

Veld	Type	Beschrijving
`garage_id`	string (UUID)	De garage waarvoor het saldo geldt.
`bedrijfsnaam`	string	Handelsnaam van de garage.
`balance`	string	Actueel saldo van de reservepot in euro's, met twee decimalen. Kan negatief zijn.
`currency`	string	Altijd `"EUR"`.

GET /roadside-passes

Levert de actieve passen binnen je formule. Een pas geldt als actief wanneer de status active is én de vervaldatum (expires_at) vandaag of in de toekomst ligt. Verlopen en geannuleerde passen worden niet meegeleverd.

Zonder parameters krijg je de actieve passen van alle garages binnen je formule. Geef je garage_id mee, dan wordt het resultaat beperkt tot die ene garage.

Query-parameters

Parameter	Verplicht	Beschrijving
`garage_id`	nee	UUID van een garage binnen je formule. Weglaten om over de hele formule op te vragen; meegeven om te beperken tot die garage.

Voorbeeldverzoek

# Over de hele formule
curl "https://platform.pechplan.nl/roadside-passes" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Accept: application/json"

# Beperkt tot één garage
curl "https://platform.pechplan.nl/roadside-passes?garage_id=9c8b7a6e-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Accept: application/json"

Voorbeeldantwoord — `200 OK`

{
  "data": [
    {
      "id": "1f2e3d4c-…",
      "garage_id": "9c8b7a6e-1234-5678-9abc-def012345678",
      "product_id": "aabbccdd-…",
      "kenteken": "12ABC3",
      "issued_at": "2026-01-15",
      "expires_at": "2027-01-15",
      "status": "active",
      "auto_renew": true,
      "invoice_id": "5a6b7c8d-…",
      "customer_id": "9e8d7c6b-…",
      "vehicle_id": "3c2b1a0f-…",
      "customer": {
        "id": "9e8d7c6b-…",
        "bedrijfsnaam": null,
        "voornaam": "Jan",
        "achternaam": "Jansen",
        "straatnaam": "Hoofdstraat",
        "huisnummer": "12",
        "huisnummer_toevoeging": null,
        "postcode": "1234 AB",
        "plaatsnaam": "Amsterdam",
        "telefoonnummer": "0612345678",
        "emailadres": "jan@example.nl",
        "geboortedatum": "1985-03-20"
      },
      "vehicle": {
        "id": "3c2b1a0f-…",
        "kenteken": "12ABC3",
        "merk": "Tesla",
        "handelsbenaming": "Model 3",
        "kleur": "Wit",
        "brandstof": "Elektriciteit",
        "chassisnummer": "WVWZZZ1KZBM123456",
        "apk_vervaldatum": "2029-02-19",
        "datum_tenaamstelling": "2025-02-19"
      },
      "product": {
        "id": "aabbccdd-…",
        "name": "PechPlan EU",
        "total_yearly_price": "135.00",
        "eu_coverage": true,
        "currency": "EUR"
      }
    }
  ]
}

Veldbeschrijving

Veld	Type	Beschrijving
`id`	string (UUID)	Unieke identifier van de pas.
`garage_id`	string (UUID)	De garage waaronder de pas is uitgegeven.
`product_id`	string (UUID)	Het pechhulpproduct van de pas.
`kenteken`	string	Kenteken van het gedekte voertuig.
`issued_at`	string (datum)	Ingangsdatum (`YYYY-MM-DD`).
`expires_at`	string (datum)	Vervaldatum (`YYYY-MM-DD`).
`status`	string	Altijd `"active"` in dit antwoord.
`auto_renew`	boolean	`true` als automatische verlenging aanstaat voor deze pas.
`invoice_id`	string (UUID) of `null`	Bijbehorende factuur, indien aanwezig.
`customer_id`	string (UUID)	De eindklant van de pas (zie ook het geneste `customer`-object).
`vehicle_id`	string (UUID)	Het gedekte voertuig (zie ook het geneste `vehicle`-object).
`customer`	object	De volledige klantgegevens: `id`, `bedrijfsnaam`, `voornaam`, `achternaam`, `straatnaam`, `huisnummer`, `huisnummer_toevoeging`, `postcode`, `plaatsnaam`, `telefoonnummer`, `emailadres`, `geboortedatum`. Optionele velden kunnen `null` zijn.
`vehicle`	object	De voertuiggegevens (uit de RDW-koppeling): `id`, `kenteken`, `merk`, `handelsbenaming`, `kleur`, `brandstof`, `chassisnummer`, `apk_vervaldatum`, `datum_tenaamstelling`. Velden die de RDW niet levert kunnen `null` zijn.
`product`	object	Het pechhulpproduct: `id`, `name`, `total_yearly_price` (string, twee decimalen), `eu_coverage` (boolean) en `currency` (altijd `"EUR"`).

PATCH /roadside-passes/{id}/auto-renew

Zet automatische verlenging aan of uit voor een bestaande, nog actieve pas. Staat automatische verlenging aan, dan verlengt PechPlan de pas automatisch (en factureert die) op de dag vóór de vervaldatum — er is dan geen apart POST /roadside-passes-verzoek meer nodig om te verlengen.

Automatische verlenging kan alleen worden gewijzigd zolang de pas actief is (niet geannuleerd of verlopen). De {id} in het pad is de id van de pas, zoals geretourneerd door POST /roadside-passes of GET /roadside-passes.

Request body

Veld	Type	Verplicht	Omschrijving
`auto_renew`	boolean	ja	`true` om automatische verlenging aan te zetten, `false` om uit te zetten.

Voorbeeldverzoek

curl -X PATCH "https://platform.pechplan.nl/roadside-passes/f0e8d1a2-3b5c-4d6e-8f7a-9b0c1d2e3f4a/auto-renew" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "auto_renew": false }'

Voorbeeldantwoord — `200 OK`

{
  "id": "f0e8d1a2-3b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "auto_renew": false
}

Veldbeschrijving

Veld	Type	Beschrijving
`id`	string (UUID)	De pas waarvan de instelling is gewijzigd.
`auto_renew`	boolean	De nieuwe status van automatische verlenging.

PATCH /roadside-passes/{id}/kenteken

Wijzigt het kenteken van een bestaande, nog actieve pas. De overige voertuiggegevens (merk, handelsbenaming, kleur, brandstof, APK-vervaldatum, tenaamstelling) worden automatisch opgehaald via de RDW-koppeling en aan de pas gekoppeld. De looptijd, klant en overige pasgegevens blijven ongewijzigd.

Het kenteken kan alleen worden gewijzigd zolang de pas actief is (niet geannuleerd of verlopen). De {id} in het pad is de id van de pas, zoals geretourneerd door POST /roadside-passes of GET /roadside-passes.

Request body

Veld	Type	Verplicht	Omschrijving
`kenteken`	string	ja	Het nieuwe kenteken. Wordt genormaliseerd (hoofdletters, zonder streepjes).
`chassisnummer`	string	nee	Optioneel VIN; alleen gebruikt om het chassisnummer aan te vullen als dat nog ontbreekt.

Voorbeeldverzoek

curl -X PATCH "https://platform.pechplan.nl/roadside-passes/f0e8d1a2-3b5c-4d6e-8f7a-9b0c1d2e3f4a/kenteken" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "kenteken": "0001TJ" }'

Voorbeeldantwoord — `200 OK`

{
  "action": "kenteken_updated",
  "pass": {
    "id": "f0e8d1a2-3b5c-4d6e-8f7a-9b0c1d2e3f4a",
    "product_id": "9b1f3a4d-6c2e-4f8a-9b1d-3e5a7c9f0b12",
    "kenteken": "0001TJ",
    "issued_at": "2026-04-28",
    "expires_at": "2027-04-28",
    "status": "active",
    "auto_renew": true,
    "invoice_id": "WO-2026-04827",
    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "vehicle_id": "9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4"
  }
}

Veldbeschrijving

Veld	Beschrijving
`action`	Altijd `"kenteken_updated"` bij succes.
`pass.kenteken`	Het nieuwe, genormaliseerde kenteken.
`pass.vehicle_id`	Verwijst nu naar het voertuig van het nieuwe kenteken (met de via RDW opgehaalde gegevens).

GET /garages/roadside-settings

Levert de pechhulpinstellingen van een garage binnen je formule: de openingstijden, de straal rondom het adres die het werkgebied bepaalt, en de telefoonnummers (met naam en volgorde).

Query-parameters

Parameter	Verplicht	Beschrijving
`garage_id`	ja	UUID van de garage binnen je formule.

Voorbeeldverzoek

curl "https://platform.pechplan.nl/garages/roadside-settings?garage_id=9c8b7a6e-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Accept: application/json"

Voorbeeldantwoord — `200 OK`

{
  "garage_id": "9c8b7a6e-1234-5678-9abc-def012345678",
  "bedrijfsnaam": "Autobedrijf De Zwaan",
  "service_radius_km": "25.00",
  "opening_hours": {
    "mon": [{ "open": "08:00", "close": "12:00" }, { "open": "13:00", "close": "17:30" }],
    "tue": [{ "open": "08:00", "close": "17:30" }],
    "sat": [{ "open": "09:00", "close": "13:00" }]
  },
  "phone_numbers": [
    { "id": "1a2b3c4d-…", "label": "Werkplaats", "phone": "31201234567", "paused": false, "position": 0 },
    { "id": "5e6f7a8b-…", "label": "Pechhulp 24/7", "phone": "31612345678", "paused": false, "position": 1 }
  ]
}

Veldbeschrijving

Veld	Type	Beschrijving
`service_radius_km`	string of `null`	Straal in kilometers rondom het garageadres die het werkgebied bepaalt. `null` als (nog) niet ingesteld.
`opening_hours`	object	Object met dagsleutels `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. Elke dag is een lijst van blokken met `open` en `close` (formaat `HH:MM`). Dagen zonder openingstijden ontbreken (gesloten). Meerdere blokken per dag zijn toegestaan (bijv. ochtend + middag).
`phone_numbers`	array	Telefoonnummers op volgorde (`position` oplopend). Per nummer: `id`, `label` (naam), `phone` (internationaal, zonder `+`), `paused` en `position`.

PUT /garages/roadside-settings

Past de pechhulpinstellingen aan. De velden zijn declaratief: wat je meestuurt vervangt de huidige instelling volledig. Stuur je een veld niet mee, dan blijft dat onderdeel ongewijzigd.

Gedrag

Openingstijden: opening_hours vervangt álle openingstijden. Een dag die je weglaat (of leeg meestuurt) wordt als gesloten opgeslagen. Blokken waarbij close niet later is dan open worden genegeerd.
Werkgebied: service_radius_km bepaalt de straal. Stuur je dit veld niet mee, dan blijft de huidige waarde staan.
Telefoonnummers: phone_numbers vervangt de volledige lijst. Een entry mét bestaande id wordt bijgewerkt, een entry zónder id wordt nieuw aangemaakt, en bestaande nummers die je niet meestuurt worden verwijderd. De volgorde van de array bepaalt de position.

Verzoeklichaam

Veld	Type	Verplicht	Beschrijving
`service_radius_km`	number	nee	0–500. Straal van het werkgebied in kilometers.
`opening_hours`	object	nee	Dagsleutels `mon`…`sun`, elk een lijst van `{ "open": "HH:MM", "close": "HH:MM" }`.
`phone_numbers`	array	nee	Lijst van telefoonnummers in gewenste volgorde.
`phone_numbers[].id`	string (UUID)	nee	Laat weg om een nieuw nummer aan te maken; geef mee om een bestaand nummer te wijzigen.
`phone_numbers[].label`	string	nee	Naam/omschrijving, bijv. "Werkplaats".
`phone_numbers[].phone`	string	ja	Telefoonnummer. `0612345678` en `+31 6 12345678` worden geaccepteerd en genormaliseerd.
`phone_numbers[].paused`	boolean	nee	Standaard `false`. Gepauzeerde nummers worden niet gebruikt voor doorschakeling.

Voorbeeldverzoek

curl -X PUT "https://platform.pechplan.nl/garages/roadside-settings?garage_id=9c8b7a6e-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "service_radius_km": 25,
    "opening_hours": {
      "mon": [{ "open": "08:00", "close": "12:00" }, { "open": "13:00", "close": "17:30" }],
      "tue": [{ "open": "08:00", "close": "17:30" }],
      "sat": [{ "open": "09:00", "close": "13:00" }]
    },
    "phone_numbers": [
      { "id": "1a2b3c4d-…", "label": "Werkplaats", "phone": "0201234567" },
      { "label": "Pechhulp 24/7", "phone": "0612345678" }
    ]
  }'

Het antwoord is identiek aan dat van GET /garages/roadside-settings en weerspiegelt de zojuist opgeslagen staat — inclusief de id's van nieuw aangemaakte telefoonnummers.

Let op: omdat de velden de huidige instelling volledig vervangen, raden we aan eerst GET te doen, de gewenste wijzigingen toe te passen op het opgehaalde object, en dat geheel terug te sturen met PUT. Zo verwijder je nooit per ongeluk bestaande openingstijden of telefoonnummers.

GET /roadside-products

Levert de pechhulpproducten die voor de opgegeven garage beschikbaar zijn. De productset kan per garage verschillen — cache de uitkomst dus per garage_id, niet globaal.

Welke producten worden getoond? Het meest specifieke niveau bepaalt de volledige lijst (één niveau wint):

Garage-specifiek — zijn er producten rechtstreeks aan deze garage gekoppeld, dan worden alleen die getoond.
Anders formule-specifiek — de producten die aan de formule van deze garage zijn gekoppeld.
Anders de algemene producten die voor iedereen beschikbaar zijn.

Een garage met eigen productafspraken ziet dus uitsluitend die producten, en niet daarnaast nog de formule- of algemene producten.

Query-parameters

Parameter	Verplicht	Beschrijving
`garage_id`	ja	UUID van de garage binnen je formule. Verkregen uit het antwoord van `POST /garages` of bij eerder aangemaakte garages bekend in jullie systeem.

Aanbevolen gebruik

Roep dit endpoint aan zodra de gebruiker in jullie UI een PechPlan-product wil selecteren (bijv. bij het toevoegen aan een werkorder of factuur).
Cache de response maximaal 24 uur per garage_id. Producten en prijzen veranderen zelden, maar wij garanderen geen onveranderlijkheid.
Toon de eindgebruiker altijd description + total_yearly_price. Bewaar product_id intern voor het vervolgverzoek.

Voorbeeldverzoek

curl "https://platform.pechplan.nl/roadside-products?garage_id=9c8b7a6e-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <formule-token>" \
  -H "Accept: application/json"

Voorbeeldantwoord

{
  "data": [
    {
      "product_id": "9b1f3a4d-6c2e-4f8a-9b1d-3e5a7c9f0b12",
      "description": "PechPlan Basis",
      "total_yearly_price": "79.50",
      "currency": "EUR"
    },
    {
      "product_id": "1c8b2e7f-4a91-4c63-9d20-7f6b3a1e2c45",
      "description": "PechPlan Plus EU",
      "total_yearly_price": "129.00",
      "currency": "EUR"
    }
  ]
}

Veldbeschrijving

Veld	Type	Beschrijving
`product_id`	string (UUID)	Stabiele identifier van het product. Gebruik deze in vervolgverzoeken.
`description`	string	Door PechPlan beheerde productnaam, geschikt voor weergave aan de eindgebruiker.
`total_yearly_price`	string	Totale jaarprijs incl. alle componenten. Geschikt voor doorbelasting op de factuur.
`currency`	string	Altijd `"EUR"`.

POST /roadside-passes

Maakt een pechhulppas aan voor de eindklant van een specifieke garage binnen je formule, of verlengt een bestaande pas. Dit is het hoofdintegratiepunt: meestal aangeroepen op het moment dat een werkorder/factuur wordt afgesloten in jullie systeem.

Gedrag

Ingangsdatum is altijd de dag van het verzoek; vervaldatum is een jaar later.
Auto-verlenging: bestaat er voor dezelfde combinatie van garage + kenteken + product al een actieve pas die binnen 2 maanden verloopt? Dan verlengen we die met één jaar in plaats van een nieuwe pas aan te maken. Dit zie je terug in action: "extended".
Te vroege verlenging (pas heeft nog meer dan 2 maanden looptijd) levert een 422 op.
Voertuiggegevens (merk, model, kleur, brandstof, APK-datum) halen wij automatisch op bij de RDW op basis van het kenteken — niet meesturen.
Klant-deduplicatie: bestaat er al een klant met hetzelfde e-mailadres bij deze garage, dan koppelen we die en werken we de NAW bij. Anders maken we een nieuwe klant aan.
Voertuig-deduplicatie: bestaat er al een voertuig met dit kenteken onder de gevonden/aangemaakte klant, dan hergebruiken we dat voertuig.

Verzoeklichaam

Veld	Type	Verplicht	Beschrijving
`garage_id`	UUID	ja	Garage binnen je formule. Verkregen uit `POST /garages`.
`product_id`	UUID	ja	Uit `/roadside-products`.
`kenteken`	string	ja	Nederlands kenteken zonder streepjes, hoofdletters (bijv. `2ZPZ13`).
`chassisnummer`	string	nee	VIN/chassisnummer. Optioneel — laat leeg of weg indien niet beschikbaar.
`voornaam`	string	ja
`achternaam`	string	ja
`straatnaam`	string	ja
`huisnummer`	string	ja
`huisnummer_toevoeging`	string	nee
`postcode`	string	ja	`1234AB` of `1234 AB`.
`plaatsnaam`	string	ja
`bedrijfsnaam`	string	nee	Voor zakelijke klanten.
`telefoonnummer`	string	nee
`emailadres`	string	nee	Sterk aanbevolen: gebruikt voor klant-deduplicatie.
`geboortedatum`	string (YYYY-MM-DD)	nee	Moet in het verleden liggen.
`auto_renew`	boolean	nee	Zet automatische verlenging aan of uit. Standaard `false`. Bij `true` verlengt PechPlan de pas automatisch (en factureert) op de dag vóór de vervaldatum. Kan later ook via `PATCH /roadside-passes/{id}/auto-renew` worden aangepast.
`invoice_id`	string	nee	Eigen factuur-/orderreferentie uit jullie systeem. Wij slaan dit op zodat support koppelingen tussen pas en factuur kan herleiden.

Voorbeeldverzoek

curl -X POST https://platform.pechplan.nl/roadside-passes \
  -H "Authorization: Bearer <formule-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "garage_id": "9c8b7a6e-1234-5678-9abc-def012345678",
    "product_id": "9b1f3a4d-6c2e-4f8a-9b1d-3e5a7c9f0b12",
    "kenteken": "2ZPZ13",
    "chassisnummer": "WVWZZZ1KZBM123456",
    "voornaam": "Jan",
    "achternaam": "Jansen",
    "straatnaam": "Hoofdstraat",
    "huisnummer": "12",
    "postcode": "1234 AB",
    "plaatsnaam": "Amsterdam",
    "telefoonnummer": "0612345678",
    "emailadres": "jan@example.nl",
    "auto_renew": true,
    "invoice_id": "WO-2026-04827"
  }'

Voorbeeldantwoord (nieuwe pas)

{
  "action": "created",
  "pass": {
    "id": "f0e8d1a2-3b5c-4d6e-8f7a-9b0c1d2e3f4a",
    "product_id": "9b1f3a4d-6c2e-4f8a-9b1d-3e5a7c9f0b12",
    "kenteken": "2ZPZ13",
    "issued_at": "2026-04-28",
    "expires_at": "2027-04-28",
    "status": "active",
    "auto_renew": true,
    "invoice_id": "WO-2026-04827",
    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "vehicle_id": "1234abcd-5678-90ef-1234-567890abcdef"
  }
}

Voorbeeldantwoord (verlenging)

{
  "action": "extended",
  "pass": {
    "id": "f0e8d1a2-3b5c-4d6e-8f7a-9b0c1d2e3f4a",
    "product_id": "9b1f3a4d-6c2e-4f8a-9b1d-3e5a7c9f0b12",
    "kenteken": "2ZPZ13",
    "issued_at": "2025-05-10",
    "expires_at": "2027-05-10",
    "status": "active",
    "auto_renew": true,
    "invoice_id": "WO-2026-04827",
    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "vehicle_id": "1234abcd-5678-90ef-1234-567890abcdef"
  }
}

Veldbeschrijving antwoord

Veld	Beschrijving
`action`	`"created"` bij een nieuwe pas, `"extended"` bij verlenging van een bestaande pas.
`pass.id`	Stabiele identifier van de pas. Bewaar deze in jullie order-/factuurregel zodat support het verband kan herleiden.
`pass.issued_at`	Originele ingangsdatum (blijft staan bij verlenging).
`pass.expires_at`	Vervaldatum (1 jaar na ingang, of huidige vervaldatum + 1 jaar bij verlenging).
`pass.status`	Altijd `"active"` bij succesvolle responses.
`pass.auto_renew`	`true` als automatische verlenging aanstaat, anders `false`.
`pass.customer_id` / `pass.vehicle_id`	Stabiele identifiers binnen het PechPlan-systeem. Optioneel te bewaren voor latere referentie.

Implementatie-aanbevelingen

Idempotency en retries

Het /roadside-passes-endpoint is op basis van garage + kenteken + product + tijdvenster de-facto idempotent: een herhaald verzoek binnen dezelfde dag voor dezelfde combinatie levert in de regel hetzelfde resultaat (verlengen of error op te-vroege verlenging). Toch raden we aan:

Bij netwerkfouten (timeout, 5xx) maximaal 3 retries met exponential back-off.
Eindig de retryloop niet stilletjes: zet falende verzoeken in een queue/dead-letter zodat de garagegebruiker zichtbaar weet dat de pas niet is aangemaakt.
Bewaar in jullie systeem de pass.id uit het response zodra je 'm hebt — dat voorkomt dubbele aanmaakpogingen vanuit dezelfde werkorder.

Logging en auditing

Log per request: tijdstip, garage-identifier (in jullie systeem), endpoint, HTTP-status, en de eerste 8 tekens van het token.
Bewaar request- en responselichamen minstens 90 dagen voor support-trace; redigeer persoonsgegevens conform jullie privacybeleid.

Verzoeken creëren echte passen en facturen. Bouw daarom in jullie eigen UI een duidelijke bevestigingsstap voordat POST /roadside-passes wordt aangeroepen.

Foutafhandeling

Status	Betekenis
`401`	Token ontbreekt of is ingetrokken.
`403`	De opgegeven garage mag dit type product niet verkopen (bijv. `can_sell_roadside_assistance` staat uit).
`404`	De opgegeven `garage_id` bestaat niet of hoort niet bij je formule.
`422`	Validatiefout. Het response-veld `errors` bevat per veld een lijst met meldingen.
`429`	Rate limit overschreden (60 requests/minuut/IP).
`500`	Interne fout — al onze logs worden gemonitord; neem contact op als deze blijft optreden.

Contact

Voor technische vragen: info@pechplan.nl.

PechPlan Platform API v1

Voor wie is deze API?

Basis-URL en formaat

Authenticatie — één formule-token voor alles

Headers

POST /garages

Request body

Voorbeeld-request

Response — 201 Created

GET /garages

Voorbeeldverzoek

Voorbeeldantwoord — 200 OK

Veldbeschrijving

GET /garages/balance

Query-parameters

Voorbeeldverzoek

Voorbeeldantwoord — 200 OK

Veldbeschrijving

GET /roadside-passes

Query-parameters

Voorbeeldverzoek

Voorbeeldantwoord — 200 OK

Veldbeschrijving

PATCH /roadside-passes/{id}/auto-renew

Request body

Voorbeeldverzoek

Voorbeeldantwoord — 200 OK

Veldbeschrijving

PATCH /roadside-passes/{id}/kenteken

Request body

Voorbeeldverzoek

Voorbeeldantwoord — 200 OK

Veldbeschrijving

GET /garages/roadside-settings

Query-parameters

Voorbeeldverzoek

Voorbeeldantwoord — 200 OK

Veldbeschrijving

PUT /garages/roadside-settings

Gedrag

Verzoeklichaam

Voorbeeldverzoek

GET /roadside-products

Query-parameters

Aanbevolen gebruik

Voorbeeldverzoek

Voorbeeldantwoord

Veldbeschrijving

POST /roadside-passes

Gedrag

Verzoeklichaam

Voorbeeldverzoek

Voorbeeldantwoord (nieuwe pas)

Voorbeeldantwoord (verlenging)

Veldbeschrijving antwoord

Implementatie-aanbevelingen

Idempotency en retries

Logging en auditing

Foutafhandeling

Contact

Response — `201 Created`

Voorbeeldantwoord — `200 OK`

Voorbeeldantwoord — `200 OK`

Voorbeeldantwoord — `200 OK`

Voorbeeldantwoord — `200 OK`

Voorbeeldantwoord — `200 OK`

Voorbeeldantwoord — `200 OK`