Verbindung zur benutzerdefinierten Carrier-API herstellen

Last updated

ChannelDock bietet eine große Auswahl vorgefertigter Spediteur-Integrationen, die Verkäufer und Fulfillment-Center sofort nutzen können. Da wir nicht mit jeder Spediteurplattform eine Verbindung aufbauen können, bieten wir zusätzlich eine Custom Carrier API an. Damit können Sie als Spediteur (oder Versandplattform) eigene Versandmethoden zum ChannelDock-Konto eines Verkäufers oder Fulfillment-Centers hinzufügen und die Versandetiketten selbst erstellen.

So funktioniert es

Sie registrieren Ihre Versandmethoden im ChannelDock-Konto des Verkäufers oder Fulfillment-Centers über die ChannelDock REST API.
Der Nutzer wählt Ihre Versandmethode beim Erstellen eines Versandetiketts in ChannelDock aus.
ChannelDock ruft Ihre API auf und übermittelt die Bestelldaten sowie die gewählte Versandmethode.
Ihre API liefert das Etikett als PDF zusammen mit der Sendungsnummer zurück.
ChannelDock druckt das Etikett und übermittelt die Sendungsnummer an den Verkaufskanal (zum Beispiel bol oder Amazon), sodass die Bestellung als versandt markiert wird.

Sie entwickeln zwei Dinge: ein Skript, das Ihre Versandmethoden registriert (Schritt 1), und einen Endpunkt auf Ihrer Seite, der Etiketten erstellt (Schritte 3 und 4).

Schritt 1: API-Zugangsdaten erhalten

Die Versandmethoden werden im Konto des Verkäufers oder Fulfillment-Centers erstellt, das sie nutzen wird. Dieses Konto erzeugt die API-Zugangsdaten und gibt sie an Sie weiter:

Verkäufer: Einstellungen → API & Webhooks
Fulfillment-Center: Einstellungen → API & Webhooks

Sind die Endpunkt-Berechtigungen für den API-Schlüssel eingeschränkt, stellen Sie sicher, dass der Schlüssel Zugriff auf den Endpunkt shipment methods hat. Weitere Informationen zu API-Schlüsseln finden Sie in der ChannelDock REST API-Dokumentation.

Schritt 2: Versandmethoden registrieren

Senden Sie Ihre Versandmethoden an den Endpunkt, der zum Kontotyp passt:

Konto	Methode	Endpunkt
Verkäufer	POST	`https://channeldock.com/portal/api/v2/seller/shipmentmethods`
Fulfillment-Center	POST	`https://channeldock.com/portal/api/v2/center/shipmentmethods`

Die Authentifizierung erfolgt über die Header api-key und api-secret.

Diesen Endpunkt in der API-Dokumentation finden

Öffnen Sie docs.channeldock.com und gehen Sie zu ChannelDock Seller (oder ChannelDock Fulfillment Center) → Shipment methods → Create / Update custom shipment method. Sie können auch nach “custom shipment method” suchen. Wir verlinken nicht direkt auf den Abschnitt, da sich diese Links bei jeder Neuveröffentlichung der API-Dokumentation ändern.

Beispielanfrage

{
  "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 }
  ]
}

Feld	Pflicht	Beschreibung
name	Ja	Name der Versandmethode, wird dem Nutzer angezeigt. Dient auch dazu, eine bestehende Methode wiederzuerkennen (siehe unten).
remote_carrier_id	Ja	Ihre eigene ID für diese Versandmethode. Wir senden sie bei jeder Etikettanfrage zurück.
carrier_code	Ja	Kleingeschriebener Code Ihrer Plattform oder Ihres Spediteurs, zum Beispiel `mycarrier` oder `dhl`.
logo_url	Ja	Öffentliche URL eines PNG-Logos mit 700 x 300 Pixeln.
min_weight, max_weight	Ja	Gewichtsgrenzen in kg.
max_x, max_y, max_z	Ja	Maximale Abmessungen in cm.
mailbox_size	Ja	`1`, wenn die Methode für Briefkastenpakete gilt, andernfalls `0`. Bei `1` wird die Methode nur angezeigt, wenn das Paket in den Briefkasten passt.
callback_request	Ja	Wie ChannelDock Ihren Etikett-Endpunkt aufruft: `url`, `method` (wir empfehlen `POST`) und `headers` (ein Objekt, zum Beispiel mit Ihrem eigenen Authentifizierungs-Token).
shipment_method_countries	Ja	Mindestens eine Route mit `country_code_from`, `country_code_to` (2-stellige ISO-Codes) und `price`. Die Methode wird nur für diese Routen angeboten.

Gut zu wissen

Erstellen oder aktualisieren: ChannelDock sucht im Konto nach einer bestehenden Versandmethode mit demselben name. Existiert sie, wird sie aktualisiert (einschließlich remote_carrier_id und callback_request). Andernfalls wird eine neue erstellt. Wenn Sie den name ändern, entsteht daher eine zweite Versandmethode; die alte bleibt bestehen.
Routen werden hinzugefügt oder aktualisiert, nie entfernt: Eine Route, die Sie in der Anfrage weglassen, bleibt mit ihrem bisherigen Preis aktiv.
Mehrere Methoden auf einmal: Senden Sie ein Array von Versandmethoden-Objekten statt eines einzelnen Objekts. Die Antwort zeigt dann das Ergebnis pro Methode.
Fulfillment-Center können ihre Versandmethoden mit GET https://channeldock.com/portal/api/v2/center/shipmentmethods abrufen.

