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 /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.

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 `false`.
`can_sell_insurances`	boolean	nee	Standaard `false`.
`has_agenda`	boolean	nee	Standaard `false`.

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 /roadside-products

Levert de pechhulpproducten die voor de opgegeven garage beschikbaar zijn. De productset kan per garage verschillen op basis van formule-/netwerkafspraken — cache de uitkomst dus per garage_id, niet globaal.

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	ja	VIN/chassisnummer.
`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.
`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",
    "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",
    "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",
    "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.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.

Sandbox-omgeving

Voor integratiepartners is een sandbox-token beschikbaar. Sandbox-tokens gebruiken dezelfde endpoints, dezelfde URL's, dezelfde validatieregels en dezelfde response-structuur als productie. Het verschil zit alleen aan onze kant: verzoeken met een sandbox-token worden niet verwerkt — er worden geen passen, klanten of facturen aangemaakt.

Vraag een sandbox-token aan via bas@pechplan.nl. Daarmee kun je het volgende testen:

Productenlijst

GET /roadside-products retourneert in sandbox een vaste lijst met twee producten:

00000000-0000-4000-8000-000000000001 — PechPlan Basis
00000000-0000-4000-8000-000000000002 — PechPlan EU

Test-kentekens

POST /roadside-passes reageert in sandbox op basis van het kenteken:

Kenteken	HTTP	Resultaat
`11AABB`	`200`	Succesvolle nieuwe pas (`action: "created"`)
`33EEFF`	`200`	Succesvolle verlenging (`action: "extended"`)
`22CCDD`	`422`	"This pass can only be extended in the last 2 months of its term."
elk ander kenteken	`422`	"No vehicle found for this license plate."

Productieverzoeken creëren echte passen en facturen. Er is geen dry-run flag op productie-tokens; 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: bas@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 /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

Sandbox-omgeving

Productenlijst

Test-kentekens

Foutafhandeling

Contact

Response — `201 Created`