VibeFox Servientrega for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Cuenta de Servientrega (solo para tarifas en tiempo real): las tarifas en tiempo real usan el Cotizador Corporativo de Servientrega (API de cotización corporativa). Necesitas una cuenta corporativa (de crédito) de Servientrega con acceso a él. Necesitas tres datos: el usuario, la contraseña y el código de facturación (suele empezar por SER). Son tus credenciales de SISCLINET y te las proporciona tu asesor comercial de Servientrega. Si solo usas precios fijos, no necesitas una cuenta de Servientrega.

Acceso del servidor (solo para tarifas en tiempo real): tu servidor debe poder conectarse a web.servientrega.com por HTTP en el puerto 8058 (API de cotización) y en el puerto 8081 (servicio web de cifrado de contraseñas).

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca VibeFox Servientrega más tarde en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).

4. Para las tarifas en tiempo real, introduce el usuario, la contraseña y el código de facturación, elige el producto de Servientrega, introduce el código DANE de origen y, si la moneda de tu tienda no es COP, la tasa de conversión de moneda. Haz clic en Add Colombian departments si tu tienda todavía no tiene departamentos (véase Configuración).

5. Opcionalmente, añade precios fijos por país y peso y un costo alternativo, y luego haz clic en Save.

Al instalar, el módulo crea el transportista Servientrega con el texto del plazo de entrega Servientrega courier delivery. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre viene del módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Servientrega > Configure. Se aplican a todas las zonas. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado borra las cotizaciones de Servientrega en caché y el token de inicio de sesión.

Si las tarifas en tiempo real no pueden funcionar con los ajustes guardados, un aviso encima del formulario te indica el motivo: falta el usuario, la contraseña o el código de facturación, falta la tasa de conversión de moneda o falta el código DANE de origen. También aparece un aviso si la unidad de peso o de dimensiones de tu tienda (International > Localization, Local units) no es conocida por el módulo; en ese caso los pesos se leen como kg y las dimensiones como cm. Al guardar, se rechaza con un error cualquier valor que no sea un número, un número negativo, una tasa de conversión de 0, un peso mínimo superior al peso máximo, un precio incorrecto en la tabla o un título de método de más de 64 caracteres, y no se guarda nada.

General

Enable Servientrega: activa o desactiva el transportista en todas las zonas a la vez. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Method title: el nombre del transportista que ve el cliente en el carrito y en la finalización de compra. Predeterminado: Servientrega. Obligatorio, máximo 64 caracteres.

API de Servientrega (tarifas en tiempo real para Colombia) (opcional; sin credenciales solo se usan los precios fijos)

User (login): tu usuario de Servientrega / SISCLINET. Al borrarlo también se elimina la contraseña guardada.

Password: tu contraseña de Servientrega / SISCLINET, tal como la escribes. El módulo la cifra con el servicio web de Servientrega antes de iniciar sesión. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.

Billing code: el código de facturación de tu cuenta de Servientrega, que aparece en SISCLINET. Suele empezar por SER.

Los tres campos son necesarios para las tarifas en tiempo real. Las tarifas en tiempo real se piden solo para destinos en Colombia. Los demás países usan los precios fijos.

Servientrega product: el servicio de tu acuerdo con Servientrega que se cotiza.

El peso facturable es el mayor entre el peso real y el volumétrico.

Currency conversion rate: Servientrega cotiza en COP. Si la moneda predeterminada de tu tienda no es COP, introduce el valor de 1 COP en la moneda de tu tienda, por ejemplo 0.00023. El valor declarado del paquete se convierte a COP de la misma forma. Déjalo vacío si la moneda de tu tienda es COP. Si tu tienda usa otra moneda y este campo está vacío, no se usan las tarifas en tiempo real y se aplican los precios fijos. El módulo no descarga tipos de cambio. Se aceptan tanto el punto como la coma como separador decimal.

