Integración con MPL¶

MPL es el servicio de paquetería de Magyar Posta, el operador postal húngaro. El módulo eyssen_delivery_mpl conecta un sitio web y un almacén de Odoo directamente con la API v2 de MPL: los clientes eligen entre entrega a domicilio o recogida en un punto de paquetería de MPL (Csomagautomata, PostaPont o Postán maradó) durante el proceso de pago, el almacén imprime etiquetas de envío en PDF A6 directamente desde la orden de entrega, los estados de seguimiento se sincronizan automáticamente con el catálogo de eventos de seguimiento de MPL, y un método de pago contra reembolso (COD) dedicado, MPL COD, transmite el importe a cobrar con cada etiqueta.

Ver también

Configuración de la cuenta¶

El envío con MPL requiere un contrato comercial con Magyar Posta y acceso a la API v2 de MPL. La integración se autentica mediante credenciales de cliente OAuth2, por lo que se deben obtener los siguientes valores de Magyar Posta antes de configurar Odoo:

un par de Client ID / Client Secret para el entorno de prueba (sandbox);
un par de Client ID / Client Secret para el entorno de producción;
el código de contabilidad del cliente (Vevőkód), enviado con las solicitudes a la API de envíos y de puntos de paquetería;
el número de acuerdo de ocho caracteres (Megállapodásszám) del contrato con Magyar Posta.

Truco

Empiece con las credenciales de prueba y el interruptor Entorno configurado en Prueba. El módulo entonces se comunica con el sandbox de Magyar Posta, de forma que las etiquetas y los envíos creados durante las pruebas nunca llegan a la red real de MPL. Cambie el transportista a Producción solo cuando el flujo se haya verificado de principio a fin.

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

El módulo incluye dos métodos de envío preconfigurados: MPL Punto de paquetería (recogida en un punto de paquetería) y MPL Entrega a domicilio. Para revisar o crear uno, vaya a Inventario ‣ Configuración ‣ Métodos de envío y configure el campo Proveedor en MPL. Al hacerlo aparecen dos pestañas adicionales en el formulario: la pestaña Configuración de MPL y la pestaña Tarifas.

Para conocer los campos genéricos que comparten todos los transportistas — como Producto de entrega, la disponibilidad por Países o el umbral de envío gratuito — consulte Conectores de transportistas.

Nota

Para generar etiquetas de envío de MPL al validar una orden de entrega, configure la opción Nivel de integración en Obtener tarifas y crear envíos. Las etiquetas también se pueden crear manualmente en cualquier momento con el botón Imprimir etiqueta MPL en el traslado.

screenshot: setup-configuration-mpl-configuration-tab

menu: Inventory ‣ Configuration ‣ Delivery Methods ‣ MPL Home delivery
shows: An MPL shipping method form with Provider set to "MPL" and the "MPL Configuration" tab open, showing the Test and Production Client ID/Secret pairs, the Accounting Code and the Agreement Number.
highlight: The "MPL Configuration" tab (red frame).
data: Shipping method "MPL Home delivery"; use throw-away credentials.
module: eyssen_delivery_mpl
notes: English UI, light theme, 1440px width.

Credenciales¶

Los campos de la pestaña Configuración de MPL solo son visibles para los usuarios con permisos de Administración: Ajustes:

ID de cliente de prueba / Secreto de cliente de prueba: el par de credenciales del sandbox, utilizado mientras el Entorno del transportista esté configurado en Prueba.
ID de cliente de producción / Secreto de cliente de producción: el par de credenciales reales, utilizado en Producción. Los secretos aparecen ocultos en pantalla.
Código de contabilidad (Vevőkód): el código de contabilidad del cliente de Magyar Posta, transmitido como encabezado en los registros de envío y en las consultas al catálogo de puntos de paquetería.
Número de acuerdo (Megállapodásszám): el número de contrato de ocho caracteres, transmitido como el acuerdo del remitente en cada envío.

Si se crea una etiqueta, o se activa una sincronización manualmente, sin credenciales para el entorno activo, la operación se detiene con un mensaje de error explícito. La sincronización programada del catálogo registra el fallo y vuelve a intentarlo en su siguiente ejecución.

Tipos de entrega¶

