Verbinden met aangepaste vervoerders-API

Last updated

ChannelDock biedt veel kant-en-klare vervoerderskoppelingen die verkopers en fulfillmentcentra direct kunnen gebruiken. Omdat we niet met elk vervoerdersplatform een koppeling kunnen bouwen, bieden we daarnaast de Custom Carrier API. Hiermee kun je als vervoerder (of verzendplatform) je eigen verzendmethoden toevoegen aan het ChannelDock-account van een verkoper of fulfillmentcenter, en de verzendlabels zelf aanmaken.

Zo werkt het

Je registreert je verzendmethoden in het ChannelDock-account van de verkoper of het fulfillmentcenter, via de ChannelDock REST API.
De gebruiker kiest jouw verzendmethode bij het aanmaken van een verzendlabel in ChannelDock.
ChannelDock roept jouw API aan met de ordergegevens en de gekozen verzendmethode.
Jouw API stuurt het label terug als PDF, samen met het trackingnummer.
ChannelDock print het label en stuurt het trackingnummer naar het verkoopkanaal (bijvoorbeeld bol of Amazon), zodat de order als verzonden wordt gemarkeerd.

Je bouwt dus twee dingen: een script dat je verzendmethoden registreert (stap 1) en een endpoint aan jouw kant dat labels aanmaakt (stap 3 en 4).

Stap 1: API-gegevens ophalen

De verzendmethoden worden aangemaakt in het account van de verkoper of het fulfillmentcenter dat ze gaat gebruiken. Dat account genereert de API-gegevens en deelt ze met jou:

Verkoper: Instellingen → API & Webhooks
Fulfillmentcenter: Instellingen → API & Webhooks

Zijn de endpoint-rechten van de API-sleutel beperkt? Zorg dan dat de sleutel toegang heeft tot het endpoint shipment methods. Meer over API-sleutels lees je in ChannelDock REST API-documentatie.

Stap 2: Verzendmethoden registreren

Stuur je verzendmethoden naar het endpoint dat bij het type account past:

Account	Methode	Endpoint
Verkoper	POST	`https://channeldock.com/portal/api/v2/seller/shipmentmethods`
Fulfillmentcenter	POST	`https://channeldock.com/portal/api/v2/center/shipmentmethods`

Authenticeer met de headers api-key en api-secret.

Dit endpoint vinden in de API-documentatie

Open docs.channeldock.com en ga in het menu naar ChannelDock Seller (of ChannelDock Fulfillment Center) → Shipment methods → Create / Update custom shipment method. Je kunt ook zoeken op “custom shipment method”. We linken niet rechtstreeks naar de sectie, omdat die links veranderen zodra de API-documentatie opnieuw wordt gepubliceerd.

Voorbeeldrequest

{
  "name": "MyCarrier - Package large express",
  "remote_carrier_id": "my_carrier_large_express",
  "carrier_code": "mycarrier",
  "logo_url": "https://example.com/logo-700x300.png",
  "min_weight": 0,
  "max_weight": 23,
  "max_x": 150,
  "max_y": 150,
  "max_z": 150,
  "mailbox_size": 0,
  "callback_request": {
    "method": "POST",
    "url": "https://yourdomain.com/api/channeldock/labels",
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_CARRIER_API_TOKEN"
    }
  },
  "shipment_method_countries": [
    { "country_code_from": "NL", "country_code_to": "NL", "price": 3.20 },
    { "country_code_from": "NL", "country_code_to": "BE", "price": 4.80 },
    { "country_code_from": "NL", "country_code_to": "DE", "price": 5.60 }
  ]
}

Veld	Verplicht	Beschrijving
name	Ja	Naam van de verzendmethode, zichtbaar voor de gebruiker. Wordt ook gebruikt om een bestaande methode te herkennen (zie hieronder).
remote_carrier_id	Ja	Jouw eigen ID voor deze verzendmethode. We sturen dit mee bij elke labelaanvraag.
carrier_code	Ja	Code van je platform of vervoerder in kleine letters, bijvoorbeeld `mycarrier` of `dhl`.
logo_url	Ja	Openbare URL van een PNG-logo van 700 x 300 pixels.
min_weight, max_weight	Ja	Gewichtsgrenzen in kg.
max_x, max_y, max_z	Ja	Maximale afmetingen in cm.
mailbox_size	Ja	`1` als de methode voor brievenbuspakketten is, anders `0`. Bij `1` wordt de methode alleen getoond als het pakket door de brievenbus past.
callback_request	Ja	Hoe ChannelDock jouw label-endpoint aanroept: `url`, `method` (we raden `POST` aan) en `headers` (een object, bijvoorbeeld met je eigen authenticatietoken).
shipment_method_countries	Ja	Minimaal één route met `country_code_from`, `country_code_to` (2-letterige ISO-codes) en `price`. De methode wordt alleen aangeboden voor deze routes.

