VibeFox Correos CityPaq for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

Credenciales de API de Correos (solo para la lista en tiempo real de taquillas): 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 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_correos_citypaq a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq, o haz clic en Settings debajo del nombre del plugin en la página 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. Rellena la tabla de precios y elige cómo selecciona el cliente la taquilla (ver Configuración).

6. Añade VibeFox Correos CityPaq a la zona de envío de España en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. Se aplican a todas las zonas de envío. Al añadir el método a una zona, la ventana de la zona solo tiene un campo:

Title (zone): el nombre de esta opción en la finalización de compra para esta zona. Déjalo vacío para usar el Name general.

Las advertencias encima de los ajustes indican cuándo la tabla de precios no tiene ninguna fila válida, cuándo la selección de taquilla elegida no puede funcionar (no hay taquillas en tu lista, no hay credenciales de API) y cuál fue el último error de la API de Correos. Los precios y los importes admiten coma o punto decimal.

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 método en todas las zonas a la vez.

Name: el nombre del método de envío que ve el cliente en la finalización de compra. Por defecto: Correos CityPaq.

Tax status: Taxable añade el impuesto de WooCommerce sobre los precios de la tabla; None no lo añade.

Precios (el título de la sección muestra la moneda de tu tienda)

Price table: una fila para Spain (ES) y/o una fila por defecto *. 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 la cruz para eliminar una. Introduce tus tarifas del contrato con Correos en la moneda de la tienda. Sin una fila correspondiente, el método se oculta. Los precios no válidos y las filas duplicadas se indican al guardar.

Calculation type: cómo se determina el tamaño del paquete.

Per order (size by the total cart weight): un precio para todo el carrito, elegido según el peso total. Es el valor por defecto.

Per item (size by each item weight, multiplied by quantity): cada producto recibe el precio de su propio tamaño, multiplicado por su cantidad, y los precios se suman.

Los pesos de los productos se convierten a kg desde la unidad de peso de tu tienda (kg, g, lbs u oz).

Condiciones

Min weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite.

