VibeFox Chilexpress for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Claves de API de Chilexpress (solo para tarifas en tiempo real): crea una cuenta en el portal de desarrolladores de Chilexpress (developers.wschilexpress.com) y suscríbete a dos productos: Rating (Cotizador) y Coverage (Coberturas / Georreferencia). Cada producto tiene su propia clave de suscripción. Las claves de prueba funcionan solo con el entorno de prueba; las claves de producción se emiten a clientes comerciales de Chilexpress con un contrato. También necesitas el código de comuna de Chilexpress desde donde envías, por ejemplo STGO. Si solo usas precios fijos, no necesitas claves de API.
Regiones de Chile (solo para tarifas en tiempo real): las tarifas en tiempo real necesitan la región (zona) de la dirección de entrega. OpenCart 3.0.5.0 tiene 15 de las 16 regiones de Chile; la extensión puede añadir las que faltan (ver Chilean regions más abajo). El país Chile debe existir en la tienda.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un único archivo zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_chilexpress-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_chilexpress.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_chilexpress-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Chilexpress 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 ajustes.
4. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Edit y haz clic en Activate (ver Clave de licencia).
5. Rellena la tabla Country prices. Para las tarifas en tiempo real, introduce ambas claves de suscripción, el código de comuna de origen y, si la moneda de la tienda no es CLP, el tipo de cambio a CLP. Haz clic en Add Chilean regions si la página muestra regiones que faltan y, después, elige la fuente de tarifas (ver Configuración). Activa Enable/Disable 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_chilexpress.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 y elige el tipo de extensión Shipping. Busca VibeFox Chilexpress, 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 y 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable/Disable y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Chilexpress que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. Tras guardar verás Settings saved. Cached Chilexpress rates and comuna lists were cleared. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes, vaciar el registro o añadir regiones.
La página muestra los problemas en la parte superior: se seleccionan tarifas de API pero la clave de la API Rating está vacía; la clave de la API Coverage está vacía; el código de comuna de origen está vacío o no es válido; la moneda de la tienda no es CLP y no hay tipo de cambio a CLP; Country prices no tiene fila para Chile ni para la predeterminada; Chile no tiene zonas en la tienda; la unidad de peso o de longitud de la tienda no la reconoce la extensión (entonces los pesos se leen como kg y las dimensiones como cm; usa kg, g, lb u oz y cm, mm, m o in en System > Localisation). Los números se pueden escribir con punto o con coma. No se guarda nada y la página muestra los errores si Name está vacío, contiene alguno de los caracteres < > ; = # { } o tiene más de 64 caracteres, si un número no es válido o es negativo, si CLP exchange rate es 0, si Min weight (kg) es mayor que Max weight (kg), si Origin county code no es un código de comuna, o si Sort order no es un número entero.
General
Un único método de entrega "Chilexpress" para cada zona geográfica, o para la zona geográfica seleccionada en Disponibilidad.
Enable/Disable: muestra u oculta Chilexpress en la finalización de compra. Por defecto: desactivado.
Name: el nombre del método de envío que ve el cliente en la finalización de compra. Por defecto: Chilexpress. Obligatorio, hasta 64 caracteres.
Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Las tarifas de la API de Chilexpress se usan exactamente como se cotizan. Elige No tax si la cotización ya incluye el IVA y tu tienda añadiría impuesto encima.
Sort order: la posición de Chilexpress entre los métodos de entrega en la finalización de compra. Un número entero.
Tarifas
Rate source: de dónde viene el precio.
Las tarifas en tiempo real solo están disponibles para destinos en Chile. Los demás países siempre usan los precios fijos.
Country prices: una lista de países de destino con una columna Price y precios opcionales por tamaño de paquete, en la moneda predeterminada de tu tienda y sin impuestos. El tamaño viene del peso del carrito: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg, XL por encima de 5 kg. Un tamaño dejado en 0 usa Price. Haz clic en Add country para añadir una fila. La fila * Default (other countries) se aplica a los países sin fila propia. Un país sin fila (y sin la fila predeterminada) no tiene precio fijo, así que el método se oculta allí. Una fila guardada cuyo precio y precios por tamaño son todos 0 da envío gratis. Una tabla vacía muestra una fila para Chile con 0, así que introduce precios reales antes de guardar la página. Un país repetido o un precio no válido se corrige (el duplicado se ignora y el precio pasa a 0), y un aviso enumera las correcciones.
Calculation type: Per order (por defecto) cobra el precio fijo una sola vez. Per item (fixed price x number of items) lo multiplica por el número de artículos del carrito. Una tarifa de la API de Chilexpress siempre se cotiza para el paquete completo.
API de Chilexpress (tarifas en tiempo real)
La sección empieza con enlaces al portal de desarrolladores y a las páginas de suscripción de Rating y Coverage.
Test environment: usa el entorno de pruebas de Chilexpress (qaservices.wschilexpress.com). Úsalo con claves de prueba y desactívalo en una tienda real. Por defecto: desactivado.
Rating API key: la clave de suscripción del producto Rating (Cotizador).
Coverage API key: la clave de suscripción del producto Coverage (Coberturas / Georreferencia). Se usa para encontrar el código de comuna de Chilexpress de la comuna del cliente (el campo City de la dirección, junto con su región).
Después de guardar, el campo de la clave queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla. La clave se guarda tal como la escribes; solo se quitan los espacios alrededor.
Remove the saved Rating API key y Remove the saved Coverage API key: activa una de ellas y haz clic en Save para borrar esa clave.
Origin county code: el código de comuna de Chilexpress desde donde envías, de 2 a 5 letras, por ejemplo STGO (Santiago Centro), PROV (Providencia) o VALP (Valparaíso). Está vacío tras la instalación. Un valor que no es un código de comuna se rechaza con un error.
Service: el servicio de Chilexpress usado para la tarifa. Si no se ofrece para el destino, se usa el servicio más barato ofrecido.
CLP exchange rate: Chilexpress cotiza en pesos chilenos. Solo hace falta si la moneda predeterminada de tu tienda no es CLP: el precio de 1 CLP en esa moneda, por ejemplo 0.001. Sin él no se usan las tarifas de la API. Si la moneda de la tienda es CLP, déjalo vacío. El valor debe ser mayor que 0.
Chilean regions: las comunas de Chile se buscan por región, así que las tarifas en tiempo real necesitan la región (zona) de la dirección. El campo muestra cuántas zonas tiene Chile y qué regiones faltan, con el botón Add Chilean regions. Solo añade las regiones que faltan como zonas de Chile; las zonas existentes no se cambian y una región no se añade dos veces. Cuando las 16 regiones están, el campo dice All 16 Chilean regions are zones of Chile. Si Chile no es un país de la tienda, el campo lo indica: añádelo en System > Localisation > Countries.
Disponibilidad
Min weight (kg): el peso mínimo del carrito para que aparezca el método. 0 significa sin límite (por defecto).
Max weight (kg): el método se oculta por encima de este peso del carrito. Por defecto: 25. 0 significa sin límite; un campo vacío significa 25 kg.
Minimum subtotal: muestra el método solo cuando el subtotal del carrito (productos que necesitan envío, después de cupones, sin impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Geo zone: ofrece el método solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se usa mientras Ignore shipping zones esté activado.
Ignore shipping zones: ofrece el método para los países de abajo sin comprobar la zona geográfica.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Este campo solo se usa cuando Ignore shipping zones está activado.
Envío gratis
Free shipping: activa el umbral de envío gratis.
Free shipping from: el subtotal del carrito (productos que necesitan envío, después de cupones, sin impuestos) a partir del cual el envío es gratis. Solo se usa cuando Free shipping está activado. En ese caso no se hace ninguna petición a la API.
Avanzado
Debug log: escribe las peticiones a la API y los cálculos de tarifas en storage/logs/vfd_chx_debug.log.php. El archivo no se puede leer desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. Las claves de API y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_chx_debug.old.log.php y se empieza un registro nuevo.
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 borran todos sus ajustes, las tarifas en caché y el registro. Si está desactivado (por defecto), todo se conserva para una reinstalación. Los pedidos y los servicios de Chilexpress guardados con ellos siempre se conservan.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. Las claves de API no se exportan.
Import: pega un JSON exportado antes y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. Las claves de API guardadas se mantienen.
Cómo funciona en la finalización de compra
Cuando OpenCart muestra los métodos de entrega, pide a la extensión el precio de Chilexpress. Si hay una Geo zone, Ignore shipping zones está desactivado y la dirección está fuera de la zona, Chilexpress no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso y no se incluyen en el subtotal. Los pesos se convierten a kilogramos y las dimensiones a centímetros según las clases de peso y de longitud de los productos. El subtotal es el precio de los productos que necesitan envío, después del descuento del cupón y sin impuestos, en la moneda predeterminada de tu tienda. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. La extensión comprueba primero las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna petición a Chilexpress.
Para una dirección en Chile y una fuente de tarifas de API, la extensión toma la región (zona) de la dirección y la comuna del campo City, y busca el código de comuna de Chilexpress en la lista de comunas de esa región (API Coverage). Se ignoran las tildes, los espacios y las variantes ortográficas, así que Ñuñoa y Nunoa coinciden, y Santiago coincide con Santiago Centro. También se acepta un código de comuna escrito en el campo City. Después, la extensión envía a la API Rating los códigos de comuna de origen y de destino, el peso del carrito (al menos 0,1 kg), las dimensiones del paquete (largo y ancho del producto más grande, con las alturas apiladas) y el subtotal del carrito en CLP como valor declarado. Chilexpress devuelve sus servicios; la extensión usa el elegido o el más barato, y convierte el importe en pesos a la moneda predeterminada de tu tienda. El precio se redondea a los decimales de esa moneda y después se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada.
Las tarifas se guardan en caché durante 1 hora. Las listas de comunas se guardan en caché hasta 7 días, pero no más que lo que OpenCart mantiene en su caché (1 hora por defecto). Una petición fallida se recuerda durante 5 minutos, para que una API lenta o no disponible no ralentice cada actualización de la finalización de compra. El tiempo de espera de la API es de 10 segundos. Si Chilexpress devuelve un error, ningún servicio con precio, o la comuna o la región son desconocidas, el cliente no ve ningún error. El método se oculta en el modo solo API, o se usa el precio fijo. El motivo se escribe en el registro de depuración.
La extensión solo calcula tarifas. No crea envíos ni órdenes de transporte (OT), no imprime etiquetas, no reserva recogidas ni hace seguimiento de paquetes; reserva el envío en tu cuenta de Chilexpress. Los clientes no pueden elegir una oficina de Chilexpress, y no hay selector de comuna: el cliente escribe la comuna en el campo City estándar. Los envíos internacionales usan los precios fijos.
En OpenCart 4 el cliente hace clic en Choose en el bloque de método de envío de la página de finalización de compra y selecciona Chilexpress en la ventana Shipping method options, por ejemplo Chilexpress - $5.49. El método funciona igual que en OpenCart 3.
Pedidos
Cuando se realiza un pedido con Chilexpress, la extensión guarda cómo se calculó su precio. En Sales > Orders, la página del pedido muestra un panel Chilexpress con Chilexpress service (en una tarifa en tiempo real, el servicio que cotizó Chilexpress, por ejemplo Express; si no, un guion) y Price: Live rate (Chilexpress Rating API), Fixed price o Free shipping. El panel también se muestra mientras el método está desactivado. En OpenCart 4 el panel Chilexpress se muestra encima de History, y cuando un pedido se vuelve a confirmar en la finalización de compra o se cambia a otro método de envío, el panel sigue el cambio.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Chilexpress es el primer bloque de Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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 aparecen la línea Product: opencart-shipping-chilexpress y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify de la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un 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. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Chilexpress no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el admin 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 admin, así que sin una clave activa el método se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del admin. 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 necesitan una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del admin: 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 ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Chilexpress no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso y Minimum subtotal. Con precios fijos, comprueba que el país o * Default (other countries) tenga una fila. Comprueba que los productos tengan Requires Shipping en Yes.
El envío en Chile es gratis cuando no debería serlo: la fila de Country prices para Chile (o la fila predeterminada) tiene 0 en Price y en las columnas de tamaño. Introduce los precios y haz clic en Save.
No se muestra la tarifa en tiempo real, se usa el precio fijo: primero revisa los avisos de la parte superior de la página de la extensión. Si no hay nada, activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Causas habituales: la dirección no tiene región o a Chile le faltan regiones (usa Add Chilean regions), una comuna que Chilexpress no reconoce (revisa el campo City y la región), una clave de otro producto o entorno, o un destino sin cobertura de Chilexpress.
HTTP 401 o 403 en el registro: la clave de suscripción es incorrecta, está inactiva o es de otro producto o entorno. Las claves de prueba funcionan solo con Test environment activado.
Las tarifas de API no se usan en una tienda con otra moneda: introduce el CLP exchange rate.
¿Las tarifas de la API llevan IVA o no? Se usan exactamente como las cotiza Chilexpress. Si tu tienda añade impuesto al envío y la cotización ya incluye IVA, pon Tax class en No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas y listas de comunas en caché.
La página dice "Warning: You do not have permission to modify VibeFox Chilexpress!": tu grupo de usuarios puede solo ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_chilexpress (OpenCart 3) o extension/vfd_chilexpress/shipping/vfd_chilexpress (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección base de la API de Chilexpress se puede cambiar con el ajuste vfd_chx_api_base_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalar
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Chilexpress. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable/Disable, Sort order, Tax class y Geo zone. Las tarifas y listas de comunas en caché siempre se eliminan. Si Remove data on uninstall está activado, los demás ajustes y el registro de depuración también se borran. Si está desactivado, se conservan y se usan de nuevo al volver a instalar la extensión. Los servicios de Chilexpress guardados con los pedidos nunca se borran, y los pedidos existentes conservan su método y coste de envío. Las regiones de Chile añadidas con Add Chilean regions se quedan en la tienda.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox Chilexpress en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Chilexpress es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Chilexpress.