Connexion d'une API transporteur personnalisée

Last updated

ChannelDock propose un large éventail d’intégrations transporteur prêtes à l’emploi que les vendeurs et centres de fulfillment peuvent utiliser immédiatement. Comme nous ne pouvons pas créer une connexion avec chaque plateforme de transporteur, nous proposons également une Custom Carrier API. Elle vous permet, en tant que transporteur (ou plateforme d’expédition), d’ajouter vos propres méthodes d’expédition au compte ChannelDock d’un vendeur ou d’un centre de fulfillment, et de créer vous-même les étiquettes d’expédition.

Fonctionnement

Vous enregistrez vos méthodes d’expédition dans le compte ChannelDock du vendeur ou du centre de fulfillment, via l’API REST de ChannelDock.
L’utilisateur sélectionne votre méthode d’expédition lors de la création d’une étiquette d’expédition dans ChannelDock.
ChannelDock appelle votre API avec les données de la commande et la méthode d’expédition sélectionnée.
Votre API renvoie l’étiquette au format PDF, accompagnée du numéro de suivi.
ChannelDock imprime l’étiquette et envoie le numéro de suivi au canal de vente (par exemple bol ou Amazon), afin que la commande soit marquée comme expédiée.

Vous développez deux éléments : un script qui enregistre vos méthodes d’expédition (étape 1) et un endpoint de votre côté qui crée les étiquettes (étapes 3 et 4).

Étape 1 : obtenir les identifiants API

Les méthodes d’expédition sont créées dans le compte du vendeur ou du centre de fulfillment qui les utilisera. Ce compte génère les identifiants API et vous les transmet :

Vendeur : Paramètres → API & Webhooks
Centre de fulfillment : Paramètres → API & Webhooks

Si les autorisations par endpoint sont limitées sur la clé API, assurez-vous que la clé a accès à l’endpoint shipment methods. Pour en savoir plus sur les clés API, consultez la documentation de l’API REST ChannelDock.

Étape 2 : enregistrer vos méthodes d’expédition

Envoyez vos méthodes d’expédition à l’endpoint correspondant au type de compte :

Compte	Méthode	Endpoint
Vendeur	POST	`https://channeldock.com/portal/api/v2/seller/shipmentmethods`
Centre de fulfillment	POST	`https://channeldock.com/portal/api/v2/center/shipmentmethods`

Authentifiez-vous avec les en-têtes api-key et api-secret.

Trouver cet endpoint dans la documentation de l’API

Ouvrez docs.channeldock.com et allez à ChannelDock Seller (ou ChannelDock Fulfillment Center) → Shipment methods → Create / Update custom shipment method. Vous pouvez aussi rechercher “custom shipment method”. Nous ne proposons pas de lien direct vers cette section, car ces liens changent à chaque nouvelle publication de la documentation de l’API.

Exemple de requête

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

Champ	Obligatoire	Description
name	Oui	Nom de la méthode d’expédition, affiché à l’utilisateur. Sert aussi à reconnaître une méthode existante (voir ci-dessous).
remote_carrier_id	Oui	Votre propre ID pour cette méthode d’expédition. Nous le renvoyons à chaque demande d’étiquette.
carrier_code	Oui	Code en minuscules de votre plateforme ou transporteur, par exemple `mycarrier` ou `dhl`.
logo_url	Oui	URL publique d’un logo PNG de 700 x 300 pixels.
min_weight, max_weight	Oui	Limites de poids en kg.
max_x, max_y, max_z	Oui	Dimensions maximales en cm.
mailbox_size	Oui	`1` si la méthode concerne les colis boîte aux lettres, sinon `0`. Avec `1`, la méthode n’est affichée que si le colis passe dans la boîte aux lettres.
callback_request	Oui	Comment ChannelDock appelle votre endpoint d’étiquettes : `url`, `method` (nous recommandons `POST`) et `headers` (un objet, par exemple avec votre propre jeton d’authentification).
shipment_method_countries	Oui	Au moins un trajet avec `country_code_from`, `country_code_to` (codes ISO à 2 lettres) et `price`. La méthode n’est proposée que pour ces trajets.

Bon à savoir

Créer ou mettre à jour : ChannelDock recherche dans le compte une méthode d’expédition existante portant le même name. Si elle existe, elle est mise à jour (y compris remote_carrier_id et callback_request). Sinon, une nouvelle méthode est créée. Modifier le name crée donc une seconde méthode d’expédition ; l’ancienne reste en place.
Les trajets sont ajoutés ou mis à jour, jamais supprimés : un trajet que vous omettez de la requête reste actif avec son prix précédent.
Plusieurs méthodes à la fois : envoyez un tableau d’objets de méthodes d’expédition au lieu d’un seul objet. La réponse indique alors le résultat pour chaque méthode.
Les centres de fulfillment peuvent récupérer leurs méthodes d’expédition avec GET https://channeldock.com/portal/api/v2/center/shipmentmethods.

