Mirakl non è un marketplace: è la piattaforma dietro molti di essi, e questo cambia il modo di integrarlo con Odoo

Mirakl non è un marketplace su cui vendere. È il software con cui un retailer crea il proprio: Leroy Merlin, Carrefour, Kingfisher, Macy's o Best Buy figurano oggi come clienti sul sito di Mirakl. Quando uno ti invita, vendi sull'operatore (le sue categorie, la sua commissione, il suo contratto), ma il tuo Odoo parla con l'API di Mirakl, la stessa per tutti. Un connettore Mirakl fatto bene non è «il connettore di Leroy Merlin»: sono N marketplace con una sola API e credenziali diverse. E la parte difficile non è l'API: è ripartire la giacenza tra i canali che guardano lo stesso magazzino.

Cosa condividono tutti gli operatori Mirakl e cosa no

L'API venditore di Mirakl ha un codice di operazione per ogni cosa, lo stesso comunque si chiami l'operatore: OR11 elenca gli ordini, OR23 e OR24 inviano il tracking e segnano la spedizione, OR28 rimborsa, OF01 carica le offerte tramite file, IV01 restituisce i documenti di liquidazione, M11 è la messaggistica con l'acquirente e SH21 elenca i vettori. Un operatore può avere intere famiglie disattivate (ce ne sono senza messaggistica né vettori, e il connettore segna l'endpoint come non disponibile davanti a un 404 o a un 410), ma quando la espone la chiamata è la stessa.

Cambia tutto ciò che non è API: l'host (adeo-marketplace.mirakl.net in Leroy Merlin), la chiave e il negozio, l'albero delle categorie e gli attributi obbligatori (4.844 categorie e 35.364 attributi nel nostro account Leroy Merlin), i vettori ammessi (165 codici), i motivi di rimborso, la valuta e, soprattutto, la modalità delle imposte: alcuni inviano i prezzi con IVA inclusa (TAX_INCLUDED) e altri senza (TAX_EXCLUDED). Questo punto ci è costato un errore reale: il connettore prendeva il prezzo con IVA come base, Odoo la sommava un'altra volta e 48,86 € entravano come 59,12 €. Verificato sui 20 ordini reali dell'account.

Come si modella in Odoo: un account per operatore

Nel nostro connettore Mirakl ogni operatore è un'istanza: un record con il suo URL base, il suo URL API, la sua chiave, il suo negozio, la sua azienda, il suo magazzino e il suo team di vendita. Testando la connessione legge /platform/configuration, /account e /channels e annota quale piattaforma risponde, di quale negozio si tratta e quali funzioni espone. Nella schermata, la piattaforma rilevata è «Marketplace Adeo» e il fornitore rilevato è leroy_merlin.

Dall'istanza dipende tutto ciò che riguarda l'operatore: il dizionario di categorie, attributi e valori (unico per istanza e codice, quindi due operatori non si sovrappongono mai), la mappatura di categorie e vettori e le regole di prezzo e giacenza. Un prodotto di Odoo ha un binding per istanza: lo stesso prodotto, un'offerta diversa su ogni operatore, con il suo SKU, il suo prezzo e la sua quantità. Aggiungere un secondo operatore (GACD, la cui API venditore risponde su tdmp.mirakl.net, o qualsiasi altro) è un'istanza in più. I profili del catalogo compilano solo valori predefiniti; il codice che parla con Mirakl è uno solo.

Il vero problema: ripartire la giacenza

Due operatori Mirakl, ManoMano, Amazon, Temu o il tuo sito possono guardare lo stesso magazzino. Solo i primi due sono Mirakl: gli altri hanno una propria API venditore (Amazon, la SP-API) e sono connettori a parte. Ma tutti vendono sulla stessa giacenza e nessuno sa degli altri: ognuno riceve la quantità che gli esporti e vende su quella fino all'esportazione successiva. Questo non si risolve «in tempo reale», perché né l'API né l'operatore funzionano così; si risolve con regole per canale. Ogni istanza decide quattro cose prima di pubblicare una quantità:

• Quale quantità guarda: a mano, prevista, libera (al netto del riservato) oppure a mano solo nei magazzini di quell'istanza.
• Quanto trattiene: un cuscinetto per istanza che copre le vendite degli altri canali tra due esportazioni.
• Minimo per pubblicare: se dopo il cuscinetto restano meno di N unità, si pubblica zero: vendere l'ultima unità in tre posti è la classica vendita in eccesso.
• Massimo pubblicato: un tetto per istanza, per non mostrare a un operatore una giacenza già promessa a un altro.