Antwort

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

Schritt 3: Etikettanfrage empfangen

Sobald ein ChannelDock-Nutzer ein Versandetikett mit einer Ihrer Versandmethoden erstellt, ruft ChannelDock die url aus callback_request auf, mit der von Ihnen angegebenen method und den angegebenen headers. Bei POST (empfohlen) werden die Bestelldaten als JSON-Body gesendet. Bei GET werden dieselben Felder als Query-Parameter gesendet.

Beispielanfrage von 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"
    }
  ]
}

Feld	Beschreibung
order_id	Die Bestell-ID in ChannelDock.
remote_order_id	Die Bestellnummer im Verkaufskanal (zum Beispiel die Bestellnummer von bol oder Amazon).
seller_id, center_id	Der Verkäufer, zu dem die Bestellung gehört. `center_id` ist gefüllt, wenn ein Fulfillment-Center das Etikett erstellt, andernfalls `0`.
api_id, api_description, channel_name	Die Verbindung zum Verkaufskanal, aus der die Bestellung stammt.
remote_carrier_id	Ihre eigene ID der gewählten Versandmethode, wie in Schritt 2 registriert. Verwenden Sie sie, um zu entscheiden, welchen Service Sie buchen.
carrier_code	Der `carrier_code` der gewählten Versandmethode.
number_of_labels	Die Anzahl der vom Nutzer angeforderten Etiketten (Pakete).
sender_details	Die Absenderadresse, einschließlich USt-IdNr. und EORI-Nummer, sofern vorhanden.
shipping_*	Die Lieferadresse. Verwenden Sie `shipping_street`, `shipping_house_number` und `shipping_house_number_ext`, wenn Ihr System getrennte Felder benötigt; `shipping_address1` und `shipping_address2` enthalten die vollständigen Adresszeilen.
billing_*	Die Rechnungsadresse.
total_weight	Gesamtgewicht des Pakets in kg.
total_length, total_width, total_height	Paketabmessungen in cm.
total_order_price, total_order_currency	Gesamtwert der Bestellprodukte, zum Beispiel für Zoll und Versicherung.
order_products	Die Produkte der Bestellung, einschließlich EAN, SKU, Menge, Preis, Gewicht (kg), Abmessungen (cm), HS-Code und Ursprungsland.

Felder können null oder leer sein, wenn die Daten in ChannelDock nicht vorhanden sind. Behandeln Sie daher nicht jedes Feld als Pflichtfeld. Bei Sendungen außerhalb der EU sendet ChannelDock die Anfrage nur, wenn für jedes Produkt ein Gewicht vorliegt.

Schritt 4: Etikett zurückgeben

Erstellen Sie das Etikett in Ihrem System und antworten Sie mit dem HTTP-Status 200 und folgendem 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..."
}

Feld	Pflicht	Beschreibung
label_id	Ja	Die Etikett-ID in Ihrem System.
carrier_code	Ja	Der Spediteur, der das Paket tatsächlich zustellt (zum Beispiel `dhl`, `postnl`, `ups`). ChannelDock gibt diesen Wert an den Verkaufskanal weiter, er muss daher zur Sendungsnummer passen.
tracking_number	Empfohlen	Die Sendungsnummer desselben Spediteurs. Ohne sie wird das Etikett trotzdem erstellt, der Verkaufskanal erhält jedoch keine Sendungsnummer.
tracking_number_url	Empfohlen	Der Link zur Sendungsverfolgung auf der Website des Spediteurs.
pdf_content_base64	Ja	Das Etikett als PDF-Datei, Base64-kodiert, im A6-Format. Ist `number_of_labels` größer als 1, geben Sie alle Etiketten in einem PDF zurück.

Fehlt label_id, carrier_code oder pdf_content_base64, sieht der Nutzer die Fehlermeldung “Missing field in JSON response” und es wird kein Etikett erstellt.

Anschließend speichert ChannelDock das Etikett, stellt es zum Drucken bereit und übermittelt die Sendungsnummer an den Verkaufskanal.

Fehlerbehandlung

Wenn Sie das Etikett nicht erstellen können (zum Beispiel weil die Adresse ungültig ist), antworten Sie mit einem HTTP-Statuscode aus dem 400er-Bereich und einer Meldung:

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

Der Nutzer sieht dann in ChannelDock die folgende Fehlermeldung:

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.

Formulieren Sie die Meldung so, dass der Nutzer weiß, was zu korrigieren ist. Der Nutzer wartet auf das Etikett, antworten Sie daher innerhalb weniger Sekunden.

Testen und Fehlerbehebung

Erstellen Sie eine Testbestellung im Konto des Verkäufers oder Fulfillment-Centers und erstellen Sie ein Etikett mit Ihrer Versandmethode.
ChannelDock protokolliert die an Ihre API gesendete Anfrage und Ihre Antwort (ohne PDF-Inhalt) im Protokoll der Bestellung. Öffnen Sie die Bestellung in ChannelDock, um genau zu sehen, was gesendet und empfangen wurde.
Erscheint Ihre Versandmethode beim Erstellen eines Etiketts nicht? Prüfen Sie die Gewichts- und Abmessungsgrenzen, mailbox_size und ob eine Route für das Absender- und Zielland der Bestellung existiert.

Was this helpful?