VibeFox Delhivery 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.

Token de API de Delhivery (solo para tarifas en tiempo real): inicia sesión en Delhivery One y abre Settings > API setup. El artículo de ayuda de Delhivery "API token generation" explica los pasos. Ambos enlaces están en la página de la extensión. Los tokens de prueba funcionan con el entorno de staging. También necesitas el código pincode de 6 dígitos de tu punto de recogida. Si solo usas precios fijos, no necesitas token.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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_delhivery-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_delhivery.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 la administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_delhivery-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Delhivery y haz clic en Install (el botón verde +).

3. Haz clic en Edit (el botón con lápiz) para abrir la página de configuración.

4. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Edit, y haz clic en Activate (ver Clave de licencia).

5. Introduce el token de API y tu código pincode de origen, elige Express o Surface y Pre-paid o COD. Si la moneda predeterminada de tu tienda no es INR, introduce el tipo de cambio. Opcionalmente, introduce precios fijos (ver Configuración). Activa Enable Delhivery y haz clic en Save.

OpenCart 4

1. En la administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_delhivery.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 y elige el tipo de extensión Shipping. Busca VibeFox Delhivery, haz clic en Install (el botón verde +) y después en Edit (el botón con 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 los mismos en ambas versiones.

Tras la instalación, el método está desactivado hasta que actives Enable Delhivery y guardes. Si vuelves a instalar la extensión después de desinstalarla, se vuelven a usar los ajustes de Delhivery que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. Las secciones aparecen a la izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas de Delhivery en caché. Los importes aceptan "9.99" y "9,99". Si un valor es incorrecto, no se guarda nada y la página muestra el motivo, por ejemplo Enter a valid method title (without < > ; = # { })., un mensaje de que un campo debe ser un número no negativo, o Sort order must be a whole number. Solo los usuarios de administración con el permiso de modificación para esta extensión pueden guardar los ajustes.

Si la moneda predeterminada de tu tienda no es INR, hay un token de API guardado y no se ha definido un tipo de cambio, un aviso en la parte superior de la página te recuerda que las tarifas en tiempo real no se usan hasta que introduzcas el tipo de cambio. Si la tienda no tiene una clase de peso en kilogramos y su unidad de peso no es una estándar (kg, g, lb u oz), un aviso indica que los pesos de los productos se leen como kilogramos. Define una unidad estándar en System > Localisation > Weight Classes.

General

Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método en Availability.

Enable Delhivery: ofrece Delhivery en la finalización de compra. Predeterminado: 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. Predeterminado: Delhivery. Obligatorio, como máximo 64 caracteres, sin los caracteres < > ; = # { }.

Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Con una clase, OpenCart añade el impuesto sobre el coste de envío.

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

Cuenta de API de Delhivery (necesaria solo para tarifas en tiempo real)

Environment: Production (track.delhivery.com) (predeterminado) o Staging / test account (staging-express.delhivery.com). Usa Staging solo con un token de prueba de Delhivery.

API token: tu token de API de Delhivery. Solo se envía en la cabecera de autorización y nunca se escribe en los registros. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.

Remove saved token: actívalo y guarda para eliminar el token guardado. Entonces solo se usan los precios fijos.

Origin pincode: el código pincode de 6 dígitos de tu punto de recogida o almacén, por ejemplo 110001. Si no tiene 6 dígitos, los ajustes se guardan con el aviso The origin pincode must have 6 digits — live rates are not requested until it is fixed.

Tarifas en tiempo real

Se solicita una tarifa en tiempo real para destinos de la India con un código pincode válido de 6 dígitos, para un envío directo (entregado).

Shipping mode: el modo de facturación de Delhivery usado para la tarifa: Express (predeterminado) o Surface.

Payment type: el tipo de pago enviado a Delhivery: Pre-paid (predeterminado) o COD (cash on delivery — Delhivery adds its COD charge). La extensión no lo cambia según el método de pago que elija el cliente.

Rate amount: Delhivery devuelve el cargo con y sin GST.

INR to (store currency) conversion rate: la etiqueta muestra la moneda predeterminada de tu tienda. Las tarifas de Delhivery están en rupias indias. Si tu moneda predeterminada no es INR, indica cuántas unidades de tu moneda vale una rupia, por ejemplo 0.011. El tipo de cambio debe ser mayor que 0. Si lo dejas vacío, no se usan las tarifas en tiempo real y se aplican los precios fijos. No es necesario si tu moneda predeterminada es INR.

Precios fijos (se usan cuando no hay tarifa en tiempo real)

Los precios fijos se usan cuando todavía no hay token o código pincode, el destino está fuera de la India, el código pincode no tiene servicio o la API devuelve un error. Están en la moneda predeterminada de tu tienda, sin impuestos.

Prices per country: uno por línea con el formato COUNTRY_CODE:precio, por ejemplo IN:120. Se comprueba antes que el precio de reserva. Las líneas con otro formato se eliminan al guardar, y un aviso las enumera.

Fallback price: se usa cuando no se aplica ni una tarifa en tiempo real ni un precio por país. Déjalo vacío para ocultar el método (predeterminado). 0 significa gratis.

Fixed price is charged: Per order (predeterminado) cobra el precio una vez. Per item (price × quantity) lo multiplica por el número de artículos del carrito. Una tarifa en tiempo real de Delhivery siempre es para el peso total del paquete.

Condiciones

Free shipping from: el envío es gratuito si el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) es al menos este importe. No se envía ninguna solicitud a Delhivery. Déjalo vacío para desactivarlo.

Show from subtotal: muestra el método solo si este subtotal es al menos este importe. Déjalo vacío para mostrarlo siempre.

Min weight (kg): el peso mínimo del carrito para mostrar el método. 0 significa sin límite (predeterminado).

Max weight (kg): oculta el método si el carrito es más pesado. Predeterminado: 30. 0 significa sin límite; un campo vacío significa 30 kg. Min weight no puede ser mayor que Max weight: la página muestra un error y no se guarda nada.

Los pesos de los productos se convierten a kg desde su clase de peso de OpenCart. La tarifa usa el peso real del carrito (la suma de los pesos de los productos), sin peso volumétrico ni cajas.

Disponibilidad

Geo zone: ofrece Delhivery solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se comprueba cuando Ignore zones está activado.

Ignore zones: si está activado, no se comprueba la zona geográfica y el método se ofrece para los países de abajo (todos los países si la lista está vacía).

Countries: los países de destino para ese modo. Se usa solo cuando Ignore zones está activado.

Avanzado

Debug log: escribe los cálculos de tarifas en storage/logs/vfd_dlv_debug.log.php (en OpenCart 4, system/storage/logs/vfd_dlv_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, incluso cuando esto está desactivado. Los tokens y los códigos pincode completos de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_dlv_debug.old.log.php y se inicia un registro nuevo.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de Delhivery, las tarifas en caché y el registro. Si está desactivado (predeterminado), se conservan para una nueva instalación. Los datos de los pedidos (modo, origen del precio, números de AWB) nunca se eliminan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. El token de API no se exporta.

Import: pega el 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 token de API guardado no se modifica.

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 Delhivery. Si hay una Geo zone definida (y Ignore zones está desactivado) y la dirección está fuera de ella, Delhivery no se ofrece. Solo cuentan los productos con Requires Shipping configurado como Yes: los demás no suman peso ni se incluyen en el subtotal. Después, la extensión comprueba los países (si Ignore zones está activado), el peso del carrito y Show from subtotal. El subtotal es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. Los certificados regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Delhivery.

Para una dirección india con un código pincode válido de 6 dígitos (el código postal de la dirección), la extensión envía a Delhivery los códigos pincode de origen y destino, el peso del carrito en gramos, el modo de envío y el tipo de pago. El importe devuelto se convierte de INR a 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 respuesta se guarda en caché durante 1 hora. Una solicitud fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a Delhivery en cada actualización. El tiempo de espera de la API es de 10 segundos.

Si no hay tarifa en tiempo real, se usa el precio del país o el precio de reserva. Si no hay ninguno de los dos, el método se oculta. El cliente nunca ve un error de la API. El motivo se escribe en el registro.

La extensión calcula las tarifas y da a los clientes un enlace de seguimiento. No crea envíos ni albaranes, no imprime etiquetas, no solicita recogidas ni manifiestos, no comprueba la cobertura de códigos pincode, no estima fechas de entrega, no sincroniza los estados de seguimiento ni cotiza tarifas internacionales de Delhivery. Fuera de la India solo se usan los precios fijos.

En OpenCart 4, el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige Delhivery en la ventana Shipping method options. El método funciona igual que en OpenCart 3.

Pedidos y seguimiento

Cuando se realiza un pedido con Delhivery, la extensión guarda con el pedido el modo de envío y el origen del precio. Abre el pedido en Sales > Orders: el panel Delhivery encima del historial del pedido muestra Mode: (Express o Surface), Price: (tarifa en tiempo real de Delhivery, precio fijo o umbral de envío gratuito) y el Delhivery AWB / tracking number, o Not entered yet.

En OpenCart 4, la finalización de compra mantiene un único pedido y lo actualiza cada vez que el cliente vuelve a confirmar. El modo y el origen del precio se actualizan con él. Si el cliente cambia a otro método de envío antes de introducir un AWB, el panel de Delhivery ya no se muestra para ese pedido.

Crea el envío en Delhivery One, luego introduce su AWB en el panel y haz clic en Save. La página no se recarga. Se mantienen las letras, los dígitos y los guiones (hasta 64 caracteres). Guarda un campo vacío para eliminar el AWB. Con un AWB, el panel muestra un enlace Track on delhivery.com. Guardar el AWB requiere el permiso para modificar pedidos. Sin él, el panel es de solo lectura.

Un cliente registrado ve Delhivery tracking: con el AWB como enlace a la página de seguimiento de Delhivery, en la página de pedido de su cuenta. Cuando añades una entrada al historial del pedido y notificas al cliente, el correo de estado del pedido recibe la misma línea con el enlace. El correo de nuevo pedido no tiene enlace de seguimiento, porque el AWB se introduce más tarde. El panel y el enlace de seguimiento también funcionan en pedidos anteriores aunque la extensión esté desactivada.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Delhivery es el primer bloque de Extensions > Extensions > Shipping > VibeFox Delhivery > Edit, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-delhivery y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios de administración con el permiso de modificación para esta extensión pueden cambiar la clave. Los textos del bloque siguen el idioma de la 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. 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 contactar con el servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: la dirección de la tienda que figura en la configuración de OpenCart. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Delhivery no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario de administración que tenga la sesión iniciada en la administración 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 de la administración, así que sin una clave activa el método se oculta a todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard de la administración. 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 requieren una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard de la administración o la página Edit: 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. Al desinstalar la extensión, siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Delhivery no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Delhivery esté activado. Revisa Geo zone, o Ignore zones y Countries, los límites de peso y Show from subtotal. Sin tarifa en tiempo real, hace falta un precio por país o un Fallback price. Comprueba que los productos tengan Requires Shipping configurado como Yes.

Las tarifas en tiempo real no aparecen: comprueba el token de API, un Origin pincode válido y, si tu moneda predeterminada no es INR, el tipo de cambio. El cliente debe introducir como código postal un código pincode indio válido de 6 dígitos. Activa el Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Muestra el motivo, por ejemplo un código pincode sin servicio o un error HTTP de Delhivery.

GST se cobra dos veces: el importe total de Delhivery ya incluye GST. Configura Rate amount como Gross amount (excluding GST) o Tax class como No tax.

Pruebas: configura Environment como Staging y usa un token de prueba de Delhivery.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas de Delhivery en caché.

No se puede guardar el AWB: el mensaje You do not have permission to modify orders. significa que tu grupo de usuarios de administración necesita el permiso de modificación para sale/order en System > Users > User Groups.

La página dice "Warning: You do not have permission to modify VibeFox Delhivery!": es posible que tu grupo de usuarios de administración solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_delhivery (OpenCart 3) o extension/vfd_delhivery/shipping/vfd_delhivery (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: la extensión dispara los eventos de OpenCart catalog/vfd_delhivery/api_url y catalog/vfd_delhivery/api_timeout, que pueden cambiar la dirección de la API y el tiempo de espera.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Delhivery. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Delhivery, Sort order, Tax class y Geo zone. Las tarifas en caché y los eventos de la extensión siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes de Delhivery y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensión. Los datos de Delhivery de los pedidos (modo, origen del precio y números de AWB) nunca se eliminan. Los pedidos existentes conservan su método de envío y su coste.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox Delhivery en la lista de extensiones instaladas y, después, en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.

Delhivery es una marca comercial de su titular. Esta extensión no está afiliada a Delhivery ni cuenta con su respaldo.