Conexión de API de transportista personalizada

Last updated

ChannelDock ofrece una amplia gama de integraciones de transportistas preconfiguradas que vendedores y centros de fulfillment pueden usar de inmediato. Como no podemos crear una conexión con cada plataforma de transportistas, también ofrecemos una Custom Carrier API. Con ella, usted, como transportista (o plataforma de envíos), puede añadir sus propios métodos de envío a la cuenta de ChannelDock de un vendedor o centro de fulfillment y crear usted mismo las etiquetas de envío.

Cómo funciona

Usted registra sus métodos de envío en la cuenta de ChannelDock del vendedor o centro de fulfillment, mediante la API REST de ChannelDock.
El usuario selecciona su método de envío al crear una etiqueta de envío en ChannelDock.
ChannelDock llama a su API con los datos del pedido y el método de envío seleccionado.
Su API devuelve la etiqueta en PDF, junto con el número de seguimiento.
ChannelDock imprime la etiqueta y envía el número de seguimiento al canal de venta (por ejemplo bol o Amazon), de modo que el pedido se marque como enviado.

Usted desarrolla dos cosas: un script que registra sus métodos de envío (paso 1) y un endpoint por su parte que crea las etiquetas (pasos 3 y 4).

Paso 1: obtener las credenciales API

Los métodos de envío se crean en la cuenta del vendedor o centro de fulfillment que los utilizará. Esa cuenta genera las credenciales API y se las facilita a usted:

Vendedor: Ajustes → API & Webhooks
Centro de fulfillment: Ajustes → API & Webhooks

Si los permisos por endpoint están limitados en la clave API, asegúrese de que la clave tenga acceso al endpoint shipment methods. Para más información sobre las claves API, consulte la documentación de la API REST de ChannelDock.

Paso 2: registrar sus métodos de envío

Envíe sus métodos de envío al endpoint que corresponda al tipo de cuenta:

Cuenta	Método	Endpoint
Vendedor	POST	`https://channeldock.com/portal/api/v2/seller/shipmentmethods`
Centro de fulfillment	POST	`https://channeldock.com/portal/api/v2/center/shipmentmethods`

Autentíquese con las cabeceras api-key y api-secret.

Cómo encontrar este endpoint en la documentación de la API

Abra docs.channeldock.com y vaya a ChannelDock Seller (o ChannelDock Fulfillment Center) → Shipment methods → Create / Update custom shipment method. También puede buscar “custom shipment method”. No enlazamos directamente a la sección, porque esos enlaces cambian cada vez que se vuelve a publicar la documentación de la API.

Ejemplo de solicitud

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

Campo	Obligatorio	Descripción
name	Sí	Nombre del método de envío, que se muestra al usuario. También sirve para reconocer un método existente (véase más abajo).
remote_carrier_id	Sí	Su propio ID para este método de envío. Lo devolvemos con cada solicitud de etiqueta.
carrier_code	Sí	Código en minúsculas de su plataforma o transportista, por ejemplo `mycarrier` o `dhl`.
logo_url	Sí	URL pública de un logotipo PNG de 700 x 300 píxeles.
min_weight, max_weight	Sí	Límites de peso en kg.
max_x, max_y, max_z	Sí	Dimensiones máximas en cm.
mailbox_size	Sí	`1` si el método es para paquetes de buzón, de lo contrario `0`. Con `1`, el método solo se muestra si el paquete cabe en el buzón.
callback_request	Sí	Cómo llama ChannelDock a su endpoint de etiquetas: `url`, `method` (recomendamos `POST`) y `headers` (un objeto, por ejemplo con su propio token de autenticación).
shipment_method_countries	Sí	Al menos una ruta con `country_code_from`, `country_code_to` (códigos ISO de 2 letras) y `price`. El método solo se ofrece para estas rutas.

Conviene saber

Crear o actualizar: ChannelDock busca en la cuenta un método de envío existente con el mismo name. Si existe, se actualiza (incluidos remote_carrier_id y callback_request). Si no, se crea uno nuevo. Por tanto, cambiar el name crea un segundo método de envío; el anterior se conserva.
Las rutas se añaden o se actualizan, nunca se eliminan: una ruta que omita en la solicitud permanece activa con su precio anterior.
Varios métodos a la vez: envíe un array de objetos de método de envío en lugar de un único objeto. La respuesta muestra entonces el resultado de cada método.
Los centros de fulfillment pueden consultar sus métodos de envío con GET https://channeldock.com/portal/api/v2/center/shipmentmethods.

