Configurar módulos de transportista en PrestaShop: guía paso a paso

La mecánica de los módulos de transportista que se explica a continuación (objeto Carrier creado en install(), tarifas externas mediante getOrderShippingCostExternal, interfaz de taquillas mediante displayCarrierExtraContent) se mantiene desde PrestaShop 1.7 hasta 8 y 9; en PS9 la visualización de varios transportistas queda detrás de una bandera de funcionalidad, como se indica al final.

En PrestaShop hay dos cosas completamente distintas a las que se suele llamar "configurar un transportista", y mezclarlas es justo donde muchos comerciantes se atascan. La primera es crear un transportista a mano en el back office, un nombre, algunas zonas, una tabla de precios, una infraestructura que PrestaShop siempre ha incluido. La segunda es instalar un módulo de transportista: un software que registra uno o varios transportistas por ti, se comunica con la API de una empresa de mensajería real, imprime etiquetas, obtiene tarifas en tiempo real y añade mapas de puntos de recogida al proceso de pago. Esta guía trata sobre lo segundo: qué es realmente un módulo de transportista, cómo se integra en PrestaShop, cómo instalarlo y configurarlo sin romper el proceso de pago, y cómo distinguir uno bueno de uno que puede darte problemas. Para crear transportistas manualmente a partir de zonas y rangos, el trabajo es distinto y lo cubrimos en la guía completa de configuración de envíos.

Qué es realmente un módulo de transportista (y por qué es distinto de un transportista del back office)

Cuando vas a Envío → Transportistas y haces clic en "Añadir nuevo transportista", creas una fila en la tabla ps_carrier que PrestaShop evalúa frente al carrito durante el proceso de pago. Es estático: el precio sale de una tabla que tú has introducido, y el transportista no sabe nada de la empresa de mensajería más allá de un nombre y una plantilla de URL de seguimiento. Eso está bien para "Envío estándar 5,99 €", y es la herramienta adecuada para muchas tiendas.

Un módulo de transportista es otra cosa. Al instalarse, crea programáticamente sus propios transportistas: instancia la clase Carrier en su método install(), define id_reference, rangos, zonas y grupos en el código, y guarda el ID del transportista resultante en su propia configuración para poder gestionarlo entre actualizaciones. A partir de ese momento, el módulo es el propietario de ese transportista. El esqueleto de esa creación se ve así; fíjate en los tres campos que convierten un transportista normal en un transportista de módulo:

// Inside the module's install() – create a carrier the module owns.
$carrier = new Carrier();
$carrier->name = 'Pickup Point Delivery';
$carrier->active = true;
$carrier->shipping_handling = false;
$carrier->range_behavior = 0;
$carrier->delay = ['en' => '1-2 business days']; // shown verbatim at checkout
$carrier->shipping_external = true;                // PS asks the module for the price
$carrier->need_range = true;                       // false = pure external rating
$carrier->external_module_name = $this->name;      // links the carrier back to this module
$carrier->is_module = true;
if ($carrier->add()) {
    // Remember the ID so the module can manage/repair this carrier later.
    Configuration::updateValue('MYCARRIER_ID', (int) $carrier->id);
    // Then assign zones/groups and (optionally) a fallback range grid.
}

Como external_module_name conecta el transportista de vuelta con el módulo, PrestaShop sabe que debe llamar a este módulo para obtener el precio de ese transportista y la interfaz adicional en el proceso de pago; eso es lo que hace posibles los dos comportamientos siguientes. ¿Y qué consigues con eso? Comportamientos que una tabla estática no puede ofrecer:

• Tarifas en tiempo real. En lugar de usar un precio estimado, el módulo llama a la API de la mensajería durante el proceso de pago y devuelve el presupuesto real para el peso, las dimensiones y el destino de ese carrito, implementando getOrderShippingCostExternal() en un transportista marcado como transportista de módulo con need_range desactivado, de modo que PrestaShop pida el precio al módulo en vez de leer una tabla estática de rangos.
• Puntos de recogida. Los transportistas de puntos relais y taquillas insertan un mapa o un desplegable en el paso de entrega (mediante el hook displayCarrierExtraContent, el sustituto en 1.7+ del obsoleto displayCarrierList) para que el cliente elija una taquilla concreta, y el módulo guarda esa elección en el pedido. El hook solo se ejecuta para el transportista cuyo external_module_name apunta al módulo.
• Etiquetas y manifiestos. Un botón en el back office (o un hook de estado de pedido) genera el PDF de la etiqueta de envío de la mensajería y escribe el número de seguimiento directamente en el pedido, sin copiar y pegar en el portal propio de la empresa de transporte.
• Configuración que se autorrepara. Como el transportista se crea en código, el módulo puede recrearlo o actualizarlo después de una actualización de PrestaShop en lugar de obligarte a reconstruir una tabla de precios a mano.

