Custom shipping provider - Eigen/andere verzendmethoden koppelen
Updated
by
Stan
In deze handleiding leggen we uit hoe je een eigen/andere verzendprovider koppelt aan GoedGepickt. In GoedGepickt ondersteunen we tal van verzendproviders, maar het kan voorkomen dat je wellicht een andere verzendprovider wilt koppelen aan GoedGepickt. Het is mogelijk om je eigen verzendprovider aan te maken in GoedGepickt. Dit doe je door zelf een script/endpoint te maken, waarop je data vanuit GoedGepickt toegestuurd krijgt en daarmee zelf een label kan genereren.
Uitleg
Met deze verzendmethode is het mogelijk om een JSON request te sturen naar een opgegeven URL, bij het aanmaken van een zending. In dit request vanuit GoedGepickt wordt de volgende data meegestuurd naar de opgegeven URL:
Deze data is weer te verwerken aan de opgegeven endpoint. Als response wordt verwacht dat binnen 15 seconden de volgende waarden teruggegeven worden: (als json_encoded waarde)
- trackingnumber: de tracking code
- trackingurl: de tracking url
- shipping_carrier: de verzendprovider, bijv. PostNL
- pdf_label: het pdf bestand, als base64 encoded.
Voorbeeld PHP-code waarmee een correcte response teruggegeven kan worden:
<?php
$result = [
'trackingnumber' => '3S123123123',
'trackingurl' => 'https://www.goedgepickt.nl',
'shipping_carrier' => 'PostNL',
'pdf_label' => base64_encode(file_get_contents('shipping-test.pdf')),
];
echo json_encode($result);
Koppeling opstarten
In GoedGepickt navigeer je naar Instellingen -> Verzendproviders -> en klik je rechts bovenin op de oranje knop: Toevoegen. Kies in de lijst met verzendproviders voor Custom Shipping Provider.
Scroll naar beneden waar je de volgende informatie kan invullen:
- URL (verplicht): De URL waar de JSON heen wordt gepusht. Vul hier de exacte URL in.
De overige gegevens zijn vrij invulbaar en worden bij elke JSON push meegestuurd. Je kan deze gegevens zien als de gegevens van afzender. Mocht je bijvoorbeeld 1 URL gebruiken voor meerdere webshops, met meerdere afzender adressen.
- API geheim: Eventueel een API-sleutel die meegestuurd moet worden om te identificeren.
- Naam afzender: Naar wens in te vullen.
- Adres: Naar wens in te vullen.
- Huisnummer: Naar wens in te vullen.
- Postcode: Naar wens in te vullen
- Plaats: Naar wens in te vullen
- Landcode: Naar wens in te vullen
- E-mailadres: Naar wens in te vullen
- Afzender telefoonnummer: Naar wens in te vullen
- Verzendmethodes: laat dit veld leeg, totdat je hebt opgeslagen!
Geef daarnaast je verzendprovider een naam, zodat je kan herkennen welke verzendmethode het is. Klaar? Klik op Verzendprovider koppelen.
Je komt nu op het bewerk-scherm van de verzendprovider. Je ziet hier de ingegeven instellingen uit de vorige stap.
Verzendmethodes toevoegen
Eventueel is het mogelijk om verzendmethodes aan te maken bij deze verzendprovider. Hierdoor is het mogelijk om in het verzendscherm, bij het aanmaken van een zending voor een bestelling, te kiezen uit verschillende methodes. Zoals bijvoorbeeld: Pakket, Pallet, etc.
Zie hier een voorbeeld:
Op het bewerk-scherm van de verzendprovider kan je deze methodes toevoegen. Je kan links een naam invullen en rechts de waarde die doorgestuurd wordt met de JSON-push.
Dynamische verzendmethodes ondersteunen
Wanneer je in het verzendmethodes blok hebt gekozen voor dynamische verzendmethodes gebruiken, komt er een extra instelling beschikbaar om een URL in te vullen. Met deze instelling is het mogelijk om de verzendmethodes dynamisch in te laden. Om de verzendmethodes op te halen zullen er verzoeken worden gedaan naar de opgegeven URL.
Verzendmethodes ophalen
Een ingestelde URL zal van GoedGepickt verzoeken ontvangen waardoor er onderscheid kan worden gemaakt welke verzendgegevens je terug wilt sturen naar GoedGepickt. Een voorbeeld van wat je kan verwachten zie je hieronder.
Verzendmethodes terugsturen naar GoedGepickt
Om de verzendmethodes in GoedGepickt te tonen dien je de methodes op een bepaald formaat terug te sturen naar GoedGepickt. Hieronder staan een array uitgewerkt hoe GoedGepickt je verzendmethodes kan verwerken. Dit kunnen simpele verzendmethodes zijn, maar ook verzendmethodes met extra opties.
<?php
$result = [
'shippingMethods' => [
[
'methodLabel' => 'DHL - pakket',
'methodId' => 'JZCrRMR',
'shippingOptions' => [
[
'optionLabel' => 'Avondlevering',
'optionId' => 'EVE',
'optionType' => 'checkbox',
],
[
'optionLabel' => 'Ochtendlevering',
'optionId' => 'MOR',
'optionType' => 'checkbox',
],
],
],
[
'methodLabel' => 'DHL - pakket XL',
'methodId' => 'ABC',
'shippingOptions' => [
[
'optionLabel' => 'Verzekerd',
'optionId' => 'INS',
'optionType' => 'checkbox',
'extraFields' => [
[
'fieldType' => 'selectbox',
'fieldName' => 'insuredAmount',
'optionChoices' => [
[
'choiceLabel' => '€500',
'choiceValue' => '500',
],
[
'choiceLabel' => '€750',
'choiceValue' => '750',
],
],
],
],
],
[
'optionLabel' => 'Ochtendlevering',
'optionId' => 'MOR',
],
],
],
[
'methodLabel' => 'PostNL - pakket',
'methodId' => '1',
],
],
];
echo json_encode($result);php
Gekozen verzendmethode/verzendopties ontvangen
Indien er bij een verzendmethode verzendopties zijn geselecteerd zal GoedGepickt deze ook meenemen in het zending aanmaken request. deze zijn terug te vinden onder shipping_options en eventueel extra gerelateerde velden onder shipping_options_related_fields.
Foutmeldingen
Is er ontbrekende data of kan een zending om de een of andere reden niet aangemaakt worden, dan is het mogelijk om een error terug te sturen, in JSON format, in het veld error. Gebruik hiervoor een statuscode, bij voorkeur hoger dan 400. Bijvoorbeeld statuscode 500.
De foutmelding wordt aan de gebruiker getoond bij het aanmaken van een zending. Probeer dus een leesbare foutmelding te genereren.
Testen van de koppeling
Wil je e.e.a. debuggen / testen? Kijk dan eens bij https://requestbin.com - Je kan hier een endpoint aanmaken, waar je data heen kan sturen. Handig om te testen wat voor data er binnenkomt.
Vragen?
Nu weet je hoe je een eigen/andere verzendprovider koppelt aan GoedGepickt. Zijn er toch nog onduidelijkheden, heb je andere vragen of ideeën? Neem dan contact met ons op, wij helpen je graag!