Colombian departments: el departamento ayuda a distinguir municipios con el mismo nombre. PrestaShop no tiene departamentos colombianos de forma predeterminada; sin ellos solo se reconocen los nombres de ciudad que son únicos en Colombia. Haz clic en Add Colombian departments para añadir los 33 departamentos como estados de Colombia (códigos ISO ANT, DC…), activa Contains states para Colombia y añade el campo de departamento al formulario de direcciones colombianas. Los departamentos que ya existen no se añaden dos veces. Cuando todo está listo, el campo muestra cuántos departamentos tienen las direcciones colombianas.

Envío desde (se usa para las tarifas en tiempo real)

Origin city (DANE code): el código DANE de 8 dígitos del municipio desde el que envías, por ejemplo 11001000 Bogotá, 05001000 Medellín, 76001000 Cali u 08001000 Barranquilla. También se acepta un código de municipio de 5 dígitos. Si está vacío y la dirección de tu tienda en Shop Parameters > Contact > Stores está en Colombia, se usa el municipio de la dirección de la tienda.

Precios fijos (se usan cuando no hay tarifa en tiempo real: sin credenciales, destino fuera de Colombia, municipio desconocido, falta la tasa de conversión, error de la API o sin cobertura para la ruta)

Price per country: una tabla de países y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add country para añadir una fila y en el icono de papelera para eliminar una. Price se aplica a cualquier peso. Las columnas de peso XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg y XL >5 kg sustituyen a ese precio para ese peso cuando son superiores a 0. La fila * Default se aplica a todos los países sin fila propia. No se guarda una fila sin ningún precio.

Fallback cost: se usa cuando no hay tarifa en tiempo real y ninguna fila de la tabla coincide. Déjalo vacío para ocultar el transportista en ese caso.

Fixed price applies: cómo se cobran los precios fijos.

Las tarifas en tiempo real de Servientrega siempre son por envío.

Condiciones

Minimum weight: oculta el transportista cuando el carrito pesa menos, en kg. 0 significa sin límite.

Maximum weight: oculta el transportista cuando el carrito pesa más, en kg. Predeterminado: 50. 0 significa sin límite.

Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.

Free shipping from: el envío es gratuito cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcanza este importe, y no se envía ninguna solicitud a Servientrega. Se aplica a todos los destinos donde se ofrece el transportista, también a los países sin fila en la tabla de precios. Déjalo vacío para no ofrecer nunca envío gratuito.

Tax: la regla de impuesto del transportista, o No tax. Las cotizaciones de Servientrega (ValorTotal) ya incluyen los cargos del transportista. Elige No tax si no quieres añadir impuestos encima.

Disponibilidad sin zonas de envío

Normalmente el transportista se ofrece en las zonas asignadas en Shipping > Carriers.

Ignore shipping zones: ofrece Servientrega para los países indicados abajo, aunque el transportista no esté asignado a su zona. Entonces el transportista se asigna a todas las zonas, también a las zonas que crees más adelante. Al desactivar la opción, el transportista recupera sus zonas anteriores.

Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos de tu tienda. Este campo solo se usa cuando Ignore shipping zones está activado.

Avanzado

Debug log: escribe los cálculos de tarifas y los errores de la API en logs/vfd_svtg_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. No se registran credenciales, tokens ni direcciones de clientes. Cuando el registro está desactivado, no se escribe nada, tampoco los errores de la API. Desactívalo cuando termines.

Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar el módulo se borran todos los ajustes de Servientrega, el transportista, las cotizaciones en caché y los registros. Los pedidos anteriores conservan su transportista. Si está desactivado, todo se conserva para una reinstalación.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de Servientrega. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el importe del pedido. El módulo comprueba primero las condiciones: el país de entrega (con Ignore shipping zones), el peso del carrito y el importe mínimo del pedido. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Servientrega. Después busca un precio: primero la tarifa en tiempo real de Servientrega, luego la tabla de precios y después el costo alternativo. Si no hay precio, el transportista se oculta para ese carrito.