La conclusión práctica: si tu empresa de mensajería ofrece un módulo oficial para PrestaShop, casi siempre te conviene usarlo antes que un transportista creado a mano; la versión manual no puede imprimir etiquetas ni calcular un precio real. Si tu transportista no lo ofrece, un transportista manual es tu alternativa, y la guía de configuración anterior es el punto de partida.

Antes de instalar nada: tres comprobaciones que evitan procesos de pago rotos

Los módulos de transportista tocan la página más delicada de tu tienda, así que el orden de las operaciones importa. El mayor temor de cualquier propietario de una tienda es que un módulo rompa el proceso de pago; gana esa confianza comprobando primero tres cosas.

• Compatibilidad con tu versión exacta. El panorama de la API de transportistas cambió entre PrestaShop 1.6 → 1.7 → 8 → 9; un módulo escrito para 1.6 puede registrar su transportista de una forma que 8.x ignore. Confirma que el módulo indica tu versión antes de comprarlo, no después.
• Una copia de staging. Nunca instales primero un módulo de transportista en producción. Clona la tienda, instálalo allí y realiza un pedido de prueba real para cada zona. Un transportista que no se registra correctamente aparece en el proceso de pago como el temido "no hay transportistas disponibles", y no quieres descubrirlo con clientes reales.
• Una copia de seguridad de la base de datos. Como estos módulos escriben en ps_carrier, ps_carrier_zone y las tablas de rangos durante la instalación, tener un punto de restauración limpio convierte una mala instalación en una reversión de cinco minutos en lugar de una tarde perdida.

La secuencia de instalación y configuración que sí funciona

La mayoría de los módulos oficiales de transportista siguen la misma lógica. Conocer la secuencia te permite configurar cualquiera de ellos, DHL, GLS, Colissimo, InPost, sin tener que reaprender el flujo cada vez.

• 1. Instala el módulo. Módulos → Gestor de módulos → Subir un módulo, suelta el ZIP e instálalo. En ese momento el módulo crea sus transportistas: ve a Envío → Transportistas y verás que aparecen automáticamente.

• 2. Introduce las credenciales de tu cuenta. Abre la configuración del módulo y pega la clave API, el ID de cliente o el número de contrato que te haya dado la empresa de mensajería. Esto es lo que separa un transportista con tarifas en tiempo real que funciona de uno muerto. La mayoría de los módulos tienen un botón de "probar conexión": úsalo; una marca verde aquí te evita un fallo en el proceso de pago más adelante.
• 3. Asigna zonas y servicios. El módulo ha creado un transportista, pero tú sigues decidiendo dónde envía y cuáles de los servicios de la mensajería (estándar, exprés, taquilla) muestras. Asigna el transportista a tus zonas desde su entrada en Envío → Transportistas, o dentro del propio módulo si gestiona las zonas por su cuenta.
• 4. Define el precio de respaldo. Los módulos con tarifas en tiempo real necesitan un respaldo para cuando la API de la mensajería agota el tiempo de espera; de lo contrario, una incidencia puntual de la API se convierte en un pedido perdido. Configura una tarifa plana razonable a la que el módulo pueda recurrir para que el proceso de pago nunca muestre cero transportistas.
• 5. Configura la manipulación y las opciones de etiqueta. Dirección del remitente, peso predeterminado del paquete, formato de etiqueta (A4 o térmica) y qué estado de pedido activa la generación de etiquetas.
• 6. Realiza un pedido de prueba real hasta el pago para cada zona, confirma que aparece el transportista, que la tarifa tiene sentido y que, si está soportado, se genera una etiqueta.

Transportista manual frente a módulo de transportista: cuál usar

Elegir módulos de mensajerías reales: las integraciones que existen

Una vez decidido que quieres un módulo, la pregunta es cuál; y eso depende de la empresa de mensajería, porque cada integración tiene sus propias particularidades (números de contrato, API de taquillas, formatos de etiqueta). En lugar de meterlas todas en una lista apresurada, aquí tienes el mapa hacia las guías por transportista:

• Los tres grandes internacionales. DHL, DPD y UPS cubren la mayoría de los envíos transfronterizos en la UE; su configuración, campos de contrato y flujo de etiquetas se explican en la guía de integración de DHL, DPD y UPS.
• GLS en varios países. Si envías a varios mercados con un único contrato GLS, la configuración multipaís tiene sus propias trampas; consulta la integración de envíos multipaís de GLS.
• Francia: Colissimo y Mondial Relay. Colissimo es la opción de transportista nacional por defecto para las tiendas francesas (guía de configuración de Colissimo); Mondial Relay añade la red de puntos relais que los compradores franceses esperan (entrega en puntos relais con Mondial Relay).
• Polonia: InPost Paczkomaty. Si vendes en Polonia y no ofreces entrega en taquillas, partes con una desventaja real; la integración del mapa de taquillas se cubre en InPost Paczkomaty para PrestaShop.

El problema de "no hay transportistas disponibles" y qué lo causa con los módulos

El fallo más común después de instalar un módulo de transportista es que el proceso de pago muestre que no hay opciones de envío en absoluto. Con un transportista creado a mano, casi siempre se debe a una asignación de zona que falta; con un módulo hay algunos sospechosos adicionales, porque el módulo ha añadido una capa más:

• El transportista del módulo no está asignado a la zona del cliente. El módulo creó el transportista, pero nunca asignaste tus países de destino a él. Corrígelo en Envío → Transportistas → las Ubicaciones y costes de envío del transportista.
• Ningún rango de precios cubre este carrito. Algunos módulos siguen dependiendo de una fila de rango por peso/precio para la disponibilidad o como respaldo, así que si la API no devuelve nada y ningún rango cubre el carrito, el transportista puede desaparecer. Un verdadero transportista con tarifa externa y need_range desactivado no dependerá en absoluto de una fila de rango estática, pero si el módulo dejó activo un requisito de rango, ese es un sospechoso.
• Las credenciales de la API son incorrectas o la API de la mensajería está caída. Sin un precio de respaldo, una llamada fallida a la API elimina silenciosamente el transportista. Exactamente por eso importa el paso 4 anterior.
• Restricción de grupo o tienda. El módulo puede asignar por defecto su transportista a un único grupo de clientes o a una sola tienda en multitienda. Revisa Acceso de grupo y Asociación de tienda en el transportista.
• El producto no tiene peso. Tanto los transportistas basados en peso como los de tarifas en tiempo real dependen de pesos reales de producto en el catálogo; según el módulo y la configuración de rangos, un peso ausente o de 0 kg puede romper el cálculo basado en peso o mediante API, o quedar fuera de todos los rangos configurados, de modo que el transportista calcula mal el precio o desaparece.

Para profundizar en la lógica de cómo encajan zonas, rangos y transportistas, el modelo al que se remontan todos estos errores, la guía completa de configuración de envíos es la referencia.

Los módulos de transportista son solo la mitad del trabajo: la mitad visible para el cliente también importa

Un módulo de transportista perfectamente instalado calcula el precio correcto e imprime la etiqueta, pero la experiencia del cliente alrededor de ese envío es una decisión aparte que no deberías pasar por alto:

• ¿Qué fecha de entrega ve el cliente? El campo de tiempo de tránsito integrado en PrestaShop muestra el mismo "3–7 días laborables" para todos los destinos, sin tener en cuenta la zona ni tu tiempo de preparación. Mostrar una fecha real es otro tema: consulta cómo fijar expectativas de entrega realistas y por qué una fecha concreta reduce la ansiedad del cliente. Nuestro módulo Estimated Delivery Date cubre ese hueco: calcula una fecha de llegada real por transportista y zona, teniendo en cuenta tu tiempo de preparación y los días laborables, de modo que un cliente alemán ve "Entrega: miércoles" mientras un cliente español ve "Entrega: viernes", sin que tengas que editar un archivo del tema.
• ¿Se le informa cuando el pedido se envía? El número de seguimiento que tu módulo escribió en el pedido solo sirve si llega al cliente; lo explicamos en números de seguimiento y notificaciones de entrega.
• ¿Qué cobras además de la tarifa de la mensajería? Trasladar las tarifas en tiempo real tal cual, aplanarlas o absorberlas dentro del envío gratuito es una decisión de margen; empieza por envío gratuito frente a tarifa plana frente a cálculo automático y, si tienes una tienda pequeña, estrategia de envíos para tiendas pequeñas.

