Pech Weg partner-API
Korte handleiding voor het aanmelden van transportopdrachten.
Omgeving: productie. Gebruik de dealersleutel die je van Pech Weg ontvangt.
API-adres: https://api.pech-weg.nl
Online handleiding: https://api.pech-weg.nl/docs
PDF: https://api.pech-weg.nl/docs.pdf
Met een geldige dealersleutel kun je rechtstreeks transportopdrachten aanmelden.
1. Toegang
Gebruik je eigen dealer-API-key uit het dealerportaal (Facturatie / Informatie / API Key), of vraag deze aan Pech Weg. Stuur bij elk API-verzoek:
x-api-key: JOUW_DEALER_API_KEY
Content-Type: application/json
De sleutel bepaalt automatisch voor welke dealer de order wordt aangemaakt. Maximaal 60 verzoeken per minuut per dealer voor onderstaande orderroutes.
2. Routes
| Methode | Pad | Doel |
|---|
| GET | /order/vehicle-types | Actuele voertuigtypes en categorieën, inclusief E-Step |
| POST | /order/quote | Prijs berekenen zonder een order aan te maken |
| POST | /order/add | Order aanmelden |
| GET | /order/api/123 | Status van je eigen API-order met ID 123 |
3. Order aanmelden
Stuur dit JSON-object naar POST https://api.pech-weg.nl/order/add. Vervang de voorbeeldgegevens en gebruik voor elke nieuwe opdracht een uniek ordernummer.
{
"ordernummer": "PARTNER-1001",
"source": "Damrak 1, 1012 LG Amsterdam, Nederland",
"destination": "Stationsplein 1, 3511 ED Utrecht, Nederland",
"date": null,
"vehicle_type": "e-step",
"merk": "Voorbeeldmerk",
"model": "Voorbeeldmodel",
"firstname": "Jan",
"lastname": "Voorbeeld",
"streetname": "Voorbeeldstraat",
"housenumber": "12",
"postalCode": "1234 AB",
"phone": "0612345678"
}date: null betekent: later inplannen door Pech Weg. Voor een geplande rit gebruik je een beschikbare datum als YYYY-MM-DD. Alle overige voorbeeldvelden zijn verplicht, behalve ordernummer als je een unieke Idempotency-Key-header gebruikt.
Optionele velden:
| Veld | Betekenis / standaard |
|---|
| affix | Huisnummertoevoeging, bijvoorbeeld A |
| country | Land van de klant; standaard Nederland |
| email | E-mailadres voor de bevestiging |
| email2 | Tweede e-mailadres voor de bevestiging |
| license_plate | Kenteken; leeg als dit niet van toepassing is |
| vehicleAmount | Aantal voertuigen van dit type; standaard 1, maximaal 10000 |
| tripType | single (standaard) of roundtrip (heen en terug) |
| delivery_notes | Instructies voor de chauffeur |
| selectedStore | Naam van de gekozen vestiging |
| inplannen | true voor later inplannen; date: null is voldoende |
Gebruik de value uit /order/vehicle-types als voertuigtype. Voorbeelden: scooter, e-step, fiets, bakfiets, biro, silence, motor (tweewieler) en personenauto.
Prijs, btw, kilometerkosten, brandstoftoeslag en staffelkorting worden door Pech Weg berekend volgens jouw dealerafspraken. De API accepteert geen zelf opgegeven prijs of admininstellingen.
4. Antwoord en opnieuw proberen
Bij een nieuwe order krijg je HTTP 201 met ok, id, ordernummer, tracking_number, tracking_url, price en notifications.
Bewaar het ID en de trackinglink. De bedragen in price zijn eurobedragen; total_incl_vat is het totaal inclusief btw. distance_km is de berekende afstand. Bevestigingen en chauffeursmeldingen worden daarna verwerkt; notifications kan pending, sending, sent of failed zijn.
Bij een timeout stuur je exact hetzelfde verzoek opnieuw, met hetzelfde ordernummer of dezelfde Idempotency-Key. Je krijgt de bestaande order terug (HTTP 200, replayed: true), zonder dubbele order of herhaalde bevestigingen. Wijzig je de gegevens met dezelfde referentie, dan krijg je HTTP 409.
Vraag een prijs vooraf op met /order/quote. Daarvoor zijn source, destination en vehicle_type voldoende; vehicleAmount, tripType en date zijn optioneel. Er wordt niets ingeboekt.
Met /order/api/ID zie je de actuele status en de verwerking van meldingen. Dit werkt alleen voor orders die onder jouw dealersleutel via deze API zijn aangemaakt.
5. Fouten
| HTTP | Betekenis |
|---|
| 400 | Geen geldig JSON-object |
| 401 | Dealersleutel ontbreekt |
| 403 | Sleutel ongeldig of nieuwe opdrachten geblokkeerd |
| 404 | Eigen API-order niet gevonden |
| 409 | Referentie bestaat al met andere gegevens |
| 413 | Verzoek groter dan 64 KB |
| 422 | Veld, voertuigtype of datum ongeldig; lees message |
| 429 | Te veel verzoeken; wacht volgens Retry-After |
| 503 | Tijdelijk probleem; probeer opnieuw met dezelfde referentie |
Fouten bevatten ok: false, een code en een leesbare message.
Abonnementen (aparte aanmelding)
Deze bestaande routes blijven beschikbaar met dezelfde x-api-key:
• POST /subscription/quickadd: stuur email en ordernummer. De klant ontvangt een uitnodiging om een abonnement af te ronden.
• POST /subscription/add: direct abonnement aanmelden met voornaam, achternaam, adres, geboorte_datum (YYYY-MM-DD), telefoonnummer, email, Rekeninghouder, bank_bic, bankrekeningnummer, subscription en ordernummer. Pakketwaarden: Bronze, Goud, Platinum, Business. Optioneel: kenteken, aantal_voertuigen, voertuig, bedrijfsnaam, Merk, Model.
De herhaalbeveiliging met Idempotency-Key geldt voor /order/add, niet voor deze abonnementsroutes.