Español
English
Deutsch
Français
Português
Italiano
Nederlands
Polski
Mirakl no és un marketplace on vendre. És el programari amb què un retailer munta el seu: Leroy Merlin, Carrefour, Kingfisher, Macy's o Best Buy figuren avui com a clients al web de Mirakl. Quan un et convida, vens a l'operador (les seves categories, la seva comissió, el seu contracte), però el teu Odoo parla amb l'API de Mirakl, la mateixa a tots. Un connector Mirakl ben fet no és «el connector de Leroy Merlin»: és N marketplaces amb una sola API i credencials diferents. I el difícil no és l'API: és repartir l'estoc entre els canals que miren el mateix magatzem.
Correcció al nostre propi web: durant mesos vam tractar Leroy Merlin i GACD com a integracions soltes. Són dos comptes del mateix connector: el mateix codi amb un host, una clau i un catàleg diferents.
Què comparteixen tots els operadors Mirakl i què no
L'API de venedor de Mirakl té un codi d'operació per a cada cosa, el mateix es digui com es digui l'operador: OR11 llista comandes, OR23 i OR24 envien el seguiment i marquen l'enviament, OR28 reemborsa, OF01 puja ofertes per fitxer, IV01 retorna els documents de liquidació, M11 és la missatgeria amb el comprador i SH21 llista els transportistes. Un operador pot tenir famílies apagades (n'hi ha sense missatgeria ni transportistes, i el connector marca l'endpoint com a no disponible davant d'un 404 o un 410), però quan l'exposa és la mateixa crida.
El que canvia és tot allò que no és API: el host (adeo-marketplace.mirakl.net a Leroy Merlin), la clau i la botiga, l'arbre de categories i els atributs obligatoris (4.844 categories i 35.364 atributs al nostre compte de Leroy Merlin), els transportistes admesos (165 codis), els motius de reemborsament, la moneda i, sobretot, el mode d'impostos: uns envien els preus amb IVA inclòs (TAX_INCLUDED) i altres sense (TAX_EXCLUDED). Aquest punt ens va costar un error real: el connector prenia el preu amb IVA com a base, Odoo el sumava una altra vegada i 48,86 € entraven com a 59,12 €. Verificat sobre les 20 comandes reals del compte.
Com es modela a Odoo: un compte per operador
Al nostre connector Mirakl cada operador és una instància: un registre amb la seva URL base, la seva URL d'API, la seva clau, la seva botiga, la seva companyia, el seu magatzem i el seu equip de vendes. En provar la connexió llegeix /platform/configuration, /account i /channels i anota quina plataforma respon, quina botiga és i quines funcions exposa. A la captura, la plataforma detectada és «Marketplace Adeo» i el proveïdor detectat, leroy_merlin.
De la instància penja tot el de l'operador: el diccionari de categories, atributs i valors (únic per instància i codi, així que dos operadors mai es trepitgen), el mapatge de categories i transportistes i les regles de preu i estoc. Un producte d'Odoo té un binding per instància: el mateix producte, una oferta diferent a cada operador, amb el seu SKU, el seu preu i la seva quantitat. Afegir un segon operador (GACD, l'API de venedor del qual respon a tdmp.mirakl.net, o qualsevol altre) és una instància més. Els perfils del catàleg només omplen valors per defecte; el codi que parla amb Mirakl és un de sol.
El problema real: repartir l'estoc
Dos operadors Mirakl, ManoMano, Amazon, Temu o la teva web poden mirar el mateix magatzem. Només els dos primers són Mirakl: els altres tenen la seva pròpia API de venedor (Amazon, la SP-API) i són connectors a part. Però tots venen contra el mateix estoc i cap no sap res dels altres: cadascun rep la quantitat que li exportes i ven contra ella fins a la següent exportació. Això no es resol «en temps real», perquè ni l'API ni l'operador funcionen així; es resol amb regles per canal. Cada instància decideix quatre coses abans de publicar una quantitat:
- Quina quantitat mira: a mà, prevista, lliure (descomptant el reservat) o a mà només als magatzems d'aquesta instància.
- Quant es guarda: un coixí per instància que cobreix les vendes d'altres canals entre dues exportacions.
- Mínim per publicar: si després del coixí queden menys de N unitats, es publica zero: vendre l'última unitat a tres llocs és la sobrevenda clàssica.
- Màxim publicat: un topall per instància, per no ensenyar a un operador un estoc ja promès a un altre.
L'ordre és al codi: quantitat segons l'estratègia, menys el coixí, zero si no arriba al mínim, retall al màxim. Amb 12 unitats lliures, coixí 2, mínim 3 i màxim 5, cada operador en veu 5. Si tots reben la quantitat a mà sense més, el primer que vengui l'última unitat deixa els altres venent aire. Coixí i cadència els tractem a estoc en temps real per a marketplaces, i com es governa tot des d'un únic Odoo, a vendre en diversos marketplaces i a solucions.
Comandes i estats: de Mirakl a Odoo i tornada
Mirakl té més estats de comanda dels que Odoo necessita i els redueix a sis: WAITING_ACCEPTANCE, WAITING_DEBIT, STAGING i INCIDENT_OPEN són «pendent»; SHIPPING, «en enviament» (el comprador ha pagat i corre el termini per expedir); SHIPPED, «enviat»; RECEIVED i CLOSED, «tancat»; CANCELED i REFUSED, «cancel·lat»; REFUNDED, «reemborsat». La comanda de la captura va entrar com a SHIPPED, es va mapar a «Enviat» i va quedar enllaçada a la comanda de venda S00509, amb moneda, total i impost del payload de l'operador.
El cicle de tornada: la comanda pendent s'accepta amb un PUT a /orders/{id}/accept, per tandes amb un topall per passada; en validar l'albarà s'envia el seguiment (OR23) i es marca l'enviament (OR24), i l'albarà queda estampat amb petició i resposta; la factura validada es puja a la comanda (OR74) esborrant abans l'anterior del mateix tipus (OR72, OR76). I la finestra incremental es demana per data d'actualització, no de creació: una comanda que canvia d'estat setmanes després no tornaria a entrar mai.
On es duplica si el connector no és idempotent
Tres llocs. La comanda: la base rebutja dos registres amb el mateix identificador a la mateixa instància (unique(instance_id, mirakl_order_id)); la importació actualitza l'existent. L'enviament: el connector rellegeix abans l'estat; si ja és SHIPPED no el repeteix, i si la rellegida falla no assumeix res i crida, perquè donar «ja enviat» per fet davant d'un timeout deixava comandes sense seguiment. I el reemborsament, que són diners: a l'auditoria de la 16.15.1 vam veure que el client HTTP reintentava qualsevol petició davant d'un 5xx o timeout, també la de OR28. Un timeout no diu que la petició no arribés: diu que no ho saps. Avui només es reintenten lectures, tret del 429, que garanteix que no es va processar; i el botó es nega a enviar un segon reemborsament complet si la comanda ja consta reemborsada.
Liquidacions: què retorna l'API i per què mereix conciliació pròpia
Mirakl no et paga comanda a comanda: transfereix periòdicament un net, i IV01 retorna el document que l'explica, amb l'import transferit i quatre cubs: comandes, comissions, reemborsaments i comissions retornades. El connector guarda cada document per instància (període, moneda, estat de pagament) i calcula un net propi a partir dels cubs. El que falta per arribar a l'import transferit són «altres tarifes», gairebé sempre la quota de l'operador: una liquidació real arrossegava 39,00 € de descòmput fins que vam incorporar aquest residu, i així queda a la vista com una línia més en lloc d'amagar-se en una diferència sense nom.
Quan un operador Mirakl no compensa
Que l'API sigui la mateixa no vol dir que cada invitació mereixi un sí. El cost d'entrar és al catàleg, no a la integració: mapar les teves categories contra un arbre de milers de nodes i omplir els atributs obligatoris de cada família és feina de persones, i es repeteix a cada operador. Poques categories afins, una comissió que se't menja el marge després de la quota o un termini d'acceptació que el teu magatzem no compleix: cap no compensa per fàcil que sigui connectar-lo. El senyal surt de la instància abans de publicar res: sincronitza el diccionari, mapa deu famílies i compta quants atributs obligatoris et falten. Si són centenars, et costarà més del que et vendrà.
El connector amb què hem fet l'anterior és en producció amb comandes reals i en verd (163 de 163 tests) a Odoo 19, 18 i 17, després de l'auditoria de la 16.15.1 (121 troballes candidates, 18 confirmades). Si hereteu un connector Mirakl d'un altre, què cal mirar és a auditar un connector Odoo heretat; si la plataforma que ha de parlar amb Odoo és la teva, això és un connector Odoo per al teu programari.
Preguntes freqüents
Aleshores venc «a Mirakl»?
No. Vens a l'operador que t'ha convidat: ell fixa categories, comissió, terminis i contracte. Mirakl és el programari amb què aquest operador gestiona el seu marketplace, i la seva API és la que integra el teu Odoo.
Necessito un connector per cada operador Mirakl?
No. Necessites una instància per operador dins del mateix connector: host, clau, botiga, diccionari, transportistes i regles d'estoc propis. El codi que parla amb l'API és el mateix.
Per què l'estoc no pot anar «en temps real»?
Perquè cada operador rep la quantitat que li exportes i ven contra ella fins a la següent exportació, sense saber dels altres. Allò que evita la sobrevenda és la regla per canal: quina quantitat es mira, coixí, mínim i màxim, més una cadència raonable.
Enllaços útils dins de FlexigoTech
El que fem sobre això
T'ha convidat un operador Mirakl i vens amb Odoo?
Explica'ns quin operador és, quants canals ja miren el teu magatzem i en quina versió d'Odoo estàs. Et diem què cal per connectar-lo com una instància més i quines regles d'estoc hauries de fixar abans de publicar. Escriu a comercial@flexigobe.com o truca al +34 616 809 504.