La versión corta

"Configurar un módulo de transportista" no es lo mismo que añadir un transportista en el back office: un módulo instala software que controla su propio transportista, se comunica con la empresa de mensajería y hace cosas que una tabla de precios estática nunca podría hacer: tarifas en tiempo real, mapas de taquillas, etiquetas en un clic. Instálalo en staging con una copia de seguridad, introduce tus credenciales de contrato y prueba la conexión, define siempre un precio de respaldo para que una incidencia de la API no vacíe tu proceso de pago, y realiza un pedido de prueba real en cada zona antes de pasar a producción. Después elige la integración de mensajería adecuada para tus mercados y asegúrate de que la parte visible para el cliente, fechas de entrega, seguimiento y lo que cobras, esté tan bien pensada como la infraestructura que hay detrás. Si lo haces bien, el paso del transportista deja de ser una fuente de carritos abandonados y pasa a ser una razón menos para marcharse.

Preguntas frecuentes

¿Cuál es la diferencia entre un módulo de transportista y añadir un transportista en el back office?

Un transportista del back office es una fila estática en ps_carrier con una tabla de precios que has introducido tú; no sabe nada de la empresa de mensajería más allá de un nombre y una plantilla de URL de seguimiento. Un módulo de transportista instala software que crea y controla su transportista en código, llama después a la API de la mensajería para obtener tarifas en tiempo real, inserta un mapa de taquillas en el proceso de pago y genera etiquetas con el número de seguimiento escrito directamente en el pedido. Si tu mensajería ofrece un módulo oficial, casi siempre te conviene usarlo; si no, un transportista creado a mano es la alternativa.

¿Por qué mi proceso de pago muestra "no hay transportistas disponibles" después de instalar un módulo de transportista?

Casi siempre es una de cinco cosas: el transportista del módulo no está asignado a la zona del cliente; ningún rango de precios cubre el carrito (algunos módulos siguen necesitando una fila de rango de respaldo); las credenciales de la API son incorrectas o la API de la mensajería está caída y no hay precio de respaldo configurado; una restricción de grupo o multitienda está ocultando el transportista; o el producto no tiene peso, por lo que un transportista basado en peso o con tarifa en tiempo real no puede calcular el precio. Revísalas en ese orden: la asignación de zonas y un precio de respaldo ausente cubren la mayoría de los casos.

¿Qué controla realmente need_range en un transportista?

Decide si PrestaShop lee una tabla estática de rangos por peso/precio para calcular el transportista, o si pregunta al módulo. Con need_range = false en un transportista marcado con shipping_external e is_module, PrestaShop llama al getOrderShippingCostExternal() del módulo para obtener un presupuesto real y no depende en absoluto de una fila de rango. Con need_range = true, un rango que no cubre el carrito puede hacer que el transportista desaparezca; ese es uno de los sospechosos de "no hay transportistas disponibles" mencionados arriba.

¿De verdad necesito probar primero en staging?

Sí: los módulos de transportista escriben en ps_carrier, ps_carrier_zone y las tablas de rangos durante la instalación, y tocan la página más delicada de tu tienda. Un módulo que registra mal su transportista aparece como "no hay transportistas disponibles" en el proceso de pago, y no quieres descubrirlo con clientes reales. Clona la tienda, haz una copia de seguridad de la base de datos, instálalo allí y realiza un pedido de prueba real para cada zona antes de tocar producción. Una copia de seguridad limpia convierte una mala instalación en una reversión de cinco minutos.

¿PrestaShop 9 cambia cómo funcionan varios transportistas?

Puede hacerlo, detrás de una bandera. Históricamente, PrestaShop ha aplicado la regla de un pedido = un transportista. PrestaShop 9.1 introduce un modelo de envíos que permite que un pedido tenga varios envíos con distintos transportistas, disponible bajo una bandera de funcionalidad: activa "Improved shipment" en Parámetros avanzados → Nuevas funciones & experimentales para probarlo. Es experimental, así que pruébalo en staging antes de depender de ello; con la bandera desactivada, sigue aplicándose el comportamiento clásico de un único transportista por pedido que describe el resto de esta guía.