Integración con Foxpost¶

Foxpost es un transportista de paquetería húngaro conocido sobre todo por su red nacional de máquinas de paquetería (taquillas). El módulo Delivery Foxpost (eyssen_delivery_foxpost) conecta Odoo con la API web de Foxpost: añade un proveedor de envío Foxpost con un modo de máquina de paquetería (APM) y un modo de entrega a domicilio, registra cada paquete y descarga su etiqueta PDF al validar la orden de entrega, mantiene el estado del paquete sincronizado con Foxpost, e incluye un proveedor de pago contra reembolso (COD) dedicado, FoxPost COD, con un límite de 150.000 HUF. En la tienda web, los clientes eligen su máquina de paquetería en el mapa oficial de Foxpost sin salir del proceso de compra.

Para configurar la integración, siga estos pasos:

Obtenga las credenciales de la API de Foxpost.
Configure el/los método(s) de envío en Odoo.
Opcionalmente, habilite el proveedor de pago FoxPost COD.

Ver también

Configuración de la cuenta¶

El conector se comunica con la API web de Foxpost, que requiere tres credenciales emitidas por Foxpost en virtud del contrato de transportista de la empresa: un usuario de API, una contraseña de API y una clave de API. Foxpost opera un sistema de pruebas y un sistema de producción independientes, por lo que conviene solicitar acceso a ambos a Foxpost: el sistema de pruebas permite ensayar el flujo completo (registro de paquetes, etiquetas, seguimiento) sin crear paquetes reales en la red de producción.

Importante

Las credenciales son específicas de cada entorno: utilice cada conjunto solo con el entorno para el que se emitió. El entorno al que llama Odoo se decide por método de envío mediante su botón Entorno (véase más abajo) — compruebe siempre que las credenciales introducidas en el método coincidan con el entorno seleccionado.

Configuración del método de envío¶

Al instalar el módulo se crean dos métodos de envío ya preparados: Foxpost Parcelmachine (modo máquina de paquetería) y Foxpost Home delivery (modo entrega a domicilio). Ambos se instalan sin publicar, con precio cero y credenciales vacías — son plantillas por completar y no métodos operativos.

Para configurarlos (o crear otros adicionales), vaya a Aplicación de Inventario ‣ Configuración ‣ Métodos de entrega y abra el método. Al seleccionar Foxpost en el campo Proveedor aparecen dos pestañas específicas de Foxpost en el formulario: Configuración de Foxpost y Tarifas.

Para conocer los campos comunes a todos los transportistas de terceros, como Producto de entrega o Países, consulte la documentación sobre transportistas de terceros.

Nota

Para que Odoo registre los paquetes y obtenga las etiquetas, mantenga el Nivel de integración en Obtener tarifa y crear envío. Con Obtener tarifa, el método solo calcula los precios en el proceso de compra y nunca contacta con Foxpost en el momento del envío.

screenshot: setup-configuration-foxpost-configuration-tab

menu: Inventory ‣ Configuration ‣ Delivery Methods ‣ Foxpost Parcelmachine
shows: A Foxpost shipping method form with Provider set to "Foxpost" and the "Foxpost Configuration" tab open, showing the API User, API Password and API key fields and the delivery type selection.
highlight: The "Foxpost Configuration" tab (red frame).
data: Shipping method "Foxpost Parcelmachine"; use throw-away credentials.
module: eyssen_delivery_foxpost
notes: English UI, light theme, 1440px width.

Credenciales¶

En la pestaña Configuración de Foxpost, introduzca las tres credenciales obtenidas en la configuración de la cuenta:

Usuario de API y Contraseña de API: el par de autenticación HTTP para la API web de Foxpost.
Clave de API: la clave adicional que Foxpost exige en cada llamada a la API.

Estos campos — junto con el campo Tipo de entrega descrito más abajo — solo son visibles para los usuarios del grupo Administración / Ajustes; el resto de usuarios ven el formulario del método de envío sin ellos.

El botón inteligente Entorno, en la esquina superior derecha del formulario, alterna entre Entorno de pruebas y Entorno de producción. En el modo de pruebas, todas las llamadas se dirigen a la API de pruebas de Foxpost; cambie el método a producción una vez que se haya verificado el flujo de principio a fin.

Tipos de entrega¶

El campo Tipo de entrega de la pestaña Configuración de Foxpost selecciona uno de los dos modos de funcionamiento. Un mismo método de envío siempre funciona exactamente en un modo; para ofrecer ambos, publique dos métodos (que es justo lo que proporcionan los dos registros preinstalados).

