VibeFox Correios for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Contrato con Correios (solo para precios en tiempo real): los precios en tiempo real usan la API de precios de Correios Web Services (CWS) y necesitan las credenciales de un contrato con Correios que tenga tarjeta de envío (cartão de postagem). Necesitas tres datos: tu usuario de Meu Correios (normalmente el CNPJ o el CPF del contrato), el código de acceso a la API y el número de la tarjeta de envío. 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, la extensión funciona solo con precios fijos.

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 de OpenCart 3 vfd_correios-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_correios.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_correios-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 Correios 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 el campo 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. Introduce el usuario de la API de Correios, el código de acceso, el número de la tarjeta de envío, el CEP de origen y el servicio. Si la moneda predeterminada de tu tienda no es BRL, introduce el tipo de cambio a BRL. Rellena los precios fijos de los demás países y el precio alternativo (consulta Configuración), activa Enable Correios 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_correios.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, elige el tipo de extensión Shipping, busca VibeFox Correios, haz clic en Install (el botón verde +) y después 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 Correios y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Correios que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Correios > Edit. Las secciones aparecen a la izquierda. Un único botón Save en la parte inferior guarda toda la página sin recargarla. Cada guardado también borra los precios de Correios en caché y los tokens de la API. Los números pueden escribirse con punto o con coma. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

La página muestra advertencias cuando los precios en tiempo real o el método no pueden funcionar: solo se han rellenado algunas de las tres credenciales, falta el CEP de origen, falta el tipo de cambio a BRL en una tienda con otra moneda, o no hay credenciales ni precios fijos. Cada advertencia indica si, mientras tanto, se usan los precios fijos o si el método se oculta. También aparece una advertencia si la tienda no tiene una clase de peso con la unidad kg ni una clase de longitud con la unidad cm; en ese caso, las unidades de los productos se convierten según el nombre de la unidad de su clase (las unidades desconocidas se leen como kg o cm). Revisa System > Localisation > Weight Classes y Length Classes.

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, sin < > ; = # { }), si un campo numérico o un precio de Country prices no es un número igual o mayor que 0, si el tipo de cambio a BRL es 0, si Min cart weight es mayor que Max cart weight, si el CEP de origen no tiene 8 dígitos, si el otro código de servicio tiene más de 5 dígitos o si Sort order no es un número entero. No se guarda nada hasta que corrijas el valor.

General

Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica en Conditions, o a una lista de países con Ignore shipping zones.

Enable Correios: muestra u oculta Correios en la finalización de compra. Por defecto: desactivado.

Method title: el nombre del método de envío que ve el cliente en el carrito y en la finalización de compra. Por defecto: Correios. Obligatorio.

Sort order: la posición de Correios entre los métodos de envío en la finalización de compra. Un número entero.

API de Correios (precios en tiempo real en Brasil)

Para las direcciones en Brasil, el precio procede de la API de precios de Correios. Si la API no devuelve ningún precio (API caída, CEP no atendido, paquete demasiado grande), se usa el precio fijo de Country prices o, si no hay ninguno, el método se oculta. Los detalles de los errores van al registro, nunca al cliente.

API user: tu inicio de sesión en el portal Meu Correios, normalmente el CNPJ o el CPF del contrato. Si lo vacías, también se borra el código de acceso guardado.

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. Tras 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 si quieres cambiarlo. Para borrar el código guardado, vacía API user y guarda.

Posting card: el número de la tarjeta de envío (cartão de postagem) de tu contrato: 10 dígitos, normalmente empiezan 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 se envían 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 precio en la finalización de compra. Códigos de tarifa normal: PAC (04510, por defecto), 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 necesitan una tarjeta de envío 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 (kg): se envía a Correios para cada producto que no tenga peso. Por defecto: 0.3. Los pesos y las dimensiones de los productos se convierten a partir de sus clases de peso y de longitud, y el carrito se tarifica como un único paquete.

BRL → store currency rate: el nombre del campo muestra la moneda predeterminada de tu tienda, por ejemplo BRL → EUR rate. Los precios de Correios están en BRL. Si la moneda predeterminada no es BRL, introduce cuántas unidades de tu moneda vale un BRL, por ejemplo 0.17. Sin este dato no se usan los precios en tiempo real. El tipo de cambio debe ser mayor que 0. Si la moneda predeterminada es BRL, déjalo vacío.

