VibeFox Servientrega for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 5.0 o posterior, instalado y activo. El plugin no se activa sin él.
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 (usualmente 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 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 solo dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_servientrega a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Shipping > VibeFox Servientrega, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
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 de origen y, si la moneda de tu tienda no es COP, la tasa de conversión de moneda (consulta Configuración).
6. Opcionalmente, añade precios fijos por país y peso y un costo alternativo.
7. Añade VibeFox Servientrega a una zona de envío en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones y elige los países.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox Servientrega. Se aplican a todas las zonas de envío. Cuando añades el método a una zona, la ventana de la zona tiene un único campo:
Title (zone): el nombre que ven los clientes en esta zona. Déjalo vacío para usar el Method title global.
Cada vez que guardas los ajustes, se borran 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 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 de origen.
General
Enable/Disable: activa o desactiva el método en todas las zonas a la vez.
Method title: el nombre del método de envío que se muestra en el carrito y en la finalización de compra. Una zona puede cambiarlo. Predeterminado: Servientrega.
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.
Password: tu contraseña de Servientrega / SISCLINET, tal como la escribes. El plugin la cifra mediante el servicio web de Servientrega antes de iniciar sesión, igual que hace el cliente oficial de Servientrega.
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 volumétrico.
Currency conversion rate: Servientrega cotiza en COP. Si la moneda 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 plugin no obtiene tipos de cambio. Se aceptan tanto el punto como la coma como separador decimal.
Origen del envío (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 WooCommerce > Settings > General 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, un destino fuera de Colombia, un municipio desconocido, una tasa de conversión que falta, o un error de la API o falta de cobertura para la ruta)
Price per country: una tabla de países y precios en la moneda de tu tienda. Haz clic en + Add country para añadir una fila y en el icono × 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 Price para ese peso cuando su valor es mayor que 0. La fila * Default se aplica a todos los países sin fila propia.
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 se aplican por envío.
Condiciones
Minimum weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite.
Maximum weight (kg): oculta el método cuando el carrito pesa más. Predeterminado: 50. 0 significa sin límite.
Minimum order amount: muestra el método 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. Se aplica solo cuando el método tiene un precio: un precio de la tabla o el costo alternativo (entonces no se envía ninguna solicitud a Servientrega), o una tarifa en tiempo real. Déjalo vacío para no ofrecer nunca envío gratuito.
Excluded shipping classes: oculta el método cuando el carrito contiene un producto de alguna de estas clases de envío de WooCommerce.
Tax status: Taxable añade el impuesto de WooCommerce al costo del envío, None no lo añade. Las cotizaciones de Servientrega (ValorTotal) ya incluyen los cargos del transportista. Elige None si no quieres añadir impuestos encima.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece Servientrega para los países indicados abajo, incluso si el método no está añadido a ninguna zona de envío.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías. 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 el registro de WooCommerce: WooCommerce > Status > Logs, origen vfd_servientrega. Las credenciales, los tokens y las direcciones de los clientes no se registran. Desactiva el registro cuando termines.
Remove data on uninstall: cuando está activado, al eliminar el plugin se borran todos los ajustes de Servientrega, los métodos de zona y las cotizaciones en caché. Desactivar el plugin nunca borra nada.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, WooCommerce pide al plugin una tarifa. Primero el plugin comprueba las condiciones: país de entrega, peso del carrito, importe mínimo del pedido y clases de envío excluidas. Después busca un precio: la tarifa en tiempo real de Servientrega, luego la tabla de precios y después el costo alternativo. Si no hay precio, el método se oculta. Si se aplica el envío gratuito, el método se muestra con un precio de 0.
Para un destino en Colombia con credenciales configuradas, el plugin busca 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 hace coincidir el departamento y la ciudad con la tabla integrada de unos 1.130 municipios. Se ignoran las tildes y "D.C.". Un nombre de ciudad que existe en un solo departamento se encuentra aunque no se indique el departamento.
A continuación, el plugin envía a Servientrega un solo paquete 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 se consideran de 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 y el plugin lo convierte a la moneda de tu tienda.
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, 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.
Si no hay tarifa en tiempo real, el precio procede de la tabla de precios fijos y después del Fallback cost. Si ninguno se aplica, el método se oculta. El cliente nunca ve un error de la API. El motivo se escribe en el registro de depuración.
El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con WooCommerce High-Performance Order Storage (HPOS). Incluye traducciones al español (Colombia, España).
El plugin solo calcula tarifas. No genera guías, etiquetas ni stickers, no solicita recogidas, no rastrea ni cancela envíos, y no permite que los clientes elijan una oficina de Servientrega (Centro de Soluciones). Crea la guía en SISCLINET o en tu portal de Servientrega. No se cotiza el contraentrega (logística de recaudo). Las cotizaciones en tiempo real son solo para envíos nacionales dentro de Colombia. Ecuador, Perú, Panamá y los envíos internacionales usan los precios fijos.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox Servientrega. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Servientrega no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión lo siguen viendo, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Servientrega no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el método está añadido a la zona del país del cliente (o que Ignore shipping zones está activado y el país está permitido). Revisa los límites de peso, Minimum order amount y Excluded shipping classes. Sin tarifa en tiempo real, comprueba que el país o * Default tiene un precio, o que Fallback cost está configurado.
Las tarifas en tiempo real no aparecen: activa el Debug log, recarga la finalización de compra y abre WooCommerce > Status > Logs, origen vfd_servientrega. 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 es un municipio conocido, credenciales incorrectas o falta de cobertura para la ruta. Los precios fijos cubren estos casos si los has configurado.
El inicio de sesión falla: 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 plugin espera 10 minutos antes del siguiente intento. Guarda los ajustes para volver a intentarlo de inmediato.
La ciudad del cliente no se reconoce: el departamento y la ciudad se comparan con la tabla DANE integrada. Para escrituras poco habituales, el cliente puede escribir el código DANE de 8 dígitos como código postal. Los desarrolladores pueden asignarlo con el filtro vfd_svtg_dane_code.
Las tarifas parecen desactualizadas tras un cambio: guarda la página de ajustes. Esto borra las cotizaciones de Servientrega en caché y el token.
Para desarrolladores: los filtros vfd_svtg_quote_request y vfd_svtg_default_dimensions ajustan la solicitud de cotización y las dimensiones de los productos que no las tienen. vfd_svtg_api_base y vfd_svtg_soap_url cambian los puntos de conexión (endpoints), por ejemplo si Servientrega te da otro servidor.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes, los métodos de zona, las cotizaciones en caché y los tokens se eliminan solo si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus líneas de envío.
Servientrega es una marca comercial de su respectivo titular. Este plugin no está afiliado a Servientrega ni cuenta con su aprobación.