El campo Tipo de entrega en la pestaña Configuración de MPL determina el comportamiento del transportista:

	Entrega a domicilio	Parcel Shop
Destino	La dirección de entrega del cliente.	Un punto de paquetería de MPL elegido por el cliente.
Proceso de pago	Se comporta como cualquier otro transportista.	Abre el selector de puntos de paquetería; el pedido no se puede confirmar hasta que se elija un punto.
Etiqueta	Se registra como un envío a domicilio.	Se registra para recogida en el punto seleccionado, utilizando el tipo de servicio de ese punto.

Un punto de paquetería es uno de los tres tipos de puntos de servicio de MPL, todos disponibles juntos en el selector:

Csomagautomata (taquilla de paquetería) — una taquilla automatizada, normalmente disponible las 24 horas;
Postán maradó (retención en oficina postal) — el paquete se retiene para su recogida en una oficina de correos;
PostaPont — un punto de recogida atendido por personal, generalmente operado por los socios comerciales de Magyar Posta.

El tipo de punto que elige el cliente se guarda en el pedido de venta junto con el identificador y el nombre del punto, y se transmite a MPL al crear la etiqueta.

La opción Crear dirección de entrega para PS (desactivada de forma predeterminada, solo para transportistas de punto de paquetería) hace que el sitio web cree una dirección de entrega independiente bajo el cliente para el punto de paquetería elegido y la establezca como la dirección de envío del pedido. Cuando el cliente cambia después a otro método de entrega, la dirección de envío vuelve a ser la del cliente y la dirección temporal del punto de paquetería se elimina automáticamente.

Precios¶

La pestaña Tarifas añadida por el módulo admite dos modos de tarificación:

Tarificación por rangos: agregue una o más Reglas de tarifas (por peso, volumen, precio o cantidad). Las reglas se evalúan en orden y la primera regla que coincide establece el precio de envío; si ninguna regla coincide, el método sigue apareciendo en el proceso de pago pero no se puede seleccionar — Odoo muestra No disponible para el pedido actual.
Alternativa fija: cuando no se define ninguna regla de tarifas, el precio de envío es el precio de venta del Producto de entrega del método, resuelto mediante la tarifa del pedido; el campo Precio fijo edita el precio de venta base de ese producto, y las reglas de tarifa en el producto de entrega lo anulan según la tarifa.

La mecánica estándar del transportista — el umbral de envío gratuito, los márgenes y los impuestos — se aplica sobre ambos modos, exactamente igual que con cualquier otro método de envío.

Nota

Seleccionar cualquier método de MPL en el proceso de pago también agrega una línea de producto Servicio de manipulación al pedido (precio de venta predeterminado: 2000 en la moneda de la empresa, es decir, 2000 HUF en una base de datos húngara, calculado mediante la tarifa del pedido). La línea se elimina automáticamente cuando el cliente cambia a un método que no sea de MPL. Para desactivar este recargo, configure el precio de venta del producto Servicio de manipulación en 0.

Pago contra reembolso¶

El módulo incluye un proveedor de pago llamado MPL COD, con tarjeta de crédito en el punto de paquetería o en la entrega. Como cualquier proveedor, debe habilitarse y publicarse antes de que aparezca en el proceso de pago, y solo se ofrece cuando el sitio web tiene un método de envío de MPL publicado y el carrito contiene productos físicos.

El importe a cobrar se calcula por cada entrega saliente (traslado) — los envíos parciales, las líneas de servicio y los anticipos facturados se gestionan todos mediante el cálculo compartido descrito en Pago contra reembolso (COD), y el resultado se guarda en el campo Importe COD del traslado.
El importe se transmite como un número entero: los pedidos en HUF se envían tal cual; los pedidos en otra moneda se convierten a HUF al tipo de cambio actual al crear la etiqueta, y el código de moneda del pedido se transmite junto con el importe. Verifique con Magyar Posta los pedidos COD en moneda extranjera antes de confiar en esto.
El campo Cuenta bancaria COD en la pestaña Configuración de MPL se envía como la cuenta de pago de los importes cobrados.
Qué métodos de pago se ofrecen junto con cada método de envío de MPL — y la experiencia de pago específica de contra reembolso — se controla mediante el filtrado de pagos por transportista descrito en Métodos de pago según el método de envío. De forma predeterminada, los transportistas de MPL incluidos solo permiten su propio proveedor de contra reembolso — siempre que no esté habilitado el proveedor de contra reembolso de otro transportista, ya que los proveedores de contra reembolso se validan en su propio proceso (consulte Métodos de pago según el método de envío) — así que agregue los proveedores de tarjeta o transferencia bancaria de la tienda a los transportistas para ofrecer una opción.

