Mirakl no es un marketplace donde vender. Es el software con el que un retailer monta el suyo: Leroy Merlin, Carrefour, Kingfisher, Macy's o Best Buy figuran hoy como clientes en la web de Mirakl. Cuando uno te invita, vendes en el operador —sus categorías, su comisión, su contrato—, pero tu Odoo habla con la API de Mirakl, la misma en todos. Un conector Mirakl bien hecho no es «el conector de Leroy Merlin»: es N marketplaces con una sola API y credenciales distintas. Y lo difícil no es la API: es repartir el stock entre los canales que miran el mismo almacén.
Corrección a nuestra propia web: durante meses tratamos Leroy Merlin y GACD como integraciones sueltas. Son dos cuentas del mismo conector: el mismo código con un host, una clave y un catálogo distintos.
Qué comparten todos los operadores Mirakl y qué no
La API de vendedor de Mirakl tiene un código de operación para cada cosa, el mismo se llame como se llame el operador: OR11 lista pedidos, OR23 y OR24 mandan el tracking y marcan el envío, OR28 reembolsa, OF01 sube ofertas por fichero, IV01 devuelve los documentos de liquidación, M11 es la mensajería con el comprador y SH21 lista los transportistas. Un operador puede tener familias apagadas —los hay sin mensajería ni transportistas, y el conector marca el endpoint como no disponible ante un 404 o un 410—, pero cuando la expone es la misma llamada.
Lo que cambia es todo lo que no es API: el host (adeo-marketplace.mirakl.net en Leroy Merlin), la clave y la tienda, el árbol de categorías y los atributos obligatorios (4.844 categorías y 35.364 atributos en nuestra cuenta de Leroy Merlin), los transportistas admitidos (165 códigos), los motivos de reembolso, la moneda y, sobre todo, el modo de impuestos: unos mandan los precios con IVA incluido (TAX_INCLUDED) y otros sin él (TAX_EXCLUDED). Ese punto nos costó un fallo real: el conector tomaba el precio con IVA como base, Odoo lo sumaba otra vez y 48,86 € entraban como 59,12 €. Verificado sobre los 20 pedidos reales de la cuenta.
Cómo se modela en Odoo: una cuenta por operador
En nuestro conector Mirakl cada operador es una instancia: un registro con su URL base, su URL de API, su clave, su tienda, su compañía, su almacén y su equipo de ventas. Al probar la conexión lee /platform/configuration, /account y /channels y anota qué plataforma responde, qué tienda es y qué funciones expone. En la captura, la plataforma detectada es «Marketplace Adeo» y el proveedor detectado, leroy_merlin.
De la instancia cuelga todo lo del operador: el diccionario de categorías, atributos y valores (único por instancia y código, así que dos operadores nunca se pisan), el mapeo de categorías y transportistas y las reglas de precio y stock. Un producto de Odoo tiene un binding por instancia: el mismo producto, una oferta distinta en cada operador, con su SKU, su precio y su cantidad. Añadir un segundo operador —GACD, cuya API de vendedor responde en tdmp.mirakl.net, o cualquier otro— es una instancia más. Los perfiles del catálogo solo rellenan valores por defecto; el código que habla con Mirakl es uno.
El problema real: repartir el stock
Dos operadores Mirakl, ManoMano, Amazon, Temu o tu web pueden mirar el mismo almacén. Solo los dos primeros son Mirakl: los demás tienen su propia API de vendedor —Amazon, la SP-API— y son conectores aparte. Pero todos venden contra el mismo stock y ninguno sabe de los demás: cada uno recibe la cantidad que le exportas y vende contra ella hasta la siguiente exportación. Eso no se resuelve «en tiempo real», porque ni la API ni el operador funcionan así; se resuelve con reglas por canal. Cada instancia decide cuatro cosas antes de publicar una cantidad:
- Qué cantidad mira: a mano, prevista, libre (descontando lo reservado) o a mano solo en los almacenes de esa instancia.
- Cuánto se guarda: un colchón por instancia que cubre las ventas de otros canales entre dos exportaciones.
- Mínimo para publicar: si tras el colchón quedan menos de N unidades, se publica cero: vender la última unidad en tres sitios es la sobreventa clásica.
- Máximo publicado: un tope por instancia, para no enseñar a un operador un stock ya prometido a otro.
El orden está en el código: cantidad según la estrategia, menos el colchón, cero si no llega al mínimo, recorte al máximo. Con 12 unidades libres, colchón 2, mínimo 3 y máximo 5, cada operador ve 5. Si todos reciben la cantidad a mano sin más, el primero que venda la última unidad deja a los otros vendiendo aire. Colchón y cadencia los tratamos en stock en tiempo real para marketplaces, y cómo se gobierna todo desde un único Odoo, en vender en varios marketplaces y en soluciones.
Pedidos y estados: de Mirakl a Odoo y vuelta
Mirakl tiene más estados de pedido de los que Odoo necesita y los reduce a seis: WAITING_ACCEPTANCE, WAITING_DEBIT, STAGING e INCIDENT_OPEN son «pendiente»; SHIPPING, «en envío» (el comprador ha pagado y corre el plazo para expedir); SHIPPED, «enviado»; RECEIVED y CLOSED, «cerrado»; CANCELED y REFUSED, «cancelado»; REFUNDED, «reembolsado». El pedido de la captura entró como SHIPPED, se mapeó a «Enviado» y quedó enlazado al pedido de venta S00509, con moneda, total e impuesto del payload del operador.
El ciclo de vuelta: el pedido pendiente se acepta con un PUT a /orders/{id}/accept, por tandas con un tope por pasada; al validar el albarán se envía el tracking (OR23) y se marca el envío (OR24), y el albarán queda estampado con petición y respuesta; la factura validada se sube al pedido (OR74) borrando antes la anterior del mismo tipo (OR72, OR76). Y la ventana incremental se pide por fecha de actualización, no de creación: un pedido que cambia de estado semanas después no volvería a entrar nunca.
Dónde se duplica si el conector no es idempotente
Tres sitios. El pedido: la base rechaza dos registros con el mismo identificador en la misma instancia (unique(instance_id, mirakl_order_id)); la importación actualiza el existente. El envío: el conector relee antes el estado; si ya es SHIPPED no lo repite, y si la relectura falla no asume nada y llama, porque dar «ya enviado» por hecho ante un timeout dejaba pedidos sin tracking. Y el reembolso, que es dinero: en la auditoría de la 16.15.1 vimos que el cliente HTTP reintentaba cualquier petición ante 5xx o timeout, también la de OR28. Un timeout no dice que la petición no llegara: dice que no lo sabes. Hoy solo se reintentan lecturas, salvo el 429, que garantiza que no se procesó; y el botón se niega a mandar un segundo reembolso completo si el pedido ya consta reembolsado.
Liquidaciones: qué devuelve la API y por qué merece conciliación propia
Mirakl no te paga pedido a pedido: transfiere periódicamente un neto, e IV01 devuelve el documento que lo explica, con el importe transferido y cuatro cubos: pedidos, comisiones, reembolsos y comisiones devueltas. El conector guarda cada documento por instancia —periodo, moneda, estado de pago— y calcula un neto propio a partir de los cubos. Lo que falta para llegar a lo transferido es «otras tarifas», casi siempre la cuota del operador: una liquidación real arrastraba 39,00 € de descuadre hasta que incorporamos ese residuo, y así queda a la vista como una línea más en vez de esconderse en una diferencia sin nombre.
Cuándo un operador Mirakl no compensa
Que la API sea la misma no significa que cada invitación merezca un sí. El coste de entrar está en el catálogo, no en la integración: mapear tus categorías contra un árbol de miles de nodos y rellenar los atributos obligatorios de cada familia es trabajo de personas, y se repite en cada operador. Pocas categorías afines, una comisión que se come el margen tras la cuota o un plazo de aceptación que tu almacén no cumple: ninguno compensa por fácil que sea conectarlo. La señal sale de la instancia antes de publicar nada: sincroniza el diccionario, mapea diez familias y cuenta cuántos atributos obligatorios te faltan. Si son cientos, te costará más de lo que te venda.
El conector con el que hemos hecho lo anterior está en producción con pedidos reales y en verde —163 de 163 tests— en Odoo 19, 18 y 17, tras la auditoría de la 16.15.1 (121 hallazgos candidatos, 18 confirmados). Si heredas un conector Mirakl de otro, qué mirar está en auditar un conector Odoo heredado; si la plataforma que debe hablar con Odoo es la tuya, eso es un conector Odoo para tu software.
Preguntas frecuentes
¿Entonces vendo «en Mirakl»?
No. Vendes en el operador que te ha invitado: él fija categorías, comisión, plazos y contrato. Mirakl es el software con el que ese operador gestiona su marketplace, y su API la que integra tu Odoo.
¿Necesito un conector por cada operador Mirakl?
No. Necesitas una instancia por operador dentro del mismo conector: host, clave, tienda, diccionario, transportistas y reglas de stock propias. El código que habla con la API es el mismo.
¿Por qué el stock no puede ir «en tiempo real»?
Porque cada operador recibe la cantidad que le exportas y vende contra ella hasta la siguiente exportación, sin saber de los demás. Lo que evita la sobreventa es la regla por canal: qué cantidad se mira, colchón, mínimo y máximo, más una cadencia razonable.
Enlaces útiles dentro de FlexigoTech
Lo que hacemos sobre esto
¿Te ha invitado un operador Mirakl y vendes con Odoo?
Cuéntanos qué operador es, cuántos canales miran ya tu almacén y en qué versión de Odoo estás. Te decimos qué hace falta para conectarlo como una instancia más y qué reglas de stock tendrías que fijar antes de publicar. Escribe a comercial@flexigobe.com o llama al +34 616 809 504.