Modo	Máquina de paquetería (APM)	Entrega a domicilio
Destino	Una máquina de paquetería de Foxpost elegida por el cliente.	La dirección de envío del cliente.
Selección de máquina de paquetería	Ventana modal con el mapa en el proceso de compra del sitio web; botón Seleccionar en el mapa en el backend.	No aplicable.
Requerido antes de validar la entrega	El identificador de la máquina de paquetería y un número de teléfono del destinatario.	La dirección de envío completa y un número de teléfono del destinatario.
Método preinstalado	Foxpost Parcelmachine	Foxpost Home delivery

El campo Es web (Visible en foxpost.hu o No visible en foxpost.hu) está pensado para controlar si el paquete se marca como visible en foxpost.hu al registrarlo. En la versión actual, todos los paquetes se registran como visibles independientemente de este ajuste, por lo que conviene mantener el valor predeterminado Visible en foxpost.hu.

Nota

El número de teléfono del destinatario es obligatorio para todos los envíos de Foxpost: se utiliza el número de móvil cuando está definido, y en caso contrario el fijo; validar una entrega para un contacto sin ningún número de teléfono falla con un mensaje bloqueante. Foxpost lo utiliza para notificar al cliente sobre el paquete.

Precios¶

La pestaña Tarifas admite dos estrategias de tarificación:

Precio fijo: cuando no se define ninguna regla de tarifa, el precio de envío es el precio de venta del Producto de entrega del método, resuelto a través de la tarifa del pedido. El campo Precio fijo edita el precio de venta base de ese producto, y las reglas de tarifa sobre el producto de entrega lo anulan por cada tarifa.
Reglas por tramos: al añadir una o más Reglas de tarifa el método pasa a una tarificación por tramos según peso, volumen, peso × volumen, precio o cantidad. Las reglas se evalúan en el orden de la secuencia y gana la primera que coincida. Cuando ninguna regla coincide (por ejemplo, el carrito pesa más que el tramo de peso más alto), el método permanece visible en el proceso de compra pero aparece atenuado y no se puede seleccionar — se muestra el mensaje Not available for current order en lugar del precio.

Los precios definidos en la moneda de la empresa se convierten automáticamente a la moneda de la tarifa del pedido, y la opción estándar Gratis si el importe del pedido supera funciona junto con cualquiera de las dos estrategias.

Example

Dos reglas — peso ≤ 2 kg → 990 Ft y peso ≤ 5 kg → 1990 Ft — cobran 990 Ft para un carrito de 1,5 kg y 1990 Ft para un carrito de 4 kg. Un carrito de 10 kg no coincide con ningún tramo, por lo que el método Foxpost aparece atenuado y no se puede seleccionar para ese carrito.

Pago contra reembolso¶

El módulo incluye un proveedor de pago llamado FoxPost COD, con tarjeta de crédito en la máquina de paquetería o en la entrega, que permite al cliente pagar en efectivo o con tarjeta al recoger el paquete. Como cualquier proveedor de pago, se instala deshabilitado: habilítelo y publíquelo en Sitio web ‣ Configuración ‣ Comercio electrónico: Proveedores de pago para ofrecerlo en el proceso de compra.

El proveedor solo aparece en el paso de pago cuando un método de envío Foxpost publicado da servicio al sitio web y el carrito contiene mercancías físicas, y su Importe máximo está preestablecido en 150000 — el conector no admite paquetes contra reembolso por encima de 150.000 HUF — por lo que los pedidos de mayor importe nunca ven esta opción. El mismo límite se aplica una segunda vez en el envío: generar una etiqueta cuyo importe contra reembolso supere el límite se bloquea con el mensaje «Maximum cash on delivery amount is 150.000,- HUF».

Una vez realizado un pedido con pago contra reembolso, el cliente ve el mensaje de confirmación «Your order has been confirmed. Please pay upon delivery.» en lugar de las instrucciones de transferencia bancaria. Este texto es solo de cara al cliente: el pago contra reembolso pendiente no confirma el pedido de venta — confirmarlo (y crear la entrega) sigue siendo un paso de back-office. El importe a cobrar se calcula dinámicamente por cada entrega saliente (transferencia) al generar la etiqueta de envío — un único importe cubre toda la entrega, teniendo en cuenta los envíos parciales, las líneas de servicio y los anticipos.

Ver también

Cómo se calcula el importe contra reembolso por entrega, y el filtrado antifraude opcional de los clientes con pago contra reembolso: Pago contra reembolso (COD)
Cómo se filtran los métodos de pago por método de envío, y la experiencia de compra y confirmación con pago contra reembolso: Métodos de pago según el método de envío