Importante

Cuando un envío contra reembolso se divide en varios paquetes, la integración actual transmite el importe completo del contra reembolso con cada paquete. Envíe los pedidos con contra reembolso como un solo paquete, o verifique con Magyar Posta cómo se cobran los envíos contra reembolso de varios paquetes, para evitar cobrar de más al cliente.

Validación del número de teléfono¶

MPL requiere un número de teléfono móvil o fijo húngaro válido para cada envío. Al crear una etiqueta, el módulo toma el número de Móvil de la dirección de entrega, después su número de Teléfono y, si no los encuentra, recurre al contacto principal, y normaliza el resultado al formato internacional +36 (los números introducidos con el prefijo nacional 06 se convierten automáticamente). Si no se encuentra ningún número, o el número no es húngaro, la creación de la etiqueta se detiene con un error bloqueante — en este aspecto la integración es exclusivamente nacional.

Catálogo de puntos de paquetería¶

El selector del sitio web no consulta a Magyar Posta en cada vista de página. En su lugar, el módulo mantiene un catálogo local de todos los puntos de paquetería de MPL (nombre, dirección, coordenadas y tipo de punto de servicio), actualizado por la acción programada diaria MPL: sincronizar lugares de entrega:

la lista completa de ubicaciones de Csomagautomata, Postán maradó y PostaPont se descarga desde la API de MPL, utilizando las credenciales de un método de envío de MPL configurado;
las entradas existentes se actualizan en su lugar, se agregan las nuevas y se eliminan los puntos que ya no existen en Magyar Posta;
cada entrada registra la última vez que se sincronizó.

Un pedido que ya tiene guardado un punto elegido sigue funcionando incluso si ese punto desaparece más tarde del catálogo — el identificador y el nombre del punto se copian en el pedido en el momento de la selección.

Truco

Justo después de la instalación, el catálogo está vacío hasta que la acción programada se ejecuta por primera vez. El selector del backend ayuda en este estado: buscar por código postal o ciudad obtiene los puntos coincidentes en tiempo real desde la API de MPL y los guarda localmente.

Proceso de pago del sitio web: elegir un punto de paquetería¶

Cuando un cliente selecciona un método de envío de punto de paquetería de MPL en el proceso de pago, se abre inmediatamente un selector a pantalla completa, y el proceso de pago no puede continuar hasta que se elija un punto — hasta entonces se muestra una advertencia debajo del método de envío. El punto seleccionado se muestra debajo del método, se guarda en el pedido y se restaura automáticamente cuando el cliente vuelve al proceso de pago más tarde.

El selector tiene dos modos, determinados por la configuración del sitio web:

	Widget de mapa	Lista con opción de búsqueda
Requisito	Clave de API de Google Maps configurada en los ajustes del sitio web	ninguno (predeterminado)
Interfaz	El widget de mapa oficial PostaPont de Magyar Posta sobre un mapa de Google	Lista integrada con filtros por tipo (Csomagautomata / Postán maradó / PostaPont), búsqueda de texto y paginación
Origen de los datos	Se carga en tiempo real desde Magyar Posta	El catálogo local de puntos de paquetería
Tipo de punto de servicio	No lo proporciona el widget — los envíos se registran con el modo de entrega genérico PostaPont	Se guarda con la selección y se transmite a MPL

Para activar el modo de mapa, vaya a Sitio web ‣ Configuración ‣ Ajustes, busque el bloque MPL e introduzca una Clave de API de Google Maps. Deje la clave vacía para usar la lista con opción de búsqueda, que no necesita ningún servicio externo aparte de la sincronización diaria del catálogo.