L'ordine è nel codice: quantità secondo la strategia, meno il cuscinetto, zero se non raggiunge il minimo, taglio al massimo. Con 12 unità libere, cuscinetto 2, minimo 3 e massimo 5, ogni operatore vede 5. Se tutti ricevono la quantità a mano e basta, il primo che vende l'ultima unità lascia gli altri a vendere aria. Cuscinetto e cadenza li trattiamo in giacenza in tempo reale per i marketplace, e come si governa tutto da un unico Odoo in vendere su più marketplace e in soluzioni.

Ordini e stati: da Mirakl a Odoo e ritorno

Mirakl ha più stati d'ordine di quelli che servono a Odoo e li riduce a sei: WAITING_ACCEPTANCE, WAITING_DEBIT, STAGING e INCIDENT_OPEN sono «in attesa»; SHIPPING, «in spedizione» (l'acquirente ha pagato e decorre il termine per spedire); SHIPPED, «spedito»; RECEIVED e CLOSED, «chiuso»; CANCELED e REFUSED, «annullato»; REFUNDED, «rimborsato». L'ordine della schermata è entrato come SHIPPED, è stato mappato su «Spedito» ed è rimasto collegato all'ordine di vendita S00509, con valuta, totale e imposta del payload dell'operatore.

Il ciclo di ritorno: l'ordine in attesa si accetta con un PUT a /orders/{id}/accept, a lotti con un tetto per passata; alla convalida del prelievo si invia il tracking (OR23) e si segna la spedizione (OR24), e il prelievo resta timbrato con richiesta e risposta; la fattura convalidata si carica sull'ordine (OR74) cancellando prima la precedente dello stesso tipo (OR72, OR76). E la finestra incrementale si richiede per data di aggiornamento, non di creazione: un ordine che cambia stato settimane dopo non rientrerebbe mai più.

Dove si duplica se il connettore non è idempotente

In tre punti. L'ordine: il database rifiuta due record con lo stesso identificativo nella stessa istanza (unique(instance_id, mirakl_order_id)); l'importazione aggiorna quello esistente. La spedizione: il connettore rilegge prima lo stato; se è già SHIPPED non la ripete, e se la rilettura fallisce non dà nulla per scontato e chiama, perché dare per fatto «già spedito» davanti a un timeout lasciava ordini senza tracking. E il rimborso, che sono soldi: nell'audit della 16.15.1 abbiamo visto che il client HTTP ritentava qualsiasi richiesta davanti a 5xx o timeout, anche quella di OR28. Un timeout non dice che la richiesta non sia arrivata: dice che non lo sai. Oggi si ritentano solo le letture, tranne il 429, che garantisce che non è stata elaborata; e il pulsante si rifiuta di inviare un secondo rimborso completo se l'ordine risulta già rimborsato.

Liquidazioni: cosa restituisce l'API e perché merita una riconciliazione propria

Mirakl non ti paga ordine per ordine: trasferisce periodicamente un netto, e IV01 restituisce il documento che lo spiega, con l'importo trasferito e quattro voci: ordini, commissioni, rimborsi e commissioni restituite. Il connettore salva ogni documento per istanza (periodo, valuta, stato di pagamento) e calcola un netto proprio a partire dalle voci. Ciò che manca per arrivare a quanto trasferito è «altre tariffe», quasi sempre la quota dell'operatore: una liquidazione reale trascinava 39,00 € di scarto finché non abbiamo incorporato quel residuo, e così resta in vista come una riga in più invece di nascondersi in una differenza senza nome.

Quando un operatore Mirakl non conviene

Che l'API sia la stessa non significa che ogni invito meriti un sì. Il costo di ingresso sta nel catalogo, non nell'integrazione: mappare le tue categorie su un albero di migliaia di nodi e compilare gli attributi obbligatori di ogni famiglia è lavoro di persone, e si ripete su ogni operatore. Poche categorie affini, una commissione che si mangia il margine dopo la quota o un termine di accettazione che il tuo magazzino non rispetta: nessuno conviene, per quanto sia facile collegarlo. Il segnale emerge dall'istanza prima di pubblicare qualsiasi cosa: sincronizza il dizionario, mappa dieci famiglie e conta quanti attributi obbligatori ti mancano. Se sono centinaia, ti costerà più di quanto venderà.

Il connettore con cui abbiamo fatto quanto sopra è in produzione con ordini reali e in verde (163 test su 163) su Odoo 19, 18 e 17, dopo l'audit della 16.15.1 (121 risultanze candidate, 18 confermate). Se erediti un connettore Mirakl da altri, cosa guardare è in auditare un connettore Odoo ereditato; se la piattaforma che deve parlare con Odoo è la tua, quello è un connettore Odoo per il tuo software.

Domande frequenti

Link utili dentro FlexigoTech

Cosa facciamo in merito