Precios fijos (se usan para los países fuera de Brasil, sin credenciales de la API y como alternativa cuando la API no devuelve ningún 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 y 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 botón × para eliminar una. La fila * All other countries define los precios de todos los países que no tengan fila propia. Un país sin fila (y sin *) no tiene precio fijo. Una fila necesita al menos un precio. Un precio base de 0 significa envío gratuito para ese país.

Fixed price per: Order (por defecto) 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 los precios fijos. Los precios en tiempo real siempre se calculan para el paquete completo.

Conditions

Min cart weight (kg): oculta el método si el carrito pesa menos que esto. 0 significa sin límite. No puede ser mayor que Max cart weight.

Max cart weight (kg): oculta el método si el carrito pesa más que esto. Por defecto: 30. 0 significa sin límite; un campo vacío equivale a 30 kg. Los paquetes PAC y SEDEX de Correios pueden pesar hasta 30 kg.

Minimum order amount: muestra el método solo cuando el subtotal de los productos que requieren envío (después del cupón y antes de impuestos) alcanza 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 de los productos que requieren envío (después del cupón y antes de impuestos) a partir del cual el envío es gratuito. En ese caso no se hace ninguna solicitud a la API.

Tax class: la clase de impuesto que se añade sobre el coste de envío, o No tax (por defecto).

Geo zone: ofrece Correios solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se usa con Ignore shipping zones.

Disponibilidad sin zonas de envío

Normalmente el método se ofrece en la zona geográfica seleccionada en Conditions (en todas las zonas si no se selecciona ninguna).

Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona geográfica que coincida. En ese caso no se comprueba el Geo zone de Conditions.

Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activados en la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.

Avanzado

Debug log: escribe los cálculos de precios en storage/logs/vfd_crr_debug.log.php (en OpenCart 4, system/storage/logs/vfd_crr_debug.log.php). El archivo no se puede leer 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 envío, el token y los CEP de los clientes no se registran. Cuando el archivo alcanza 5 MB, se mueve a vfd_crr_debug.old.log.php y se inicia un registro nuevo.

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 la extensión se borran los ajustes de Correios y el registro. Si está desactivado (por defecto), se conservan para una nueva instalación. Los servicios de Correios guardados con los pedidos siempre se conservan.

Importación / Exportación

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El código de acceso no se exporta.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. El código de acceso guardado se conserva.

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 Correios. Si se ha definido una Geo zone (y Ignore shipping zones está desactivado) y la dirección queda fuera de ella, no se ofrece Correios. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no se incluyen en el importe del pedido. A continuación, la extensión comprueba las condiciones: países permitidos (con Ignore shipping zones), peso del carrito e importe mínimo del pedido. El importe del pedido es el precio de los productos que requieren envío, después del descuento del cupón y antes de impuestos. 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, la extensión primero obtiene un token de la API para tu tarjeta de envío. El token también proporciona los números de contrato y de oficina regional, así 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. 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 tipo de cambio. El precio se calcula en la moneda predeterminada de tu tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.

Cada precio se guarda en caché durante 1 hora. 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 (como máximo durante el tiempo de vida de la caché de OpenCart, 1 hora por defecto) 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 ningún precio, se usa el precio fijo, o el método se oculta cuando no hay precio fijo. El cliente nunca ve los detalles de los errores de la API; estos van al registro de depuración.

La extensión solo calcula tarifas. No obtiene precios internacionales de Correios (Exporta Fácil, Packet), estimaciones de plazos de entrega, etiquetas, prenotificaciones, declaraciones ni seguimiento. Los clientes no pueden elegir una agencia ni un punto de recogida de Correios. No se añaden servicios adicionales (valor declarado, entrega en mano, aviso de recibo). Muestra un único servicio de Correios por tienda, y los tipos de cambio no se actualizan automáticamente.

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 Correios en la ventana Shipping method options. El método funciona igual que en OpenCart 3.

Pedidos

Cuando se realiza un pedido con Correios, la extensión guarda cómo se calculó su precio de envío. La página del pedido en Sales > Orders muestra entonces un bloque Correios con Correios service (por ejemplo PAC — contract (03298)) y Price: Live price (Correios API), Fixed price o Free shipping. El bloque solo se muestra en el panel de administración, no en los correos electrónicos de los clientes, y sigue visible cuando la extensión está desactivada.

En OpenCart 4, la finalización de compra mantiene un solo pedido y lo actualiza cuando el cliente vuelve a confirmar. Los datos de Correios del pedido se actualizan con él, y si el cliente cambia a otro método de envío, el bloque de Correios ya no se muestra para ese pedido.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Correios es el primero de la página Extensions > Extensions > Shipping > VibeFox Correios > Edit, por encima de los ajustes. Pega 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: opencart-shipping-correios y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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. Después de 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 contactar con el servidor de licencias, 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. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Correios no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un 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 está oculto para todos. Después de abrir una vez la página Edit, 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 necesitan 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 por semana. No hace falta una tarea cron. Al desinstalar la extensión siempre se eliminan 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. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso y Minimum order amount. Sin precio en tiempo real, debe existir un precio fijo para el país o para *. Comprueba que los productos tengan Requires Shipping en Yes.

El método muestra un precio fijo en lugar del precio de Correios: revisa el campo Log en la página de la extensión. 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 que supera los límites de tamaño. Comprueba también que el CEP de origen esté configurado, que el CEP del cliente tenga 8 dígitos y, si la moneda predeterminada no es BRL, el tipo de cambio a 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 envío 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 él desactivado.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Así se borran los precios en caché y el token de la API.

La página muestra "Warning: You do not have permission to modify VibeFox Correios!": 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_correios (OpenCart 3) o extension/vfd_correios/shipping/vfd_correios (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: el host de la API de Correios se puede sustituir con el ajuste vfd_crr_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 Correios. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Correios, Sort order, Tax class y Geo zone. Los precios y tokens en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de Correios y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al instalar la extensión de nuevo. Los servicios de Correios guardados con los pedidos siempre se conservan, y los pedidos existentes mantienen 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 la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Correios en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Correios es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Correios.