Importante

Ambos métodos Foxpost preinstalados incluyen únicamente el proveedor FoxPost COD en su lista blanca Adquirentes de pago habilitados. De fábrica, un cliente que elija Foxpost solo puede pagar contra reembolso — siempre que no esté habilitado el proveedor COD de ningún otro transportista, ya que los proveedores COD se validan por su propia vía (véase Métodos de pago según el método de envío). Añada los proveedores de tarjeta y transferencia bancaria de la tienda a la pestaña Proveedores de pago de cada método Foxpost para ofrecerlos también.

Proceso de compra del sitio web: elección de una máquina de paquetería¶

Cuando el cliente selecciona un método de máquina de paquetería Foxpost en el paso de entrega del proceso de compra del sitio web, se abre una ventana a pantalla completa titulada Válasszon Foxpost csomagpontot con el mapa oficial apt-finder de Foxpost — el mismo mapa y listado con búsqueda que los clientes conocen de foxpost.hu. Al elegir una máquina se cierra la ventana, se guarda la máquina en el pedido, y la elección se muestra bajo el método de entrega seleccionado como Választott csomagpont: seguido del nombre de la máquina. Al hacer clic de nuevo en el método Foxpost se vuelve a abrir el mapa, de modo que el cliente puede cambiar su elección en cualquier momento antes de realizar el pedido.

Si el método de envío restringe Países, la máquina elegida se valida frente a esa lista: se rechaza una máquina de paquetería situada en un país al que el método no da servicio.

Nota

Cerrar el mapa sin elegir una máquina no bloquea el proceso de compra: el cliente puede completar el pedido igualmente. La falta de máquina de paquetería se detecta más tarde, cuando el almacén valida la entrega: la validación se rechaza con el mensaje «Please select a Foxpost parcel machine (APM ID) on the sales order or transfer before validating the delivery.», y el personal puede elegir la máquina en el pedido o en el albarán en ese momento (véase más abajo).

Nota

Actualmente, los textos de la ventana del mapa se muestran en húngaro independientemente del idioma del sitio web.

Cuando el transportista seleccionado es un método de máquina de paquetería Foxpost, tanto el formulario del pedido de venta como el del albarán muestran un campo Foxpost parcel machine con un botón Select on map. El botón abre el diálogo Select Foxpost parcel machine con el mismo mapa de Foxpost que se usa en el proceso de compra; alternativamente, se puede escribir directamente el identificador de operador de la máquina (por ejemplo, hu472). El pedido y todos sus albaranes comparten una única máquina de paquetería: al editarla en el albarán se actualiza el pedido, y solo se puede establecer en albaranes vinculados a un pedido de venta.

Una vez generada la primera etiqueta de envío para el pedido, el campo y el botón pasan a ser de solo lectura en ambos formularios: cambiar la máquina de destino después de que el paquete exista en el sistema de Foxpost requiere ponerse en contacto con Foxpost.

Etiquetas de envío¶

Cuando se valida una entrega saliente con un método de envío Foxpost, Odoo registra el paquete en Foxpost y descarga su etiqueta de inmediato:

El identificador de paquete devuelto se guarda en el albarán como Foxpost parcel ID y pasa a ser la Tracking Reference del albarán.
La etiqueta en PDF se adjunta al albarán y se publica en su chatter como LabelFoxpost-<parcel id>.pdf, lista para imprimir.
Si Foxpost rechaza el paquete (ID de máquina no válido, datos con formato incorrecto, etc.), la validación se detiene con un mensaje de error comprensible y no se registra nada.

El registro del paquete al validar requiere que el Integration Level del método sea Get Rate and Create Shipment y que la opción Generate Shipping Labels esté activada en el tipo de operación (Inventory app ‣ Configuration ‣ Operations Types); ambos son los valores predeterminados para las operaciones de entrega.

Si falla la descarga de la etiqueta (por ejemplo, un fallo de red tras un registro correcto), el paquete permanece registrado y la etiqueta se puede volver a descargar en cualquier momento con el botón de cabecera Get Foxpost Label del albarán. El botón está disponible siempre que el albarán ya tenga un ID de paquete; las etiquetas se imprimen en tamaño A6.

Nota

Cada albarán viaja como un único paquete Foxpost con un tamaño mediano fijo: las dimensiones y el peso del paquete no se transmiten a Foxpost. Envíe un albarán Foxpost por cada paquete físico y asegúrese de que la mercancía cabe físicamente en un compartimento mediano del casillero.

Seguimiento y estados¶

