VibeFox Correos CityPaq for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 o posterior (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Envío a España: las taquillas CityPaq solo existen en España, por lo que el método solo se ofrece para direcciones de entrega en España.
Credenciales de la API de Correos (solo para la lista de taquillas en tiempo real): la lista de CityPaq de Correos lee las taquillas activas de la API "terminals" de Correos. En el portal para desarrolladores de Correos, abre la API "terminals" y usa Request access para tu aplicación. Correos aprueba las solicitudes de sus clientes empresariales y envía un client ID y un client secret. También aparecen en My applications en el portal. Si los clientes introducen la taquilla ellos mismos o eligen de tu propia lista, no necesitas credenciales de la API.
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 para OpenCart 3 vfd_correos_citypaq-oc3-(version).ocmod.zip y el paquete para OpenCart 4 vfd_correos_citypaq.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_correos_citypaq-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 de este paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions, elige el tipo de extensión Shipping. Busca VibeFox Correos CityPaq 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. Pega 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 (consulta Clave de licencia).
5. Rellena la tabla de precios, elige cómo selecciona el cliente la taquilla (consulta 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_correos_citypaq.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 Correos CityPaq, haz clic en Install (el botón verde +) y luego 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 iguales 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 que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit. Las secciones aparecen a la izquierda. Un único botón Save en la parte inferior guarda toda la página sin recargarla. Los precios e importes admiten coma decimal o punto decimal. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
En la parte superior de la página aparecen advertencias cuando la tabla de precios no tiene fila para España ni fila predeterminada, cuando la selección de taquilla elegida no puede funcionar (no hay taquillas en tu lista, no hay credenciales de la API), cuál fue el último error de la API de Correos, y cuando la tienda no tiene una clase de peso con la unidad kg (los pesos de los productos se convierten entonces según el nombre de la unidad: kg, g, lb u oz; las unidades desconocidas se leen como kg). Revisa System > Localisation > Weight Classes. Si el nombre está vacío, no es válido o tiene más de 64 caracteres, si un peso o un importe no es un número válido igual o mayor que 0, si Min weight (kg) es mayor que Max weight (kg), o si Sort order no es un número entero, la página muestra un error y no se guarda nada. Los precios no válidos de la tabla de precios, las filas duplicadas y las líneas no válidas o duplicadas en My lockers se notifican como advertencias, y el resto se guarda.
General
Las taquillas CityPaq solo existen en España, así que el método nunca se ofrece para otros países.
Enable/Disable: activa o desactiva el envío con CityPaq de Correos. Por defecto: desactivado.
Name: el nombre del método de envío que ve el cliente en la finalización de compra. Por defecto: Correos CityPaq. Obligatorio, máximo 64 caracteres, sin < > ; = # { }.
Tax class: OpenCart añade el impuesto de esta clase sobre los precios de la tabla. No tax significa que los precios son finales.
Sort order: la posición del método en la lista de métodos de envío. Un número entero.
Precios (el título de la sección muestra la moneda predeterminada de tu tienda)
Correos no publica una API de tarifas para CityPaq, así que el precio procede de esta tabla. Introduce los precios de tu contrato con Correos en la moneda predeterminada de la tienda, sin impuestos.
Price table: una fila para Spain (ES) y/o una fila predeterminada * Default. Cada fila tiene un Price base y precios opcionales para los tamaños XS (hasta 1 kg), S (hasta 2 kg), M (hasta 3 kg), L (hasta 5 kg) y XL (más de 5 kg). Un precio de tamaño de 0 o vacío usa el precio base. Haz clic en Add row para añadir una fila y en el botón × para eliminar una. Sin una fila correspondiente, el método queda oculto. Si un país aparece dos veces, solo se usa la primera fila.
Calculation type: cómo se determina el tamaño del paquete.
Los pesos de los productos se convierten a kg desde la clase de peso de cada producto.
Condiciones
Min weight (kg): oculta el método cuando el carrito es más ligero. 0 significa sin límite.
Max weight (kg): oculta el método cuando el carrito es más pesado. Por defecto: 30, porque CityPaq acepta paquetes de hasta 30 kg. 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.
Envío gratuito
Free shipping: activa el envío gratuito con CityPaq a partir del importe indicado abajo.
Free shipping from: el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) a partir del cual este método cuesta 0. Solo se usa cuando Free shipping está activado.
Selección de taquilla CityPaq
La sección tiene un enlace al buscador oficial de taquillas CityPaq de Correos.
Locker selection: cómo elige el cliente la taquilla antes de realizar el pedido. Por defecto: el cliente introduce la taquilla.
Si eliges la lista de Correos sin credenciales de la API, o tu propia lista mientras My lockers está vacía, se pide al cliente que introduzca la taquilla manualmente.
My lockers: se usa cuando Locker selection está configurado con tu lista. Una taquilla por línea: CODE | Name | Address | Postal code | City, por ejemplo S0000213D | CityPaq Name | Street 1 | 46001 | Valencia. El código y el nombre son obligatorios. Si un código aparece dos veces, solo se usa la primera línea.
Lista de taquillas CityPaq de Correos (API) (solo se usa con la lista de taquillas CityPaq de Correos)
La sección tiene un enlace a la página de la API "terminals" del portal para desarrolladores de Correos. Solo se lee la lista de taquillas. Los precios siempre proceden de la tabla de precios.
API client ID: el client_id de tu aplicación en el portal para desarrolladores de Correos.
API client secret: el client_secret de tu aplicación en el portal para desarrolladores de Correos.
Tras guardar, ambos campos quedan vacíos y muestran Saved - leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. Marca Remove the saved client ID and client secret y haz clic en Save para eliminarlos. Si no hay nada guardado, la sección muestra No credentials saved. Cuando cambias las credenciales o la selección de taquilla, se borran las listas de taquillas en caché y el último error de la API.
Disponibilidad
Geo zone: ofrece el método solo para direcciones de esta zona geográfica. All zones (por defecto) significa todas las direcciones españolas. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore geo zone: ofrece CityPaq para todas las direcciones españolas, aunque no estén en la zona geográfica indicada arriba.
Avanzado
Debug log: escribe líneas de depuración en storage/logs/vfd_cpq_debug.log.php (en OpenCart 4, system/storage/logs/vfd_cpq_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API de Correos siempre se escriben, incluso cuando esta opción está desactivada. Las credenciales y los datos personales nunca se registran.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes, las listas en caché y los registros. Las taquillas guardadas en los pedidos se conservan. Si está desactivado (por defecto), todo se conserva para una nueva instalación.
Importación / Exportación
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El client ID y el secret de la API no se incluyen.
Import: pega un JSON de ajustes exportado desde esta extensión y haz clic en Import. Los valores se comprueban como en un guardado normal. Las credenciales guardadas se conservan.
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 CityPaq. Si se ha definido una Geo zone (y Ignore geo zone está desactivado) y la dirección queda fuera de ella, CityPaq no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no se incluyen en el importe del pedido. La extensión comprueba entonces que la dirección de entrega esté en España, el peso del carrito y el importe mínimo del pedido, busca la fila de precios de España (o la fila *) y el tamaño del paquete, y devuelve el precio. Si se aplica el envío gratuito, el precio es 0. El precio se calcula en la moneda predeterminada de la tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada. No se envía ninguna solicitud a Correos para calcular el precio.
El cuadro CityPaq locker aparece debajo del método CityPaq en el paso del método de envío. La elección se guarda en cuanto el cliente la hace. Una taquilla no aceptable se rechaza con un mensaje y la elección anterior se mantiene. Con la lista de Correos, un código de taquilla solo se acepta si Correos lo ofreció para el código postal buscado, y su nombre y dirección se toman de Correos. Un cliente puede buscar hasta 30 códigos postales distintos por sesión de compra. Después, el cliente ve Too many searches. Please enter the CityPaq locker you found on the Correos map.
El botón Continue del paso del método de envío no continúa con CityPaq sin una taquilla válida. Esto se comprueba en el servidor. El cliente ve, por ejemplo, Please choose the CityPaq locker where you want to collect your parcel. Cuando se realiza el pedido, la taquilla se guarda en él.
En OpenCart 4, el cliente hace clic en Choose en el bloque del método de envío de la página de finalización de compra y elige CityPaq en la ventana Shipping method options. El cuadro CityPaq locker aparece en esa ventana, debajo de la opción CityPaq, y funciona como se ha descrito arriba. El botón Continue de la ventana no continúa con CityPaq sin una taquilla válida. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar, y la taquilla del pedido se actualiza con él.
La lista de Correos solo se solicita cuando CityPaq es el método seleccionado, no mientras se dibuja el paso. Una lista se guarda en caché durante 12 horas por código postal. Una solicitud fallida se guarda en caché durante 10 minutos, así la finalización de compra no espera a Correos en cada actualización. El cliente nunca ve el error técnico, solo el mensaje The Correos CityPaq list cannot be loaded right now. y el campo manual.
La extensión no obtiene tarifas en tiempo real de Correos, no muestra un mapa, no preregistra envíos, no imprime etiquetas, no solicita recogidas ni hace seguimiento de paquetes. Crea el envío en tu cuenta de Correos usando la taquilla guardada en el pedido.
Puntos de recogida
La taquilla elegida se añade al método de envío del pedido, por ejemplo Correos CityPaq - CityPaq locker: .... Así el cliente la ve en el historial de pedidos de su cuenta y en los correos de pedido, y aparece impresa en la factura y en Sales > Orders. La página de pedido completado de OpenCart no muestra el método de envío.
En la página de pedido del administrador, el panel CityPaq locker situado sobre el historial muestra la taquilla y su Locker code: cuando se eligió de una lista. Para cambiarla, usa el campo Change CityPaq locker y haz clic en Save: con tu lista, elige otra taquilla del desplegable; con la lista de Correos, escribe un código de taquilla (se busca en Correos) o una dirección; en los demás casos, escribe un código o dirección nuevos. Deja el campo vacío, o mantén -- Keep the current locker --, para conservar la taquilla actual. Cada cambio también actualiza el texto del método de envío del pedido y añade una entrada al historial CityPaq locker changed to: ... sin notificar al cliente. Cambiar la taquilla requiere el permiso de modificación de pedidos (sale/order). No se necesita acceso a los ajustes de la extensión. El panel se muestra en los pedidos CityPaq también cuando la extensión está desactivada.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Correos CityPaq es el primer bloque de Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-correos-citypaq y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (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. Tras 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 el servidor de licencias no responde, 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. 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, Correos CityPaq 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 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 una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del panel o la página Edit: una vez al día durante los primeros 14 días después de introducir la clave y después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar la extensión siempre elimina la clave de licencia y su estado.
Solución de problemas
Correos CityPaq no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que la dirección de entrega esté en España. Revisa Geo zone (o activa Ignore geo zone). Comprueba que la tabla de precios tenga una fila para España o una fila *, que el carrito esté dentro de los límites de peso y de Minimum order amount, y que los productos tengan Requires Shipping en Yes.
El cliente tiene que escribir la taquilla aunque esté seleccionada la lista de Correos: comprueba que API client ID y API client secret estén guardados y mira la advertencia de la parte superior de la página de ajustes. Muestra el último error de la API de Correos. HTTP 401/403 significa que Correos rechazó las credenciales: revísalas y comprueba que tu aplicación tenga acceso a la API "terminals". Tras un error, el siguiente intento se hace al cabo de 10 minutos.
No hay taquillas para un código postal: Correos no encontró ninguna taquilla activa para ese código postal, su zona o su provincia. El cliente puede buscar otro código postal o escribir la taquilla que encuentre en el mapa de CityPaq de Correos.
El desplegable de my lockers no aparece: My lockers está vacío o sus líneas no son válidas. Cada línea necesita al menos CODE | Name.
Dónde encuentran los clientes el código de la taquilla: en el mapa de CityPaq de Correos enlazado debajo del campo de la taquilla.
La página dice "Warning: You do not have permission to modify VibeFox Correos CityPaq!": es posible que el grupo de usuarios administradores solo tenga permiso para ver los ajustes. Concede al grupo el permiso de modificación para extension/shipping/vfd_correos_citypaq (OpenCart 3) o extension/vfd_correos_citypaq/shipping/vfd_correos_citypaq (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la taquilla de una sesión de compra y de un pedido se guarda en la tabla vfd_cpq_locker (con el prefijo de tu base de datos). La dirección de la API de Correos se puede sustituir con el ajuste vfd_cpq_api_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Correos CityPaq. 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 listas de taquillas de Correos en caché y el último error de la API siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes, el registro y las taquillas de sesiones de compra sin pedido. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al instalar la extensión de nuevo. Las taquillas guardadas en los pedidos nunca se eliminan, y los pedidos existentes conservan su método y coste de envío.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla y haz clic en Uninstall (el botón naranja −) junto a VibeFox Correos CityPaq en la lista de extensiones instaladas, y luego en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Correos y CityPaq son marcas comerciales de sus respectivos titulares. Esta extensión no está afiliada ni respaldada por Correos.