Goed om te weten

Aanmaken of bijwerken: ChannelDock zoekt in het account naar een bestaande verzendmethode met dezelfde name. Bestaat die, dan wordt hij bijgewerkt (ook remote_carrier_id en callback_request). Zo niet, dan wordt er een nieuwe aangemaakt. Pas je de name aan, dan ontstaat er dus een tweede verzendmethode; de oude blijft bestaan.
Routes worden toegevoegd of bijgewerkt, nooit verwijderd: een route die je weglaat in het request blijft actief met de oude prijs.
Meerdere methoden tegelijk: stuur een array van verzendmethode-objecten in plaats van één object. Het antwoord toont dan het resultaat per methode.
Fulfillmentcentra kunnen hun verzendmethoden ophalen met GET https://channeldock.com/portal/api/v2/center/shipmentmethods.

Antwoord

{
  "response": "success",
  "message": "Shipment method MyCarrier - Package large express created successfully"
}

Stap 3: De labelaanvraag ontvangen

Zodra een ChannelDock-gebruiker een verzendlabel aanmaakt met een van jouw verzendmethoden, roept ChannelDock de url uit callback_request aan, met de method en headers die je hebt opgegeven. Bij POST (aanbevolen) worden de ordergegevens als JSON-body verstuurd. Bij GET worden dezelfde velden als queryparameters meegestuurd.

Voorbeeldrequest van ChannelDock

{
  "order_id": 774,
  "remote_order_id": "ORD-2025-4055",
  "seller_id": 1223,
  "center_id": 0,
  "api_id": 456,
  "api_description": "Bol.com - Main shop",
  "channel_name": "Bol.com",
  "order_date": "2025-05-13 08:49:28",
  "ship_on_date": "2025-05-14",
  "remote_carrier_id": "my_carrier_large_express",
  "carrier_code": "mycarrier",
  "number_of_labels": 1,
  "sender_details": {
    "name": "John Doe",
    "company_name": "Doe Logistics BV",
    "street": "Keizersgracht",
    "house_number": "241",
    "address_line_2": "Suite 301",
    "zipcode": "1016 EA",
    "city": "Amsterdam",
    "state_province_code": "",
    "country": "NL",
    "phone_number": "+31 20 123 4567",
    "email": "[email protected]",
    "signature_full_name": "John Doe",
    "signature_initials": "JD",
    "vat_number": "NL123456789B01",
    "eori_number": "NL123456789000"
  },
  "shipping_first_name": "Emma",
  "shipping_middle_name": null,
  "shipping_last_name": "van Dijk",
  "shipping_company": "KiteGear BV",
  "shipping_street": "Keizersgracht",
  "shipping_house_number": "123",
  "shipping_house_number_ext": "B",
  "shipping_address1": "Keizersgracht 123",
  "shipping_address2": "2nd floor",
  "shipping_address_supplement": "Entrance via side door",
  "shipping_zip_code": "1015 CJ",
  "shipping_city": "Amsterdam",
  "shipping_region": "Noord-Holland",
  "shipping_country_code": "NL",
  "shipping_email": "[email protected]",
  "shipping_phone_number": "+31 6 12345678",
  "shipping_address_accurate": 1,
  "shipping_service": "",
  "billing_first_name": "Emma",
  "billing_middle_name": null,
  "billing_last_name": "van Dijk",
  "billing_company": "KiteGear BV",
  "billing_street": "Keizersgracht",
  "billing_house_number": "123",
  "billing_house_number_ext": "B",
  "billing_address1": "Keizersgracht 123",
  "billing_address2": "2nd floor",
  "billing_address_supplement": "Finance dept.",
  "billing_zip_code": "1015 CJ",
  "billing_city": "Amsterdam",
  "billing_region": "Noord-Holland",
  "billing_country_code": "NL",
  "billing_email": "[email protected]",
  "total_weight": 8.0,
  "total_length": 80,
  "total_width": 25,
  "total_height": 25,
  "total_order_price": 749.95,
  "total_order_currency": "EUR",
  "order_products": [
    {
      "order_product_id": 868,
      "remote_order_product_id": "NL-PROD-001",
      "ean": "8719326583655",
      "sku": null,
      "quantity": 1,
      "product_title": "North Orbit Kite 2025 - 12m",
      "order_product_price": 699.95,
      "order_product_price_currency": "EUR",
      "product_weight": "5.00",
      "product_length": 80,
      "product_width": 25,
      "product_height": 15,
      "product_hs_code": "95062900",
      "product_origin_country_code": "NL"
    },
    {
      "order_product_id": 869,
      "remote_order_product_id": "NL-PROD-002",
      "ean": "8719326583617",
      "sku": "PUMP-PRO",
      "quantity": 1,
      "product_title": "Mystic Kite Pump Pro",
      "order_product_price": 50.0,
      "order_product_price_currency": "EUR",
      "product_weight": "3.00",
      "product_length": 40,
      "product_width": 10,
      "product_height": 10,
      "product_hs_code": "84142080",
      "product_origin_country_code": "DE"
    }
  ]
}

