VibeFox Correios for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Contrato con Correios (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API de precios de Correios Web Services (CWS) y requieren las credenciales de un contrato de Correios con tarjeta de postagem. Necesitas tres valores: 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 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 módulo funciona solo con tarifas fijas.
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 después VibeFox Correios en la lista de módulos 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. 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 predeterminada 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) y haz clic en Save.
Al instalar, el módulo crea el transportista Correios con el texto del plazo de entrega Correios (Brazilian Post). El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre procede del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Correios > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de Correios y los tokens de la API en caché. Los números se pueden escribir con punto o con coma.
La página muestra advertencias cuando las tarifas en tiempo real o el transportista no pueden funcionar: solo se han rellenado algunas de las tres credenciales, falta el CEP de origen, falta la tasa en BRL en una tienda con otra moneda, o no hay ni credenciales ni tarifas fijas. Cada advertencia indica si mientras tanto se usan las tarifas fijas o si el transportista se oculta. También aparece una advertencia si la unidad de peso o de dimensiones de la tienda no es conocida por el módulo (entonces se interpreta como kg o cm); configura kg, g, lb u oz y cm, mm, m o in en International > Localization (Local units).
El guardado se rechaza con un mensaje si el título del método está vacío o no es válido (máximo 64 caracteres), si un campo numérico o un precio en Country prices no es un número igual o mayor que 0, si la tasa en BRL es 0, si Min cart weight es mayor que Max cart weight, si el CEP de origen no tiene 8 dígitos o si el otro código de servicio tiene más de 5 dígitos. Nada se guarda hasta que corrijas el valor.
General
Enable Correios: activa o desactiva el transportista en todas las zonas a la vez. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista que se muestra en el carrito y en la finalización de compra. Predeterminado: Correios. Obligatorio.
Tax: la regla de impuesto que se suma al coste de envío, o No tax (la opción predeterminada).
API de Correios (tarifas en tiempo real en Brasil)
Para direcciones en Brasil, el precio procede de la API de precios de Correios. Si la API no devuelve precio (API caída, CEP no atendido, paquete demasiado grande), se usa la tarifa fija de Country prices o el transportista se oculta si no hay ninguna. Los detalles de los errores van al registro, nunca al cliente.
API user: tu usuario de acceso al portal Meu Correios, normalmente el CNPJ o CPF del contrato.
Access code: el código de acceso a la API (código de acceso) generado en el portal de Correios Web Services. No es la contraseña del portal. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it (empty the API user as well to remove it). Escribe un valor nuevo solo para cambiarlo. Para eliminar el código guardado, vacía API user y Access code y guarda.
Posting card: el número de la tarjeta de postagem (cartão de postagem) de tu contrato: 10 dígitos, normalmente empieza por dos ceros, 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 homologación (pruebas) de Correios: las solicitudes van a apihom.correios.com.br con un código de acceso de homologación. Desactívalo en una tienda en producción.
Origin CEP: el CEP (8 dígitos) desde el que se envían los paquetes, por ejemplo 01001-000.
Service: el servicio de Correios con tarifa 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. Un código más corto se completa con ceros a la izquierda. Si se rellena, se usa en lugar de Service.
Package format: el tipo de objeto que se envía a Correios.
Default product weight: en kg, se envía a Correios para cada producto que no tenga peso. Predeterminado: 0.3. Los pesos y las dimensiones de los productos se convierten desde las unidades de tu tienda (la descripción del campo las muestra), y el carrito se tarifica como un solo paquete.
BRL → store currency rate: el nombre del campo muestra la moneda predeterminada de tu tienda, por ejemplo BRL → EUR rate. Las tarifas de Correios están en BRL. Si tu moneda predeterminada no es BRL, introduce cuántas unidades de tu moneda vale un BRL, por ejemplo 0.17. Sin este valor no se usan las tarifas en tiempo real. La tasa debe ser mayor que 0. Si tu moneda predeterminada es BRL, déjalo vacío.
Tarifas fijas (se usan para países fuera de Brasil, sin credenciales de la API y como alternativa cuando la API no devuelve precio)
Country prices: una tabla de países con un precio Base y precios según el peso del carrito en la moneda predeterminada de tu tienda, sin impuestos: XS hasta 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL más de 5 kg. Un precio de tamaño vacío o igual a cero usa el precio Base. Haz clic en Add country para añadir una fila y en el icono de la cruz para eliminar una. La fila * Default (all other countries) fija los precios de todos los países sin fila propia. Un país sin fila (y sin *) no tiene tarifa fija. Una fila sin ningún precio no se guarda. Un precio que no sea un número, o que sea negativo, detiene el guardado con un error. 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: en kg, oculta el transportista por debajo de este peso del carrito. 0 significa sin límite. No puede ser mayor que Max cart weight.
Max cart weight: en kg, oculta el transportista por encima de este peso del carrito. Predeterminado: 30. 0 significa sin límite; un campo vacío significa 30 kg. Los paquetes PAC y SEDEX de Correios pueden pesar hasta 30 kg.
Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (productos que requieren envío, después de descuentos y antes de impuestos) alcance este importe. Déjalo vacío para mostrarlo siempre.
Free shipping: activa el envío gratuito a partir del importe indicado abajo.
Free shipping from: el subtotal del carrito (después de descuentos y antes de impuestos) 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
Normalmente el transportista se muestra en las zonas a las que está asignado en Shipping > Carriers.
Ignore shipping zones: ofrece el transportista para los países indicados abajo, sea cual sea la zona que corresponda. Al guardar, el transportista se añade a todas las zonas. Al desactivar la opción se eliminan las zonas que añadió. Una zona creada más tarde, mientras la opción esté activada, se añade automáticamente.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos de la tienda. Este campo se usa solo cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de precios en logs/vfd_crr_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso cuando 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.
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 el módulo se borran los ajustes, el transportista, los servicios de los pedidos, las tarifas en caché y el registro. Si está desactivado, se conserva todo 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 Correios. 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 primero las condiciones: países permitidos (con Ignore shipping zones), peso del carrito e importe mínimo del pedido. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Correios.
Para una dirección en Brasil con credenciales configuradas, el módulo obtiene primero 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 el de destino, el peso del paquete en gramos y el tamaño del paquete en cm. Solo se solicita un precio cuando el CEP de destino tiene 8 dígitos. Cuando 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 precio se calcula en tu moneda predeterminada y después se muestra en la moneda del carrito del cliente.
Cada precio se guarda en caché durante 1 hora por paquete. Una solicitud fallida se guarda en caché durante 10 minutos, de modo que una caída de la API no ralentiza 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 un token 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 devuelve precio, se usa la tarifa fija, o el transportista se oculta cuando no hay tarifa fija. El cliente nunca ve los detalles de los errores de la API; estos van al registro de depuración.
Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.
El módulo 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 un casillero de Correios. No se añaden servicios adicionales (valor declarado, mano propia, aviso de recibo). Muestra un único servicio de Correios por tienda, y las tasas de moneda no se actualizan automáticamente.
Pedidos
Cuando se realiza un pedido con el transportista de Correios, el módulo guarda cómo se calculó su precio de envío. La página del pedido en el back office muestra entonces un bloque Correios con Correios service (para una tarifa en tiempo real, por ejemplo PAC — contrato (03298)) y Price source: Live price (Correios API), Fixed price o Free shipping.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Correios es el primer bloque de Modules > Module Manager > VibeFox Correios > 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-correios 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 de Correios 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
Correios no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable Correios está activado. En Shipping > Carriers, comprueba que el transportista cubre la zona del país del cliente y el grupo del cliente (o que Ignore shipping zones está activado y el país está permitido). Revisa los límites de peso y Minimum order amount. Sin tarifa en tiempo real, debe existir una tarifa fija para el país o para *. Además, los productos pueden limitarse a determinados transportistas en la página del producto.
El transportista muestra una tarifa fija en lugar de la tarifa de Correios: mira el campo Log de la página del módulo. Allí se registran los errores 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 por encima de los límites de tamaño. Comprueba también que el CEP de origen está configurado, que el CEP del cliente tiene 8 dígitos y, si la moneda predeterminada no es BRL, la tasa en BRL. Activa Debug log para ver cada cálculo.
La solicitud de token falla: 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 funciona solo con Homologation activado, y un código de producción solo con esta opción desactivada.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Así se borran las tarifas en caché y el token de la API.
La página indica que no se encontró el transportista de Correios: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Al guardar aparece el mensaje de que no tienes permiso: tu perfil de empleado puede ver el módulo pero no configurarlo. Guardar los ajustes y vaciar el registro requieren el permiso de configuración del módulo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Correios y elige Uninstall. La clave de licencia, el estado de la licencia, las tarifas y los tokens en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se eliminan los ajustes, los servicios guardados de los pedidos y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, el transportista se restaura con el estado que tenía antes.
Correios es una marca registrada de su respectivo titular. Este módulo no está afiliado a Correios ni cuenta con su respaldo.