Una vez registrado un paquete, el albarán muestra su estado en tiempo real de Foxpost: Parcel state (una descripción legible) y Parcel state code (el código de estado de Foxpost). La fecha del último evento de estado también se registra en el albarán, donde impulsa el seguimiento de la fecha de entrega descrito más abajo.

Una acción programada, Picking: Update foxpost tracking information, consulta la API de seguimiento de Foxpost cada 3 horas para todos los albaranes cuyo paquete aún no haya alcanzado un estado final (entregado, devuelto o caducado), de modo que los paquetes abiertos se sigan actualizando sin intervención manual. El intervalo se puede cambiar en Settings ‣ Technical ‣ Automation: Scheduled Actions, y el botón de cabecera Update Foxpost Status del albarán actualiza un único paquete bajo demanda.

Cuando Foxpost informa de que el cliente ha recibido el paquete (lo ha retirado de la máquina o ha aceptado la entrega a domicilio), la fecha del evento se registra en el albarán como la fecha real de recepción del cliente. Esa fecha alimenta el estado de entrega del pedido y el informe de fechas de entrega descrito en Estado y fechas de entrega.

Configuración¶

Lista de comprobación resumida para una configuración de Foxpost funcional:

Instale el módulo Delivery Foxpost (eyssen_delivery_foxpost); las capas compartidas de entrega, pago y estado de entrega se instalan automáticamente como dependencias.
Obtenga de Foxpost las credenciales de API de prueba y producción.
En Inventory app ‣ Configuration ‣ Delivery Methods, abra Foxpost Parcelmachine y/o Foxpost Home delivery (o cree nuevos métodos con el Provider establecido en Foxpost), y luego:
- introduzca el API User, la API Password y la API Key;
- revise el Delivery type y, si es necesario, la restricción de Countries;
- configure la pestaña Pricing (precio fijo o reglas por tramos);
- realice pruebas en el Test Environment y, después, cambie al Production Environment con las credenciales de producción;
- publique el método para que aparezca en el sitio web.
Para ofrecer el pago contra reembolso, active y publique el proveedor de pago FoxPost COD, with credit card at parcelmachine or at delivery en Website ‣ Configuration ‣ eCommerce: Payment Providers.
Añada los demás proveedores de pago de la tienda (tarjeta, transferencia bancaria) a la pestaña Payment Providers de cada método Foxpost, de modo que el pago contra reembolso no sea la única opción (véase Métodos de pago según el método de envío).
Compruebe que el tipo de operación saliente tiene activada la opción Generate Shipping Labels.

Uso¶

El cliente finaliza la compra en el sitio web y selecciona un método Foxpost. Para un método de máquina de paquetería, se abre el mapa de Foxpost y elige su máquina; para la entrega a domicilio, el paquete se envía a su dirección de entrega.
En el paso de pago, paga en línea o, para pedidos de hasta 150 000 HUF, elige FoxPost COD y paga al recoger el paquete.
El pedido de venta se confirma automáticamente en los pagos en línea; para los pedidos con pago contra reembolso, la confirmación sigue siendo un paso de back-office, y el almacén procesa la entrega. Si el cliente omitió la selección de la máquina, el personal elige una con Select on map (o escribiendo el ID) en el pedido o el albarán.
Al validar el albarán se registra el paquete en Foxpost, se guarda el Foxpost parcel ID y se adjunta la etiqueta imprimible al chatter. En los pedidos con pago contra reembolso, se calcula y se envía junto con el paquete el importe a cobrar en esta entrega concreta (véase Pago contra reembolso (COD)).
El cron de seguimiento mantiene actualizado el Parcel state. Cuando el cliente recibe el paquete, se registra la fecha de recepción y el estado de entrega del pedido se actualiza en consecuencia (véase Estado y fechas de entrega).

Alcance y módulos¶

eyssen_delivery_foxpost — el conector del transportista Foxpost: el proveedor de envío Foxpost con los modos de máquina de paquetería (APM) y entrega a domicilio, el selector de máquina de paquetería basado en mapa (en el proceso de compra y en el backend), precios por tramos o fijos, registro de paquetes y etiquetas en PDF, sincronización del seguimiento, y el registro del proveedor de pago FoxPost COD.

El conector se apoya en módulos compartidos de eYssen documentados en sus propias páginas: el filtrado de pagos por transportista y la experiencia de pago contra reembolso en el proceso de compra (Métodos de pago según el método de envío), el importe dinámico de pago contra reembolso por entrega (Pago contra reembolso (COD)), y el seguimiento de la fecha de entrega (Estado y fechas de entrega).