VibeFox Correios 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.
Contrato de Correios (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API de precios de Correios Web Services (CWS) y necesitan las credenciales de un contrato de Correios con tarjeta de postagem. Necesitas tres datos: tu usuario de Meu Correios (normalmente el CNPJ o CPF del contrato), el código de acceso a la API y el número de la tarjeta de postagem. Genera el código de acceso en el portal de Correios Web Services (cws.correios.com.br; para homologación, cwshom.correios.com.br). También necesitas el CEP desde el que envías. Sin credenciales, el plugin funciona solo con tarifas fijas.
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_correios a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Shipping > VibeFox Correios, 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. Introduce el usuario de la API de Correios, el código de acceso, el número de tarjeta de postagem, el CEP de origen y el servicio. Si la moneda de tu tienda no es BRL, introduce la tasa en BRL. Rellena las tarifas fijas para otros países y como alternativa (véase Configuración).
6. Añade VibeFox Correios 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 Correios. 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 ve el cliente en esta zona. Déjalo vacío para usar el Method title global.
La página de ajustes muestra avisos cuando las tarifas en tiempo real o el método no pueden funcionar: solo están rellenadas algunas de las tres credenciales, falta el CEP de origen, falta la tasa en BRL para una tienda con otra moneda, o no hay ni credenciales ni tarifas fijas. Cada vez que guardas los ajustes se borran las tarifas en caché y el token de la API. Los números se pueden escribir con punto o con coma.
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. Predeterminado: Correios. Una zona puede reemplazarlo con su propio título.
Tax status: Taxable añade el impuesto de WooCommerce sobre el coste del envío; None no lo añade.
API de Correios (tarifas en tiempo real en Brasil)
Para las direcciones en Brasil, el precio procede de la API de precios de Correios. Si la API no da precio (API caída, CEP no atendido, paquete demasiado grande), se usa la tarifa fija de Country prices o el método se oculta si no hay ninguna.
API user: tu usuario del portal Meu Correios, normalmente el CNPJ o CPF del contrato.
Access code: el código de acceso a la API (código de acesso) generado en el portal de Correios Web Services. No es la contraseña del portal.
Posting card: el número de la tarjeta de postagem (cartão de postagem) de tu contrato: 10 dígitos, normalmente con dos ceros al principio, por ejemplo 0012345678. Los números más cortos se completan con ceros a la izquierda. Puedes consultar el número en la página Correios Fácil del sitio web de Correios.
Homologation: usa el entorno de pruebas de homologación de Correios con un código de acceso de homologación. Desactívalo en una tienda real.
Origin CEP: el CEP (8 dígitos) desde el que se envían los paquetes, por ejemplo 01001-000.
Service: el servicio de Correios cuyo precio se calcula en la finalización de compra. Códigos minoristas: PAC (04510, predeterminado), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Códigos de contrato: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Los códigos de contrato requieren una tarjeta de postagem de un contrato que incluya el servicio.
Other service code: opcional, un código de servicio de 5 dígitos de tu contrato que no esté en la lista, por ejemplo 03085. Si se rellena, se usa en lugar de Service.
Package format: el tipo de objeto que se envía a Correios.
Default product weight (kg): se envía a Correios para cada producto que no tiene peso. Default: 0.3. Los pesos y las dimensiones de los productos se convierten desde las unidades de tu tienda, y el carrito se tarifica como un único paquete.
BRL → store currency rate: el nombre del campo muestra la moneda de tu tienda. Las tarifas de Correios están en BRL. Si la moneda de tu tienda no es BRL, introduce cuántas unidades de tu moneda vale 1 BRL, por ejemplo 0.17. Sin este valor no se usan las tarifas en tiempo real. Si la moneda de tu tienda es BRL, déjalo vacío.
Tarifas fijas (para países fuera de Brasil, sin credenciales de la API y como alternativa cuando la API no da precio)
Country prices: tabla de países con un precio Base y precios según el peso del carrito en la moneda de tu tienda: XS hasta 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL más de 5 kg. Si el precio de una talla está vacío o es cero, se usa el precio Base. Haz clic en Add country para añadir una fila y en la cruz para eliminarla. La fila * Default (all other countries) fija los precios de todos los países que no tengan fila propia. Un país sin fila (y sin *) no tiene tarifa fija. Un precio base de 0 significa envío gratuito para ese país.
Fixed price per: Order cobra el precio una sola vez. Item (price × quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo a las tarifas fijas. Las tarifas en tiempo real siempre se calculan para el paquete completo.
Condiciones
Min cart weight (kg): oculta el método si el peso del carrito es inferior a este valor. 0 significa sin límite.
Max cart weight (kg): oculta el método si el peso del carrito supera este valor. Default: 30. 0 significa sin límite. Los paquetes PAC y SEDEX de Correios pueden pesar hasta 30 kg.
Minimum order amount: muestra el método solo cuando el subtotal del carrito alcanza este importe. Déjalo vacío para mostrarlo siempre.
Excluded shipping classes: oculta el método si algún artículo del carrito tiene una de estas clases de envío de WooCommerce.
Free shipping: activa el envío gratuito a partir del importe indicado abajo.
Free shipping from: el subtotal del carrito a partir del cual el envío es gratuito. En ese caso no se hace ninguna solicitud a la API.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona que coincida.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que la tienda envía. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra los cálculos de precios en WooCommerce > Status > Logs, origen vfd-correios. Los errores de la API siempre se registran, aunque esta opción esté desactivada. El usuario de la API, el código de acceso, la tarjeta de postagem, el token y los CEP de los clientes no se registran.
Remove data on uninstall: si está activado, al eliminar el plugin se borran sus ajustes, los métodos de las zonas y las tarifas 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 una tarifa al plugin. Primero el plugin comprueba las condiciones: peso del carrito, importe mínimo del pedido y clases de envío excluidas. Si se aplica el envío gratuito, el cliente obtiene una tarifa gratuita y no se envía ninguna solicitud a Correios.
Para una dirección en Brasil con credenciales configuradas, el plugin primero obtiene un token de la API para tu tarjeta de postagem. El token también proporciona los números de contrato y de oficina regional, de modo que el precio es el de tu contrato. Después solicita el precio del servicio elegido según el CEP de origen y de destino, el peso del paquete en gramos y el tamaño del paquete en cm. El precio solo se solicita si el CEP de destino tiene 8 dígitos. Si todos los productos tienen dimensiones, el tamaño del paquete se estima a partir de ellas; si no, se envía el tamaño mínimo de Correios. Los paquetes de más de 30 kg no se envían a la API. El precio en BRL se convierte con tu tasa. El servicio se guarda con la línea de envío del pedido como Correios service y se ve en la administración del pedido.
Cada precio se guarda en caché durante 1 hora por paquete. Una solicitud fallida se guarda en caché durante 10 minutos, para que una caída de la API no ralentice cada actualización de la finalización de compra. El token se guarda en caché hasta poco antes de caducar y se renueva automáticamente; si Correios lo rechaza, se solicita uno nuevo y la solicitud de precio se repite una vez. El tiempo de espera de la API es de 12 segundos.
Si la API no da precio, se usa la tarifa fija, o el método se oculta si no hay tarifa fija. El cliente nunca ve los detalles de los errores de la API; van al registro de WooCommerce.
El método funciona en la finalización de compra clásica y en los bloques de Carrito y de Finalizar compra. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin solo calcula tarifas. No obtiene precios internacionales de Correios (Exporta Fácil, Packet), estimaciones de plazos de entrega, etiquetas, prepostagens, declaraciones ni seguimiento. Los clientes no pueden elegir una agencia ni una taquilla de Correios. No se añaden servicios adicionales (valor declarado, entrega en mano, aviso de recibo). Muestra un servicio de Correios por tienda, y las tasas de moneda no se actualizan automáticamente.
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 Correios. 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. Eliminar la clave de un sitio no libera su cupo de dominio. Libera el cupo en tu cuenta de vibefox.net.
Sin una clave activa, Correios no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión sí la ven, marcada 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 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 renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Correios 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, debe existir una tarifa fija para el país o para *.
El método muestra una tarifa fija en lugar de la tarifa de Correios: abre WooCommerce > Status > Logs, origen vfd-correios. Allí se registra el error de Correios: código de acceso incorrecto, servicio que no está en tu contrato, CEP no atendido, paquete de más de 30 kg o que supera los límites de tamaño. Comprueba también que el CEP de origen está configurado y, si la moneda de la tienda no es BRL, la tasa en BRL. Activa Debug log para ver cada cálculo.
Falla la solicitud del token: comprueba el usuario de la API, el código de acceso, la tarjeta de postagem y el entorno. Un código de acceso de homologación solo funciona con Homologation activado, y un código de producción solo con esa opción desactivada.
Las tarifas parecen desactualizadas tras un cambio: guarda la página de ajustes. Esto borra las tarifas en caché y el token de la 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 un cupo 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. Los ajustes, los métodos de zona y las tarifas en caché solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos nunca se tocan.
Correios es una marca comercial de su respectivo titular. Este plugin no está afiliado ni respaldado por Correios.