Los usuarios de administración pueden elegir o cambiar el punto sin usar el sitio web: tanto el pedido de venta como el traslado muestran un campo Punto de paquetería MPL con un botón Seleccionar en el mapa que abre el cuadro de diálogo Seleccionar punto de paquetería MPL — una lista con opción de búsqueda con filtros Taquilla de paquetería, Retención en oficina postal y PostaPont. El campo se bloquea en cuanto el envío se registra con MPL o el pedido se completa o se cancela.

Etiquetas de envío¶

Las etiquetas se generan en formato PDF A6, listas para impresoras de etiquetas:

Con el Nivel de integración configurado en Obtener tarifas y crear envíos, al validar la orden de entrega se registra el envío con MPL automáticamente.
El botón Imprimir etiqueta MPL en el traslado crea el envío manualmente en cualquier momento; desaparece en cuanto existe una etiqueta.
Si tiene éxito, el traslado guarda el ID de paquete MPL, el Número de paquete MPL (cuando el envío se registra al validar el traslado, el número también se copia en la referencia de seguimiento estándar; el botón manual Imprimir etiqueta MPL solo rellena los campos de MPL) y la Etiqueta MPL descargable, y el PDF de la etiqueta se adjunta al chatter del traslado junto con el número de seguimiento.

Cuando los productos se empaquetan en varios paquetes, se registra un paquete por cada bulto, y el peso de envío de cada paquete se transmite individualmente (los pesos se envían en gramos, con un mínimo de 100 g y un valor predeterminado de 1 kg cuando no se ha configurado ningún peso). Cuando MPL devuelve números de seguimiento por paquete, cada registro de paquete guarda su propio número para poder rastrear los bultos uno por uno; en caso contrario, los paquetes comparten el número de seguimiento del envío.

Importante

Imprimir etiqueta MPL no es un botón para reimprimir. Al presionarlo se borran los datos de paquete guardados y se registra un envío nuevo con MPL. Por esta razón se oculta en cuanto existe una etiqueta; volver a registrar un envío solo se ofrece a los usuarios con el modo de desarrollador activado. Para reimprimir una etiqueta existente, descargue el archivo Etiqueta MPL guardado o el archivo adjunto del chatter.

Nota

La dirección del remitente transmitida a MPL siempre es la dirección de la empresa, no la dirección del almacén. Los comercios que envían desde varios almacenes aparecen ante MPL bajo la dirección registrada de la empresa.

Seguimiento y estados¶

El módulo incluye el catálogo de eventos de seguimiento de MPL — 46 estados repartidos entre las fases de recogida, procesamiento, transporte y entrega — como registros editables en Inventario ‣ Configuración ‣ Estados de entrega MPL, cada uno con un Código de estado, Categoría de estado, Nombre de estado MPL y una casilla Estado entregado.

Los estados se actualizan automáticamente mediante dos acciones programadas, cada una ejecutándose cada tres horas:

Traslado: actualizar información de seguimiento de MPL consulta todos los traslados que tienen un número de paquete MPL y que aún no están completados ni cancelados;
Paquete: actualizar información de seguimiento de MPL consulta paquetes individuales, hasta 50 por ejecución, espaciando las comprobaciones repetidas del mismo paquete según el Intervalo de comprobación de seguimiento configurado (predeterminado: 60 minutos).

El estado más reciente, su código y su marca de tiempo se muestran en el traslado (Estado del paquete, Código de estado del paquete, Fecha de estado del paquete) y en cada paquete; el traslado también tiene un botón Actualizar estado MPL para una actualización bajo demanda.

Dos automatizaciones se basan en el catálogo de estados:

Fecha de entrega: cuando un evento de seguimiento se asigna a un estado cuya casilla Estado entregado está marcada, la fecha en la que el cliente recibió realmente la mercancía se registra en el traslado (la fecha real de recepción por el cliente), utilizando la marca de tiempo de entrega informada por MPL. Esto alimenta el progreso de entrega a nivel de pedido descrito en Estado y fechas de entrega.
Validación automática: en el tipo de operación (Inventario ‣ Configuración ‣ Tipos de operación), el grupo Validación en la entrega MPL ofrece Validar picking en la entrega junto con una lista Validar en los estados MPL. En cuanto todos los paquetes de un traslado alcanzan uno de los estados seleccionados, el traslado se valida automáticamente. Esto permite un flujo de validación diferida: deje la orden de entrega abierta después de imprimir la etiqueta, deje que las acciones programadas sigan el paquete, y haga que Odoo cierre el traslado cuando MPL informe la entrega.