Réponse

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

Étape 3 : recevoir la demande d’étiquette

Dès qu’un utilisateur ChannelDock crée une étiquette d’expédition avec l’une de vos méthodes d’expédition, ChannelDock appelle l’url de callback_request, avec la method et les headers que vous avez fournis. Avec POST (recommandé), les données de la commande sont envoyées dans un corps JSON. Avec GET, les mêmes champs sont envoyés en paramètres de requête.

Exemple de requête de 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"
    }
  ]
}

Champ	Description
order_id	L’ID de la commande dans ChannelDock.
remote_order_id	Le numéro de commande dans le canal de vente (par exemple le numéro de commande bol ou Amazon).
seller_id, center_id	Le vendeur auquel appartient la commande. `center_id` est renseigné lorsqu’un centre de fulfillment crée l’étiquette, sinon il vaut `0`.
api_id, api_description, channel_name	La connexion au canal de vente d’où provient la commande.
remote_carrier_id	Votre propre ID de la méthode d’expédition sélectionnée, tel qu’enregistré à l’étape 2. Utilisez-le pour décider quel service réserver.
carrier_code	Le `carrier_code` de la méthode d’expédition sélectionnée.
number_of_labels	Le nombre d’étiquettes (colis) demandé par l’utilisateur.
sender_details	L’adresse de l’expéditeur, y compris le numéro de TVA et le numéro EORI lorsqu’ils sont disponibles.
shipping_*	L’adresse de livraison. Utilisez `shipping_street`, `shipping_house_number` et `shipping_house_number_ext` si votre système a besoin de champs séparés ; `shipping_address1` et `shipping_address2` contiennent les lignes d’adresse complètes.
billing_*	L’adresse de facturation.
total_weight	Poids total du colis en kg.
total_length, total_width, total_height	Dimensions du colis en cm.
total_order_price, total_order_currency	Valeur totale des produits de la commande, par exemple pour la douane et l’assurance.
order_products	Les produits de la commande, avec EAN, SKU, quantité, prix, poids (kg), dimensions (cm), code SH et pays d’origine.

Les champs peuvent être null ou vides lorsque la donnée n’est pas disponible dans ChannelDock ; ne considérez donc pas chaque champ comme obligatoire. Pour les envois hors UE, ChannelDock n’envoie la requête que si chaque produit a un poids.

Étape 4 : renvoyer l’étiquette

Créez l’étiquette dans votre système et répondez avec le statut HTTP 200 et le JSON suivant :

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

Champ	Obligatoire	Description
label_id	Oui	L’ID de l’étiquette dans votre système.
carrier_code	Oui	Le transporteur qui livre réellement le colis (par exemple `dhl`, `postnl`, `ups`). ChannelDock transmet cette valeur au canal de vente, elle doit donc correspondre au numéro de suivi.
tracking_number	Recommandé	Le numéro de suivi de ce même transporteur. Sans lui, l’étiquette est tout de même créée, mais le canal de vente ne reçoit pas de numéro de suivi.
tracking_number_url	Recommandé	Le lien permettant de suivre l’envoi sur le site du transporteur.
pdf_content_base64	Oui	L’étiquette sous forme de fichier PDF, encodé en Base64, au format A6. Si `number_of_labels` est supérieur à 1, renvoyez toutes les étiquettes dans un seul PDF.

Si label_id, carrier_code ou pdf_content_base64 est manquant, l’utilisateur voit l’erreur “Missing field in JSON response” et aucune étiquette n’est créée.

ChannelDock enregistre ensuite l’étiquette, la met à disposition pour l’impression et envoie le numéro de suivi au canal de vente.

Gestion des erreurs

Si vous ne pouvez pas créer l’étiquette (par exemple parce que l’adresse est invalide), répondez avec un code de statut HTTP de la plage 400 et un message :

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

L’utilisateur voit alors l’erreur suivante dans 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.

Rédigez le message de sorte que l’utilisateur sache ce qu’il doit corriger. L’utilisateur attend l’étiquette ; répondez donc en quelques secondes.

Tests et dépannage

Créez une commande de test dans le compte du vendeur ou du centre de fulfillment, puis créez une étiquette avec votre méthode d’expédition.
ChannelDock consigne la requête envoyée à votre API et votre réponse (sans le contenu du PDF) dans le journal de la commande. Ouvrez la commande dans ChannelDock pour voir exactement ce qui a été envoyé et reçu.
Votre méthode d’expédition n’apparaît pas lors de la création d’une étiquette ? Vérifiez les limites de poids et de dimensions, mailbox_size, et s’il existe un trajet pour le pays d’expédition et le pays de destination de la commande.

Was this helpful?