Max weight (kg): oculta el método cuando el carrito pesa más. 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 del carrito (después de descuentos y antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.

Excluded shipping classes: oculta el método cuando el carrito contiene un producto de una de estas clases de envío de WooCommerce, por ejemplo artículos voluminosos que no caben en una taquilla. El plugin no comprueba las dimensiones del paquete.

Envío gratis

Free shipping: activa el envío gratis CityPaq desde el importe indicado abajo.

Free shipping from: el subtotal del carrito (después de descuentos y 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

Locker selection: cómo elige el cliente la taquilla antes de hacer el pedido. Por defecto: el cliente introduce la taquilla.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): el cliente ve las taquillas CityPaq activas del código postal de la dirección de envío y puede buscar otro código postal de 5 dígitos. Si un código postal no tiene taquilla, se listan las de la misma zona y después las de la misma provincia, primero los códigos postales más cercanos. Cada taquilla muestra su nombre, dirección, código postal, localidad y horario. Si la lista no se puede cargar o no encuentra nada, el cliente introduce la taquilla manualmente.

Customer enters the locker (code or address from the Correos finder): un campo obligatorio para el código de la taquilla (por ejemplo S0000213D) o la dirección, con un enlace al buscador oficial de CityPaq de Correos.

Customer chooses from my list of lockers (below): una lista desplegable obligatoria con las taquillas de My lockers. Las taquillas cercanas al código postal del cliente aparecen primero.

Do not ask for a locker: sin pregunta sobre la taquilla en la finalización de compra.

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 manualmente.

My lockers: se usa cuando Locker selection está en tu lista. Una taquilla por línea: CODE | Name | Address | Postal code | City. El código y el nombre son obligatorios. Las líneas no válidas y duplicadas se indican al guardar.

Lista de CityPaq de Correos (API) (se usa solo con la lista de CityPaq de Correos)

La sección tiene un enlace a la página de la API "terminals" del portal de 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 de desarrolladores de Correos.

API client secret: el client_secret de tu aplicación en el portal de desarrolladores de Correos.

Cuando cambies las credenciales o la selección de taquilla, se borran las listas de taquillas guardadas en caché.

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece CityPaq en cualquier dirección de España, aunque ninguna zona de envío contenga este método. Desactivado (recomendado) significa que se ofrece donde lo hayas añadido a una zona de envío.

Avanzado

Debug log: escribe líneas de depuración en WooCommerce > Status > Logs, origen vfd-correos-citypaq. Los errores de la API de Correos siempre se registran, aunque esto esté desactivado. Las credenciales y los datos personales nunca se registran.

Remove data on uninstall: si está activado, al eliminar el plugin se borran sus ajustes y sus métodos de zona. Desactivar el plugin nunca borra nada. Las taquillas guardadas en los pedidos se conservan.

Cómo funciona en la finalización de compra

Cuando el cliente introduce una dirección de entrega en España, WooCommerce pide al plugin una tarifa. El plugin comprueba el peso del carrito, el importe mínimo del pedido y las clases de envío excluidas, busca la fila de precios de España (o la fila *) y el tamaño del paquete, y muestra el precio. Si se aplica el envío gratis, el precio es 0.

Cuando el cliente selecciona CityPaq, el campo de taquilla aparece debajo del método. El pedido no se puede realizar sin una taquilla válida. Esto también se comprueba en el servidor, incluso en los pedidos realizados con los bloques de Carrito y Finalizar compra. Con la lista de Correos, un código de taquilla solo se acepta si Correos lo ofreció a este cliente, y su nombre y dirección se toman de Correos. El número de búsquedas por código postal en una sesión de cliente está limitado. Cuando se alcanza el límite, el cliente introduce la taquilla manualmente.

Una lista de Correos 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 método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).

El plugin 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 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. Se muestra en la administración del pedido debajo de la dirección de envío, en la página de confirmación del pedido, en My account > Orders y en todos los correos electrónicos del pedido (HTML y texto plano) como CityPaq locker.

En la administración del pedido puedes cambiar la taquilla en el campo Change CityPaq locker: elige otra taquilla de tu lista o escribe un nuevo código o dirección. Con la lista de Correos, un código de taquilla escrito se busca en Correos. Deja el campo vacío para conservar la taquilla actual. Cada cambio añade una nota al pedido.

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 Correos CityPaq. 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 quitarla 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Correos CityPaq no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión sí lo ven, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un aviso en la página 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 necesitan una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

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, que la dirección está en España y que el método está añadido a la zona de envío correspondiente (o que Ignore shipping zones está activado). 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, de Minimum order amount y de Excluded shipping classes.

El cliente debe escribir la taquilla aunque esté seleccionada la lista de Correos: comprueba que API client ID y API client secret están rellenados y mira la advertencia encima de 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". 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 introducir la taquilla encontrada en el buscador de CityPaq de Correos.

La lista desplegable de mis taquillas 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 buscador de CityPaq de Correos enlazado debajo del campo de taquilla.

Notas para desarrolladores: la taquilla se guarda en los metadatos del pedido _vfd_cpq_locker (texto que se muestra en todas partes) y _vfd_cpq_locker_id (código de la taquilla, cuando se elige de la lista de Correos o de tu lista). El plugin usa la API de producción "terminals" de Correos. No hay entorno sandbox documentado para esta API.

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 en 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, al igual que las listas de taquillas de Correos guardadas en caché y el último error de la API. Los ajustes y los métodos de zona solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una futura reinstalación. Las taquillas guardadas en los pedidos nunca se borran, y los pedidos existentes conservan sus líneas de envío.

Correos y CityPaq son marcas comerciales de sus respectivos titulares. Este plugin no está afiliado ni respaldado por Correos.