VibeFox Servientrega for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado con 3.0.5.0) o 4.0.2 y posteriores (probado con 4.1.0.3).
PHP: 8.0 o posterior.
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 (normalmente empieza por SER). Son tus credenciales de SISCLINET y los emite tu asesor comercial de Servientrega. Si solo usas precios fijos, no necesitas una cuenta de Servientrega.
Acceso al servidor (solo para tarifas en tiempo real): tu servidor debe poder acceder 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 solo dominio.
Instalación
La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_servientrega-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_servientrega.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.
OpenCart 3
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_servientrega-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, también puedes copiar el contenido de la carpeta upload del paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions, elige el tipo de extensión Shipping, busca VibeFox Servientrega y haz clic en Install (el botón verde +).
3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración.
4. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Edit, y haz clic en Activate (véase Clave de licencia).
5. 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 del origen y, si la moneda de tu tienda no es COP, la tasa de conversión de moneda.
6. Opcionalmente, añade precios fijos por país y peso y un costo de contingencia, activa Enable Servientrega y haz clic en Save.
OpenCart 4
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_servientrega.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.
2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.
3. Ve a Extensions > Extensions, elige el tipo de extensión Shipping, busca VibeFox Servientrega, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).
4. Introduce la clave de licencia y los ajustes como en los pasos 4 a 6 de OpenCart 3. La página de configuración y sus campos son los mismos en ambas versiones.
Tras la instalación, el método queda desactivado hasta que actives Enable Servientrega y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Servientrega que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. Las secciones aparecen a la izquierda. Se aplican a todas las zonas geográficas. Un botón Save en la parte inferior guarda toda la página sin recargarla. Cada guardado borra las cotizaciones de Servientrega en caché y el token de inicio de sesión. Solo los administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
Si las tarifas en tiempo real no pueden funcionar con los ajustes guardados, un aviso encima de los ajustes te indica el motivo: falta el usuario, la contraseña o el código de facturación, falta la tasa de conversión o falta el código DANE del origen. También aparece un aviso si la tienda no tiene una clase de peso en kg o una clase de longitud en cm y su unidad predeterminada no es conocida por la extensión; en ese caso, los pesos se leen como kg y las dimensiones como cm. Al guardar, un valor que no es un número, un número negativo, una tasa de conversión de 0, un peso mínimo mayor que el máximo, un precio incorrecto en la tabla, un título de método vacío, de más de 64 caracteres o con < > ; = # { }, o un orden de clasificación que no es un número entero se rechaza con un error, y no se guarda nada.
General
Enable Servientrega: muestra u oculta Servientrega en la finalización de compra. Por defecto: desactivado.
Method title: el nombre del método de envío que el cliente ve en el carrito y en la finalización de compra. Por defecto: Servientrega. Obligatorio, de 64 caracteres como máximo.
Sort order: la posición de Servientrega entre los métodos de envío en la finalización de compra. Un número entero.
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. Borrarlo también elimina la contraseña guardada.
Password: tu contraseña de Servientrega / SISCLINET, tal como la escribes. La extensión la cifra mediante el servicio web de Servientrega antes del inicio de sesión. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla.
Billing code: el código de facturación de tu cuenta de Servientrega, que aparece en SISCLINET. Normalmente empieza por SER.
Los tres campos son necesarios para las tarifas en tiempo real. Las tarifas en tiempo real solo se solicitan 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 peso 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 manera. Si la moneda de tu tienda es COP, el campo indica que no hace falta conversión: déjalo vacío. 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. La extensión no obtiene tipos de cambio. Se aceptan tanto el punto como la coma como separador decimal.
Ship from (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. La dirección de la tienda en OpenCart es texto libre, por lo que el origen nunca se toma de ella: sin este campo no hay tarifas en tiempo real.
Fixed prices (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 botón de eliminar para borrar una. Price se aplica a cualquier peso. Las columnas de peso XS (hasta 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) y XL (más de 5 kg) lo reemplazan para ese peso cuando son mayores que 0. La fila * Default se aplica a todos los países sin fila propia. Una fila nueva empieza como * Default. Una fila sin ningún precio no se guarda.
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 método 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.
Conditions
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (predeterminado).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Por defecto: 50. 0 significa sin límite.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el envío es gratuito cuando ese subtotal alcanza este importe, y no se envía ninguna solicitud a Servientrega. Se aplica a todos los destinos donde se ofrece el método, también a países sin fila en la tabla de precios. Déjalo vacío para no ofrecer nunca envío gratuito.
Tax class: la clase de impuesto del costo de envío, o No tax (predeterminado). Las cotizaciones de Servientrega (ValorTotal) ya incluyen los cargos de la transportista. Elige No tax si no quieres añadir impuestos encima.
Geo zone: ofrece Servientrega solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se comprueba cuando Ignore shipping zones está activado.
Availability without geo zone
Normalmente el método se ofrece en la zona geográfica seleccionada en Conditions, o en todas partes.
Ignore shipping zones: ofrece Servientrega para los países de abajo sea cual sea la zona geográfica.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activados de tu tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Advanced
Debug log: escribe los cálculos de tarifas y los errores de la API en storage/logs/vfd_svtg_debug.log.php. El archivo no puede leerse desde la web. Las credenciales, los tokens y las direcciones de los clientes no se registran. Cuando el registro está desactivado, no se escribe nada, tampoco los errores de la API. Cuando el archivo llega a 5 MB, se mueve a vfd_svtg_debug.old.log.php y se inicia un registro nuevo. Desactiva el registro 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 la extensión se eliminan todos los ajustes de Servientrega y el registro. Si está desactivado (predeterminado), se conservan para una reinstalación. Las cotizaciones en caché siempre se eliminan.
Import / Export
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La contraseña no se exporta.
Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. La contraseña guardada se conserva mientras el usuario esté definido.
Cómo funciona en la finalización de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de Servientrega. Si hay una Geo zone definida y la dirección está fuera de ella, Servientrega no se ofrece (salvo que Ignore shipping zones esté activado). Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni se incluyen en el importe del pedido. El importe del pedido es el precio de estos productos después del descuento del cupón y antes de impuestos. Los certificados de regalo y los puntos de recompensa no se tienen en cuenta. La extensión primero comprueba 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: la tarifa en tiempo real de Servientrega, luego la tabla de precios y, por último, el costo de contingencia. Si no hay precio, el método se oculta para ese carrito.
Para un destino en Colombia con credenciales configuradas, la extensión encuentra el código DANE del municipio del cliente. Usa un código DANE escrito en el código postal o en el campo de ciudad, o hace coincidir el departamento y la ciudad con la tabla integrada de unos 1.130 municipios. El departamento es la Region / State de la dirección: OpenCart ya tiene los 33 departamentos colombianos. Se ignoran las tildes y "D.C.". Una ciudad que existe en un solo departamento se encuentra incluso sin el departamento.
Después, la extensión envía a Servientrega una pieza por pedido: el peso total convertido de la clase de peso del producto 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 importe del pedido convertido a COP, con un mínimo de 6.000 COP. Servientrega devuelve el total en COP. La extensión lo convierte a la moneda predeterminada de tu tienda y lo redondea a sus decimales. El cliente lo ve en su moneda con el impuesto de la Tax class seleccionada.
El token de inicio de sesión se mantiene 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, así que el mismo carrito no genera 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.
La extensión solo calcula tarifas. No crea guías, etiquetas ni stickers, no solicita recogidas, no rastrea ni cancela envíos, y no permite que el cliente elija una oficina de Servientrega (Centro de Soluciones). Crea la guía en SISCLINET o en tu portal de Servientrega. El pago contra entrega (logística de recaudo) no se cotiza. Las cotizaciones en tiempo real son solo para envíos nacionales dentro de Colombia. No añade nada a los pedidos: el pedido muestra el nombre del método y el costo de envío como cualquier otro método de envío de OpenCart.
En OpenCart 4 el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige Servientrega en la ventana Shipping method options, donde se muestra el título del método con el precio. El método funciona igual que en OpenCart 3.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Servientrega es el primer bloque de Extensions > Extensions > Shipping > VibeFox Servientrega > Edit, por 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 quitar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-servientrega y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso de modificación de la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (incluidos 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 y una fecha. Después de cambiar la dirección de la tienda o de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío de Servientrega no se muestra a los clientes en la finalización de compra y no se solicita ni calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el panel en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del panel, así que sin una clave activa el método se oculta a todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez por semana. No hace falta ninguna tarea cron. Desinstalar la extensión 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. Revisa Geo zone, 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 * Default tiene un precio, o que Fallback cost está definido. Comprueba que los productos tienen Requires Shipping en Yes.
Las tarifas en tiempo real no aparecen: activa el Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. 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 se han introducido o no son un municipio conocido, credenciales incorrectas, sin cobertura para la ruta, o el servidor no puede acceder a web.servientrega.com por los puertos 8058 y 8081. Los precios fijos cubren estos casos si los configuras.
Falla el inicio de sesión: comprueba el usuario, la contraseña y el código de facturación con tu asesor comercial de Servientrega. Tras un inicio de sesión fallido, la extensión espera 10 minutos antes del siguiente intento. Guarda los ajustes para volver a intentarlo de inmediato.
La ciudad del cliente no se reconoce: el cliente debe elegir el departamento en el campo Region / State. Para escrituras poco habituales, el cliente puede escribir el código DANE de 8 dígitos como código postal.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las cotizaciones de Servientrega en caché y el token.
La página dice "Warning: You do not have permission to modify VibeFox Servientrega!": tu grupo de usuarios de administración puede solo ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_servientrega (OpenCart 3) o extension/vfd_servientrega/shipping/vfd_servientrega (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: los eventos de OpenCart vfd_servientrega/dane_code y vfd_servientrega/quote_request permiten que otra extensión cambie el código DANE de destino y la solicitud de cotización.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Servientrega. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Servientrega, Sort order, Tax class y Geo zone. Las cotizaciones en caché, los tokens y la contraseña cifrada siempre se eliminan. Si Remove data on uninstall está activado, también se borran el resto de ajustes y el registro. Si está desactivado, se conservan y se usan de nuevo al volver a instalar la extensión. Los pedidos existentes conservan su método de envío y su costo.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox Servientrega en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Servientrega es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Servientrega.