Para un destino en Colombia con credenciales configuradas, el módulo encuentra el código DANE del municipio del cliente. Usa un código DANE escrito como código postal o en el campo de ciudad, o compara el departamento y la ciudad con la tabla integrada de unos 1.130 municipios. Se ignoran los acentos y «D.C.». Un nombre de ciudad que existe en un solo departamento se encuentra incluso sin el departamento.

Después el módulo envía a Servientrega una pieza por pedido: el peso total convertido de la unidad de tu tienda a kg, y una caja con el largo y el ancho del artículo más grande y el volumen total de todos los artículos, convertido a cm. Los productos sin dimensiones cuentan como 10 × 10 × 10 cm. El valor declarado es el subtotal del carrito convertido a COP, con un mínimo de 6.000 COP. Servientrega devuelve el total en COP. El módulo lo convierte a la moneda predeterminada de tu tienda, y el cliente lo ve en la moneda del carrito.

El token de inicio de sesión se conserva hasta que caduca, como máximo 4 días. Un token rechazado se renueva automáticamente una vez. Cada cotización se guarda en caché durante 1 hora por ruta y paquete, para que el mismo carrito no genere una nueva solicitud. Una solicitud fallida (cifrado, inicio de sesión o cotización) se guarda en caché durante 10 minutos, para que la finalización de compra no espere a Servientrega en cada actualización. El tiempo de espera es de 10 segundos por solicitud.

El cliente nunca ve un error de la API. El motivo se escribe en el registro de depuración cuando está activado.

Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.

El módulo solo calcula tarifas. No genera guías, etiquetas ni stickers, no solicita recogidas, no rastrea ni cancela envíos, ni permite que los clientes elijan una oficina de Servientrega (Centro de Soluciones). Crea la guía en SISCLINET o en tu portal de Servientrega. El contraentrega (logística de recaudo) no se cotiza. Las cotizaciones en tiempo real son solo para envíos nacionales dentro de Colombia. Los demás países usan los precios fijos.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox Servientrega es el primer bloque de Modules > Module Manager > VibeFox Servientrega > Configure, encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-servientrega y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, el transportista de Servientrega no se muestra a los clientes en la finalización de compra y no se solicita ni calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Servientrega no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Servientrega esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y el Minimum order amount. Sin tarifa en tiempo real, comprueba que el país o la fila * Default tenga un precio, o que Fallback cost esté configurado. Los productos también pueden limitarse a ciertos transportistas en la página del producto.

Las tarifas en tiempo real no aparecen: activa el Debug log, recarga la finalización de compra y mira el campo Log en la página del módulo. Motivos habituales: falta la tasa de conversión (la moneda de la tienda no es COP), no hay código DANE de origen, el departamento o la ciudad del cliente aún no están introducidos o no son un municipio conocido, credenciales incorrectas o falta cobertura para la ruta. Los precios fijos cubren estos casos si los configuras.

Error de inicio de sesión: comprueba el usuario, la contraseña y el código de facturación con tu asesor comercial de Servientrega. Después de un inicio de sesión fallido, el módulo espera 10 minutos antes del siguiente intento. Guarda los ajustes para volver a intentarlo de inmediato.

La ciudad del cliente no se reconoce: haz clic en Add Colombian departments para que los clientes puedan elegir su departamento. Para grafías poco habituales, el cliente puede escribir el código DANE de 8 dígitos como código postal.

Las tarifas parecen desactualizadas después de un cambio: haz clic en Save en la página del módulo. Esto borra las cotizaciones de Servientrega en caché y el token.

La página indica que no se encontró el transportista de Servientrega: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.

Para desarrolladores: los hooks actionVfdSvtgDaneCode y actionVfdSvtgQuoteRequest te permiten cambiar el código DANE del destino y la solicitud de cotización.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Servientrega y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las cotizaciones en caché, los tokens y la contraseña cifrada siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y todos los ajustes se conservan. Al volver a instalar el módulo, o con Reset, el transportista recupera el estado que tenía antes.

Servientrega es una marca comercial de su respectivo propietario. Este módulo no está afiliado ni respaldado por Servientrega.