PechPlan API

Integratiehandleiding voor Dealer Management Systeem (DMS)–leveranciers. Deze API stelt jullie in staat om vanuit jullie eigen software namens een aangesloten garagebedrijf pechhulpproducten op te halen en pechhulppassen aan te maken of te verlengen.

Doelgroep en model

Deze documentatie is bedoeld voor softwareleveranciers die een DMS, garagemanagementsysteem of werkplaatssoftware leveren aan automotive-bedrijven. De integratie werkt als volgt:

Het garagebedrijf is klant van PechPlan en klant van jullie DMS.
De garage genereert in het PechPlan-portal een API-token dat aan precies één garagevestiging is gekoppeld.
De garage plakt dit token in jullie DMS, op een plek waar jullie hun PechPlan-koppeling configureren.
Jullie DMS roept met dat token namens de garage onze API aan — bijvoorbeeld op het moment van factureren of bij een werkplaatsorder.

Eén token = één garagevestiging. Een DMS-leverancier die meerdere garages bedient, beheert dus één token per klantvestiging in het eigen tenant-/configuratiemodel.

Basis-URL en formaat

https://api.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 (bijv. "79.50") om afrondingsverliezen in jullie boekhouding te voorkomen. Datums zijn ISO-8601 (YYYY-MM-DD). Identifiers zijn UUID-strings.

Versie: v1. Breaking changes worden minstens 30 dagen vooraf aangekondigd op het opgegeven technische contactadres.

Onboarding

De garage logt in op portal.pechplan.nl en gaat naar het API-tokenbeheer.
De garage maakt een token aan met een herkenbare naam (bijv. "Koppeling [naam DMS]") en kopieert dit eenmalig zichtbare token.
De garage plakt het token in jullie DMS-configuratie. Bewaar het in jullie systeem versleuteld at-rest en lever het nooit terug aan de gebruiker.
Jullie DMS test direct de koppeling door GET /roadside-products aan te roepen. Een 200-response bevestigt dat het token werkt en koppelt aan een actieve garage.

Aanbeveling: bouw een "Test verbinding"-knop in jullie configuratiescherm die GET /roadside-products aanroept en het aantal beschikbare producten toont. Dit verkort de supportcyclus aanzienlijk.

Authenticatie

Alle endpoints (behalve deze pagina) vereisen een Bearer token in de Authorization-header:

Authorization: Bearer <token>
Accept: application/json

Tokens worden door de garage zelf in het portal aangemaakt en ingetrokken. Een ingetrokken token werkt direct niet meer — vang 401-responses dus altijd af en toon de eindgebruiker een duidelijke melding dat de PechPlan-koppeling opnieuw geconfigureerd moet worden.

Bewaaradvies

Sla het token versleuteld op (bijv. via een KMS of versleutelde kolom).
Log nooit het volledige token; gebruik bij debugging alleen de eerste 8 tekens.
Beperk toegang tot tokens binnen jullie organisatie — een token geeft volledige schrijfrechten op de pechhulppassen van die garage.

Foutafhandeling

Status	Betekenis	Aanbevolen DMS-gedrag
`200`	OK	Verwerk de response.
`400`	Slecht gevormd verzoek (geen geldige JSON).	Bug in jullie integratie — niet retry-en.
`401`	Token ontbreekt, is ongeldig of ingetrokken.	Markeer de koppeling als "her-configuratie nodig" en informeer de gebruiker.
`403`	De garage heeft geen recht om dit endpoint te gebruiken (bv. mag geen pechhulp verkopen).	Toon een duidelijke melding; niet retry-en.
`404`	Endpoint of resource bestaat niet.	Niet retry-en.
`422`	Validatiefout op de payload, of business-rule afgewezen (bv. te vroege verlenging).	Toon de veldfouten uit het response-body.
`429`	Rate limit overschreden.	Wacht en retry met exponential back-off (zie hieronder).
`500–504`	Onverwachte fout aan onze kant.	Retry met back-off (max 3 pogingen). Bij blijvende fout: zet in queue en alarmeer ons via support.