Advertencia

Al usar el flujo de validación diferida, configure el Nivel de integración del método de envío en Obtener tarifa (o desmarque Generar etiquetas de envío en el tipo de operación). Con Obtener tarifas y crear envíos, la validación automática registra el envío con MPL por segunda vez, porque el botón Imprimir etiqueta MPL no rellena la referencia de seguimiento estándar que suprime el registro en el momento de la validación.

Importante

Ninguno de los 46 estados incluidos está marcado previamente como entregado. Marque Estado entregado en las filas terminales de Kézbesített (entregado) después de la instalación — de lo contrario, ni el registro de la fecha de entrega ni una configuración de validación automática basada en la entrega tendrán ningún efecto.

Nota

La acción programada a nivel de traslado omite deliberadamente los traslados que ya están completados. Si las entregas se validan de inmediato en el momento del envío, el seguimiento solo se sigue actualizando a través de la acción a nivel de paquete y el botón manual Actualizar estado MPL.

Configuración¶

Lista de comprobación para poner MPL en producción:

Instale eyssen_delivery_mpl.
En cada método de envío de MPL (Inventario ‣ Configuración ‣ Métodos de envío), complete la pestaña Configuración de MPL: las credenciales del Entorno elegido, el Código de contabilidad (Vevőkód), el Número de acuerdo (Megállapodásszám) y — para contra reembolso — la Cuenta bancaria COD.
Elija el Tipo de entrega de cada método, configure la pestaña Tarifas y publique los métodos en el sitio web.
Habilite y publique el proveedor de pago MPL COD, con tarjeta de crédito en el punto de paquetería o en la entrega, y revise los proveedores de pago habilitados de cada transportista (consulte Métodos de pago según el método de envío).
En Sitio web ‣ Configuración ‣ Ajustes, bloque MPL: configure opcionalmente una Clave de API de Google Maps para el selector de mapa, y ajuste el Intervalo de comprobación de seguimiento si es necesario.
En Inventario ‣ Configuración ‣ Estados de entrega MPL, marque Estado entregado en las filas entregadas.
Opcionalmente, configure la validación automática en el tipo de operación de salida (Validar picking en la entrega + Validar en los estados MPL).
Configure el precio de venta del producto Servicio de manipulación (0 desactiva el recargo en el proceso de pago).
Deje que la acción programada diaria MPL: sincronizar lugares de entrega rellene el catálogo de puntos de paquetería, o active una búsqueda inicial por código postal desde el selector del backend.

Uso¶

Un cliente finaliza la compra en el sitio web y elige un método de envío de MPL. Para un método de punto de paquetería, se abre el selector y el cliente elige una ubicación Csomagautomata, Postán maradó o PostaPont; el proceso de pago se bloquea hasta que se selecciona un punto.
El cliente paga — con el método MPL COD, o con cualquier otro proveedor habilitado para el transportista — y el punto de paquetería elegido se guarda en el pedido de venta.
El almacén procesa la orden de entrega. Al validarla (o al presionar Imprimir etiqueta MPL) se registra el envío con MPL, se calcula el importe COD cuando corresponde, y se adjunta la etiqueta en PDF A6 — con números de seguimiento por paquete cuando MPL los proporciona.
Las acciones programadas siguen el paquete a través de los estados de seguimiento de MPL. Cuando se alcanza un estado marcado como Estado entregado, se registra la fecha de recepción del cliente y — si está configurado en el tipo de operación — el traslado se valida automáticamente.

Alcance y módulos¶

eyssen_delivery_mpl — el conector del transportista MPL: el tipo de método de envío MPL con las variantes de entrega a domicilio y de punto de paquetería, el catálogo y los selectores de puntos de paquetería, la generación de etiquetas en PDF A6, la sincronización de seguimiento con validación automática y el proveedor de pago MPL COD.

El cálculo del importe COD, el filtrado de pagos por transportista y los campos de estado de entrega a los que se conecta el conector son bloques compartidos documentados en Pago contra reembolso (COD), Métodos de pago según el método de envío y Estado y fechas de entrega.