Veld	Beschrijving
order_id	Het order-ID in ChannelDock.
remote_order_id	Het ordernummer in het verkoopkanaal (bijvoorbeeld het bol- of Amazon-ordernummer).
seller_id, center_id	De verkoper van de order. `center_id` is gevuld als een fulfillmentcenter het label aanmaakt, anders is het `0`.
api_id, api_description, channel_name	De verkoopkanaalkoppeling waar de order vandaan komt.
remote_carrier_id	Jouw eigen ID van de gekozen verzendmethode, zoals geregistreerd in stap 2. Gebruik dit om te bepalen welke service je boekt.
carrier_code	De `carrier_code` van de gekozen verzendmethode.
number_of_labels	Het aantal labels (colli) dat de gebruiker heeft aangevraagd.
sender_details	Het afzenderadres, inclusief btw- en EORI-nummer als die bekend zijn.
shipping_*	Het afleveradres. Gebruik `shipping_street`, `shipping_house_number` en `shipping_house_number_ext` als je systeem losse velden nodig heeft; `shipping_address1` en `shipping_address2` bevatten de volledige adresregels.
billing_*	Het factuuradres.
total_weight	Totaalgewicht van het pakket in kg.
total_length, total_width, total_height	Afmetingen van het pakket in cm.
total_order_price, total_order_currency	Totale waarde van de orderproducten, bijvoorbeeld voor douane en verzekering.
order_products	De producten in de order, met EAN, SKU, aantal, prijs, gewicht (kg), afmetingen (cm), HS-code en land van herkomst.

Velden kunnen null of leeg zijn als de gegevens niet in ChannelDock bekend zijn, dus behandel niet elk veld als verplicht. Bij zendingen buiten de EU verstuurt ChannelDock de aanvraag alleen als elk product een gewicht heeft.

Stap 4: Het label terugsturen

Maak het label aan in je systeem en antwoord met HTTP-status 200 en de volgende JSON:

{
  "label_id": "99999",
  "carrier_code": "dhl",
  "tracking_number": "JVGL0123456789",
  "tracking_number_url": "https://www.dhl.com/nl-en/home/tracking.html?tracking-id=JVGL0123456789",
  "pdf_content_base64": "JVBERi0xLjQKJeLjzgo8PC9UeXBlL0NhdGFsb2cvUG..."
}

Veld	Verplicht	Beschrijving
label_id	Ja	Het label-ID in jouw systeem.
carrier_code	Ja	De vervoerder die het pakket daadwerkelijk bezorgt (bijvoorbeeld `dhl`, `postnl`, `ups`). ChannelDock geeft dit door aan het verkoopkanaal, dus het moet bij het trackingnummer passen.
tracking_number	Aanbevolen	Het trackingnummer van diezelfde vervoerder. Zonder trackingnummer wordt het label wel aangemaakt, maar ontvangt het verkoopkanaal geen trackingnummer.
tracking_number_url	Aanbevolen	De link om de zending te volgen op de website van de vervoerder.
pdf_content_base64	Ja	Het label als PDF-bestand, Base64-gecodeerd, op A6-formaat. Is `number_of_labels` hoger dan 1, stuur dan alle labels terug in één PDF.

Ontbreekt label_id, carrier_code of pdf_content_base64, dan ziet de gebruiker de foutmelding “Missing field in JSON response” en wordt er geen label aangemaakt.

ChannelDock slaat het label vervolgens op, zet het klaar om te printen en stuurt het trackingnummer naar het verkoopkanaal.

Foutafhandeling

Kun je het label niet aanmaken (bijvoorbeeld omdat het adres ongeldig is), antwoord dan met een HTTP-statuscode in de 400-reeks en een melding:

{
  "error": {
    "message": "House number is missing in the delivery address"
  }
}

De gebruiker ziet dan de volgende foutmelding in ChannelDock:

Please contact the owner of this shipment method (integration) for support assistance. Shipping error 400 from mycarrier: House number is missing in the delivery address.

Schrijf de melding zo dat de gebruiker weet wat er aangepast moet worden. De gebruiker wacht op het label, dus antwoord binnen een paar seconden.

Testen en problemen oplossen

Maak een testorder aan in het account van de verkoper of het fulfillmentcenter en maak een label aan met jouw verzendmethode.
ChannelDock logt het request naar jouw API en jouw antwoord (zonder de PDF-inhoud) in de log van de order. Open de order in ChannelDock om precies te zien wat er is verstuurd en ontvangen.
Verschijnt je verzendmethode niet bij het aanmaken van een label? Controleer de gewichts- en afmetingsgrenzen, mailbox_size en of er een route bestaat voor het verzend- en bestemmingsland van de order.

Was this helpful?