Foutformaat

Bij 422 en andere clientfouten leveren we een Laravel-stijl foutobject:

{
  "message": "The given data was invalid.",
  "errors": {
    "kenteken": ["Het kenteken is verplicht."],
    "postcode": ["Postcode moet voldoen aan formaat 1234AB."]
  }
}

Rate limiting

Standaard 60 requests per minuut per token. Voor batch-scenario's (bijv. nachtelijke synchronisatie van een groot wagenpark) raden we aan om requests te spreiden of contact op te nemen voor een verhoogd limiet. Bij overschrijding krijg je een 429; pas exponential back-off toe (1s, 2s, 4s, …) tot maximaal 60 seconden.

Endpoints

GET/roadside-products

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

Aanbevolen gebruik in jullie DMS

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. 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://api.pechplan.nl/roadside-products \
  -H "Authorization: Bearer <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 (servicebedrag + reserveringen). Geschikt voor doorbelasting op de factuur.
`currency`	string	Altijd `"EUR"`.

POST/roadside-passes

Maakt een pechhulppas aan voor de eindklant van de garage, of verlengt een bestaande pas. Dit is het hoofdintegratiepunt: meestal aangeroepen op het moment dat de garage het product op een werkorder/factuur zet of die order afsluit in jullie DMS.

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 (vervaldatum + 1 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. Communiceer dit duidelijk in jullie UI; bouw geen automatische retry.
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
`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.
`invoice_id`	string	nee	Eigen factuur-/orderreferentie uit jullie DMS. Wij slaan dit op zodat support koppelingen tussen pas en factuur kan herleiden.

Voorbeeldverzoek

curl -X POST https://api.pechplan.nl/roadside-passes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "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.

Endpoint-specifieke foutcodes

Status	Betekenis
`403`	De aan het token gekoppelde garage mag geen pechhulpproducten verkopen.
`422`	Validatiefout op de payload, of er bestaat een actieve pas die nog niet verlengd mag worden (alleen mogelijk in de laatste 2 maanden van de looptijd).

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 DMS 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 DMS), 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.

UX-richtlijnen voor de eindgebruiker

Toon de productlijst pas wanneer de gebruiker er actief op klikt — niet bij elke schermlaad. Cache 24u.
Bij 401: toon "PechPlan-koppeling moet opnieuw worden geconfigureerd" met directe link naar jullie configuratiepagina.
Bij 422 op verlenging: toon "Pas is nog te lang geldig om te verlengen" en de huidige expires_at als die bekend is uit eerder gebruik.
Bij succes: toon action ("Nieuwe pas aangemaakt" / "Bestaande pas verlengd tot {expires_at}") zodat de gebruiker weet wat er is gebeurd.

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. De response is voor de aanroeper niet te onderscheiden van een echte productieresponse.

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

Productenlijst

GET /roadside-products retourneert in sandbox een vaste lijst met twee producten met de volgende product_id's. Gebruik een van deze in POST /roadside-passes:

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

Gebruik dit om je integratie end-to-end te testen voordat je overstapt naar een productietoken.

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.

Wijzigingsbeleid en versionering

De huidige API is versie v1. Backward-compatibele uitbreidingen (nieuwe optionele velden, nieuwe endpoints) kunnen zonder waarschuwing worden uitgerold. Breaking changes worden minstens 30 dagen vooraf aangekondigd op het bij ons bekende technisch contactadres en gaan altijd gepaard met een nieuwe versiering (v2) op een nieuw pad of subdomein.

Contact en onboarding-support

Voor partner-onboarding, technische vragen of het aanmelden van een nieuwe DMS-koppeling: info@pechplan.nl. Geef bij aanmelding aan welke DMS-software jullie leveren, een schatting van het aantal aangesloten garages, en een technisch contactpersoon voor proactieve communicatie over wijzigingen.

v1 PechPlan API