Respuesta

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

Paso 3: recibir la solicitud de etiqueta

En cuanto un usuario de ChannelDock crea una etiqueta de envío con uno de sus métodos de envío, ChannelDock llama a la url de callback_request, con el method y los headers que usted indicó. Con POST (recomendado), los datos del pedido se envían como cuerpo JSON. Con GET, los mismos campos se envían como parámetros de consulta.

Ejemplo de solicitud 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"
    }
  ]
}

Campo	Descripción
order_id	El ID del pedido en ChannelDock.
remote_order_id	El número de pedido en el canal de venta (por ejemplo, el número de pedido de bol o Amazon).
seller_id, center_id	El vendedor al que pertenece el pedido. `center_id` se rellena cuando un centro de fulfillment crea la etiqueta; de lo contrario es `0`.
api_id, api_description, channel_name	La conexión con el canal de venta de la que procede el pedido.
remote_carrier_id	Su propio ID del método de envío seleccionado, tal como se registró en el paso 2. Utilícelo para decidir qué servicio reservar.
carrier_code	El `carrier_code` del método de envío seleccionado.
number_of_labels	El número de etiquetas (paquetes) que solicitó el usuario.
sender_details	La dirección del remitente, incluidos el número de IVA y el número EORI cuando estén disponibles.
shipping_*	La dirección de entrega. Use `shipping_street`, `shipping_house_number` y `shipping_house_number_ext` si su sistema necesita campos separados; `shipping_address1` y `shipping_address2` contienen las líneas de dirección completas.
billing_*	La dirección de facturación.
total_weight	Peso total del paquete en kg.
total_length, total_width, total_height	Dimensiones del paquete en cm.
total_order_price, total_order_currency	Valor total de los productos del pedido, por ejemplo para aduanas y seguro.
order_products	Los productos del pedido, con EAN, SKU, cantidad, precio, peso (kg), dimensiones (cm), código HS y país de origen.

Los campos pueden ser null o estar vacíos cuando el dato no está disponible en ChannelDock, así que no trate todos los campos como obligatorios. En envíos fuera de la UE, ChannelDock solo envía la solicitud si todos los productos tienen peso.

Paso 4: devolver la etiqueta

Cree la etiqueta en su sistema y responda con el estado HTTP 200 y el siguiente 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..."
}

Campo	Obligatorio	Descripción
label_id	Sí	El ID de la etiqueta en su sistema.
carrier_code	Sí	El transportista que realmente entrega el paquete (por ejemplo `dhl`, `postnl`, `ups`). ChannelDock transmite este valor al canal de venta, por lo que debe coincidir con el número de seguimiento.
tracking_number	Recomendado	El número de seguimiento de ese mismo transportista. Sin él, la etiqueta se crea igualmente, pero el canal de venta no recibe número de seguimiento.
tracking_number_url	Recomendado	El enlace para seguir el envío en el sitio web del transportista.
pdf_content_base64	Sí	La etiqueta como archivo PDF, codificado en Base64, en formato A6. Si `number_of_labels` es mayor que 1, devuelva todas las etiquetas en un solo PDF.

Si falta label_id, carrier_code o pdf_content_base64, el usuario ve el error “Missing field in JSON response” y no se crea ninguna etiqueta.

A continuación, ChannelDock guarda la etiqueta, la deja disponible para imprimir y envía el número de seguimiento al canal de venta.

Gestión de errores

Si no puede crear la etiqueta (por ejemplo, porque la dirección no es válida), responda con un código de estado HTTP del rango 400 y un mensaje:

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

El usuario verá entonces el siguiente error en 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.

Redacte el mensaje de modo que el usuario sepa qué debe corregir. El usuario está esperando la etiqueta, así que responda en pocos segundos.

Pruebas y resolución de problemas

Cree un pedido de prueba en la cuenta del vendedor o centro de fulfillment y cree una etiqueta con su método de envío.
ChannelDock registra la solicitud enviada a su API y su respuesta (sin el contenido del PDF) en el registro del pedido. Abra el pedido en ChannelDock para ver exactamente qué se envió y qué se recibió.
¿Su método de envío no aparece al crear una etiqueta? Compruebe los límites de peso y dimensiones, mailbox_size y si existe una ruta para el país de origen y de destino del pedido.

Was this helpful?