VibeFox Correos CityPaq for PrestaShop — Ayuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Entrega en España: las taquillas CityPaq solo existen en España, por lo que el transportista solo se ofrece para direcciones de entrega en España.
Credenciales de API de Correos (solo para la lista de taquillas en tiempo real): la lista de taquillas CityPaq de Correos lee las taquillas activas de la API "terminals" de Correos. En el portal de 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 API.
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 Correos CityPaq en la lista de módulos más adelante y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key dentro del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).
4. Rellena la tabla de precios, elige cómo selecciona el cliente la taquilla (consulta Configuración) y haz clic en Save.
Al instalar, el módulo crea el transportista Correos CityPaq con el texto del plazo de entrega Delivery to a Correos CityPaq parcel locker. El transportista se asigna a todos los grupos de clientes y a la zona de España. Puedes cambiar zonas, grupos de clientes, plazo de entrega, logotipo y límites de tamaño en Shipping > Carriers. No definas 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 Correos CityPaq > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Los precios y los importes admiten coma decimal o punto decimal.
Las advertencias sobre los ajustes te indican cuando no se encontró el transportista, cuando la tabla de precios no tiene fila para España ni fila por defecto, cuando la selección de taquilla elegida no puede funcionar (no hay taquillas en tu lista, no hay credenciales de API), cuál fue el último error de la API de Correos, y cuando la unidad de peso de tu tienda no la conoce el módulo (los pesos de los productos se leen entonces como kg; configura kg, g, lb u oz en International > Localization). Si el nombre está vacío, no es válido o supera los 64 caracteres, si un peso o un importe no es un número válido igual o superior a 0, o si Min weight (kg) es mayor que Max weight (kg), la página muestra un error y no se guarda nada. Los precios no válidos en la tabla de precios 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 transportista nunca se ofrece para otros países.
Enable/Disable: activa o desactiva el envío Correos CityPaq. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del método de envío que ve el cliente en la finalización de compra. También es el nombre del transportista. Por defecto: Correos CityPaq. Obligatorio, máximo 64 caracteres.
Tax: la regla de impuestos del transportista. PrestaShop añade este impuesto sobre los precios de la tabla. No tax significa que los precios son finales.
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 sale de esta tabla. Introduce las tarifas 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 por defecto * Default. Cada fila tiene un Price base y precios opcionales para los tamaños de paquete 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 icono de papelera para eliminar una. Sin una fila correspondiente, el transportista se oculta. 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 unidad de peso de tu tienda (por ejemplo, kg, g, lb u oz).
Condiciones
Min weight (kg): oculta el transportista cuando el carrito es más ligero. 0 significa sin límite.
Max weight (kg): oculta el transportista 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 transportista solo cuando el subtotal del carrito (productos que requieren envío, después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Envío gratuito
Free shipping: activa la entrega gratuita de CityPaq a partir del importe indicado abajo.
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual este transportista 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 API, o tu propia lista mientras My lockers está vacía, se pide al cliente que introduzca la taquilla.
My lockers: se usa cuando Locker selection está configurado como tu lista. Una taquilla por línea: CODE | Name | Address | Postal code | City. El código y el nombre son obligatorios. Si un código aparece dos veces, solo se usa la primera línea.
Lista de Correos CityPaq (API) (se usa solo con la lista de Correos CityPaq)
La sección tiene un enlace a la página de la API "terminals" en el portal de desarrolladores de Correos. Solo se lee la lista de taquillas. Los precios siempre vienen de la tabla de precios.
API client ID: el client_id de tu aplicación en el portal de desarrolladores de Correos.
API client secret: el client_secret de tu aplicación en el portal de desarrolladores de Correos.
Después de guardar, ambos campos quedan vacíos y muestran Saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Marca Remove the saved client ID and client secret y haz clic en Save para eliminarlos. Cuando 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é.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece CityPaq para cualquier dirección de España, aunque la zona de la dirección no esté vinculada al transportista. Cuando está activado, el transportista se vincula a todas las zonas activas, incluidas las creadas después. Al desactivarlo de nuevo, el transportista recupera las zonas que tenía antes. Desactivado (recomendado) significa que se usan las zonas definidas en Shipping > Carriers.
Avanzado
Debug log: escribe líneas de depuración en logs/vfd_cpq_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API de Correos se escriben siempre, incluso cuando esto está desactivado. 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: cuando está activado, al desinstalar el módulo se eliminan los ajustes, el transportista, las listas en caché y los registros. Las taquillas guardadas en los pedidos se conservan. Cuando 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 CityPaq. 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 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 tu tienda y después se muestra en la moneda del carrito del cliente. Los impuestos se añaden mediante la regla de impuestos del transportista.
Cuando el cliente selecciona CityPaq, el cuadro CityPaq locker aparece debajo del transportista. La elección se guarda en el carrito 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 carrito. Después de eso, el cliente ve Demasiadas búsquedas. Introduce la taquilla CityPaq que encontraste en el mapa de Correos.
El botón Continue del paso de envío no avanza sin una taquilla válida. Esto también se comprueba en el servidor. El cliente ve, por ejemplo, Elige la taquilla CityPaq donde quieres recoger tu paquete. Al realizar el pedido, la taquilla del carrito se guarda en el pedido.
La lista de Correos se pide solo cuando el cliente selecciona CityPaq, no para cada visitante del paso de envío. Una lista se guarda en caché durante 12 horas por código postal. Una petición fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a Correos en cada actualización. El tiempo de espera de la API es de 12 segundos. El cliente nunca ve el error técnico, solo un mensaje breve y el campo manual. El cuadro de taquilla funciona con los temas Classic y Hummingbird.
El módulo no obtiene tarifas en tiempo real de Correos, no muestra un mapa, no registra envíos por adelantado, no imprime etiquetas, no solicita recogidas ni hace el 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 guarda en el pedido. El cliente la ve como CityPaq locker: en la página de confirmación del pedido y en la página de detalles del pedido de su cuenta. En el correo de confirmación del pedido y en el correo de nuevo pedido del módulo Mail alerts, la taquilla se añade a la línea del transportista, por ejemplo, Correos CityPaq - CityPaq locker: ....
En la página de pedido del admin, el bloque CityPaq locker 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 de la lista 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 una dirección nuevos. Deja el campo vacío para mantener la taquilla actual. Cada cambio añade un mensaje privado al pedido: Taquilla CityPaq cambiada a: .... Cambiar la taquilla requiere permiso para editar pedidos. No hace falta acceso a las páginas de Modules.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Correos CityPaq es el primer bloque de Modules > Module Manager > VibeFox Correos CityPaq > Configure, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-correos-citypaq 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. 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 no se puede acceder al 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. 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 transportista Correos CityPaq no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también queda oculto 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 por 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
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. En Shipping > Carriers, comprueba que el transportista cubre la zona de España y el grupo del cliente (o activa Ignore shipping zones). Comprueba que la tabla de precios tiene una fila para España o una fila *, y que el carrito está dentro de los límites de peso y de Minimum order amount. Además, los productos pueden estar limitados a determinados transportistas en su página de producto.
Los clientes tienen 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 sobre los 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 tiene acceso a la API "terminals". Después de un error, el siguiente intento se hace tras 10 minutos.
Sin taquillas para un código postal: Correos no encontró ninguna taquilla activa para ese código postal, su zona ni su provincia. El cliente puede buscar otro código postal o introducir la taquilla que encuentre en el buscador de CityPaq de Correos.
La lista desplegable de mis taquillas no aparece: My lockers está vacía 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 buscador de CityPaq de Correos enlazado bajo el campo de la taquilla.
La página indica que no se encontró el transportista, o que no se pudo actualizar el transportista: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para crearlo de nuevo. Al restablecer se conservan los ajustes y el estado del transportista.
Notas para desarrolladores: la taquilla de un carrito y de un pedido se guarda en la tabla vfd_cpq_locker (con el prefijo de tu base de datos). El módulo usa la API "terminals" de producción de Correos.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Correos CityPaq y elige Uninstall. La clave de licencia, el estado de la licencia, las listas de taquillas de Correos en caché y el último error de la API se eliminan siempre. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial), y se eliminan los ajustes, el registro y las taquillas de carritos sin pedido. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Volver a instalar el módulo restaura el estado del transportista que tenía antes. Las taquillas guardadas en los pedidos nunca se eliminan.
Correos y CityPaq son marcas comerciales de sus respectivos propietarios. Este módulo no está afiliado a Correos ni cuenta con su respaldo.