Checkout per Miva

Entro 24 ore dalla registrazione, un referente dedicato all'onboarding ti contatterà per avviare un processo di integrazione su misura.

Importante: I passaggi elencati di seguito sono a titolo di riferimento e sarai guidato attraverso di essi dal tuo referente onboarding.

1. Scarica il modulo dal Miva App Store, oppure richiedi il file zonos.mvc direttamente a Zonos.
2. Nel tuo pannello di amministrazione Miva, vai su Domain Settings -> Modules -> Add Module, carica il file zonos.mvc e fai clic su Add.

3. Vai su Settings -> Modules, cerca Zonos e fai clic su Install. Verifica che venga visualizzato come Installed.

In Miva, vai su Users -> API Tokens e fai clic su Add API Token. Configuralo come segue:

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- fai clic su Generate per creare una chiave di firma
• Timestamp: Require Timestamp Within 30 seconds

Nella schermata successiva, abilita Customer Service & Sales per consentire al token di creare e modificare ordini. Fai clic su Save.

Vai al modulo Checkout in Miva selezionando Miva -> Utility Settings -> Zonos, quindi compila i seguenti campi:

1. Store ID: Copia il tuo numero account Zonos da Dashboard -> Settings -> Account -> Integrations.
2. Zonos API Key: La tua chiave API segreta (non condividerla mai).
3. Zonos Public Key: La tua chiave pubblica.
4. Store Currency: La valuta base del tuo negozio (ad esempio, USD).
5. Environment: Seleziona Live per la produzione o Test per i test.
6. Checkout Button Selector: Selettore CSS per il tuo pulsante di checkout (esempio: a[href*="checkout.html"]).
7. Hidden Selectors: Per nascondere le opzioni di pagamento nazionali e altri dettagli che potrebbero non riguardare i clienti internazionali.
8. Import Orders: Seleziona questa opzione per importare automaticamente in Miva admin gli ordini Zonos completati. Richiede che i webhook siano registrati nel passaggio successivo.

Fai clic su Update in alto a destra per salvare prima di continuare.

Gli ordini vengono importati tramite webhook nel modulo 10.x. Le versioni precedenti del modulo utilizzavano invece un URL/endpoint di successo dell'ordine.

Dopo aver salvato le impostazioni, fai clic su Register Webhooks. In questo modo il tuo negozio viene collegato a Zonos in modo che gli ordini completati vengano importati automaticamente, le cancellazioni vengano sincronizzate e gli aggiornamenti di spedizione vengano rinviati a Miva.

I webhook devono essere registrati prima che l'importazione degli ordini, la sincronizzazione delle cancellazioni e gli aggiornamenti di spedizione funzionino. La casella Import Orders richiede che i webhook siano registrati.

Scorri verso il basso per completare i campi rimanenti:

1. Miva API Token: L'Access Token del token API creato nel passaggio Crea un token API.
2. Miva API Signature: La Signing Key della stessa voce del token API.
3. Image Type: Seleziona quale dimensione dell'immagine prodotto viene mostrata nel checkout Zonos (Main funziona per la maggior parte dei negozi).
4. Additional Field Mappings: Facoltativamente, mappa i campi personalizzati Miva sugli attributi/metadati Zonos (colore, materiale, taglia, ecc.). Consigliamo di mappare il codice HS se hai impostato codici HS specifici per prodotto nelle schede prodotto Miva. Non è obbligatorio per produrre un preventivo di dazi e imposte, poiché possiamo usare i codici HS specifici per prodotto inseriti in Catalog o il tuo codice HS predefinito. Tuttavia, è consigliato: l'accuratezza dei calcoli di landed cost aumenterà notevolmente con prodotti classificati correttamente. Per mappare un campo in Miva, crea un campo personalizzato per il codice HS e mappalo in Utility Settings -> Zonos.

Fai clic su Update per salvare tutte le impostazioni.

Ora che hai configurato l'account e il modulo, sei pronto per eseguire i test seguenti:

• Testare i preventivi di spedizione
• Effettuare un ordine di test sul tuo sito
• Testare il flusso ordini attraverso i tuoi sistemi
• Testare il tuo sito web

Scopri come eseguire questi test. Dovrai impostare il campo Environment del modulo su Test durante i test.

Al termine dei test, sei pronto per andare live! Imposta Environment su Live, verifica che le tue credenziali Zonos siano corrette e assicurati che i webhook siano registrati sul tuo negozio live.

1. Vai su dashboard.zonos.com -> Hello -> Hello Settings.
2. Attiva Currency behavior.
3. Inserisci il selettore CSS che individua gli elementi di prezzo del tuo prodotto (ad esempio, .price).

Zonos Hello convertirà e visualizzerà automaticamente i prezzi nella valuta locale dell'acquirente quando questa opzione è abilitata.

Le dimensioni di spedizione, il Paese di origine e il codice HS impostati nel catalogo Miva vengono mappati automaticamente su Zonos e vengono utilizzati per i preventivi di landed cost / spedizione, se presenti. Non è richiesta alcuna mappatura aggiuntiva da configurare.

Se il tuo negozio vende prodotti configurabili in cui tutte le varianti condividono un unico SKU, le Product Shipping Rules standard di Miva memorizzano un solo set di dimensioni per prodotto, quindi ogni configurazione viene trattata come della stessa dimensione, indipendentemente da ciò che il cliente ha selezionato.

Miva e Zonos supportano le dimensioni a livello di variante, ma ciò richiede di configurare ogni variante singolarmente. Questo può risultare impraticabile per i negozi con centinaia o migliaia di configurazioni che non corrispondono a varianti discrete.

Questa funzionalità risolve il problema leggendo le dimensioni per configurazione direttamente dal carrello al momento del checkout, utilizzando qualsiasi logica personalizzata già presente nel tuo negozio per calcolarle -- ad esempio, estraendo le dimensioni dalla descrizione del prodotto.

Requisiti

• Il tuo negozio deve già popolare le colonne di dimensione personalizzate sugli articoli del carrello quando questi vengono aggiunti (gestito lato Miva, al di fuori dell'ambito del modulo Zonos).
• Dovrai conoscere i nomi esatti delle colonne che utilizzi.

Configurazione

Inserisci quei nomi di colonna nei tre campi corrispondenti nell'amministrazione del modulo Zonos. Lasciali vuoti per tornare alle Product Shipping Rules standard -- la funzionalità è completamente opzionale e non influisce sui negozi che non la utilizzano.

Quando viene creata un'etichetta di spedizione o viene inserito un numero di tracking nel Zonos Dashboard, il numero di tracking e lo stato della spedizione vengono automaticamente inviati all'ordine corrispondente nel pannello di amministrazione Miva. Questo richiede che i webhook siano registrati (vedi il passaggio Registra i webhook sopra).

Il tracking può anche essere inserito direttamente in Miva. Usa la finestra di dialogo Enter Tracking Number su qualsiasi ordine Zonos -- il numero di tracking e lo stato della spedizione verranno sincronizzati automaticamente con il Zonos Dashboard.

Il debug log è accessibile all'interno del pannello di amministrazione Miva, nelle impostazioni del modulo Zonos. Registra l'intero ciclo di vita di ogni evento ordine elaborato dal modulo -- importazioni, sincronizzazioni di tracking, cancellazioni e richieste di cancellazione in uscita verso Zonos -- includendo sia i successi sia gli errori.

Ogni voce include l'ID ordine Zonos, l'ID ordine Miva e, se pertinente, dettagli a livello cliente come la risposta di errore dell'API Miva o Zonos. Questo lo rende la fonte di informazioni più completa per diagnosticare i problemi.

Il log conserva solo le 500 righe più recenti. Le voci più vecchie non vengono archiviate, quindi controllalo tempestivamente dopo che si verifica un problema -- gli eventi precedenti potrebbero già essere stati sovrascritti.

Log errori pubblico (nessun accesso richiesto) 

Un secondo log, ad accesso pubblico, è disponibile tramite URL diretto -- non è richiesto alcun accesso al pannello di amministrazione Miva. Registra solo gli errori (nessun successo) e non contiene PII del cliente o dati sensibili. Ogni voce è preceduta dalla versione del modulo (ad esempio, [v10.09]) per un'identificazione rapida.

Formato URL:

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Esempio:

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Store Code: Il miva_store_code viene restituito nell'array metadata della risposta API per tutti gli ordini dashboard.

Tutti i rimborsi dei pagamenti devono essere elaborati direttamente tramite la dashboard di Zonos. I pulsanti Refund, Capture e Void in Miva non sono disponibili per gli ordini importati da Zonos, per progettazione. Eventuali rimborsi elaborati in Zonos non aggiorneranno automaticamente gli importi di pagamento sull'ordine Miva corrispondente -- l'ordine Miva mantiene gli importi originariamente catturati e non viene sincronizzato con l'attività di rimborso in Zonos.

Per le cancellazioni degli ordini, il comportamento dipende dallo stato attuale dell'ordine:

• Open (non ancora spedito): Annullarlo in Miva lo annullerà anche in Zonos e annullerà l'autorizzazione di pagamento. Poiché Zonos non cattura il pagamento finché l'ordine non viene spedito, al cliente non viene mai effettivamente addebitato alcun importo e non è richiesto un rimborso separato.
• Shipped o Completed: Annullare l'ordine in Miva lo contrassegnerà come annullato, ma Zonos rifiuterà la cancellazione perché l'ordine è già stato evaso e non è più idoneo per la cancellazione automatica. In questo caso, viene aggiunta all'ordine Miva una nota visibile solo agli amministratori -- visibile solo allo staff del negozio e mai al cliente -- che spiega che l'ordine deve essere gestito in Zonos. Viene inoltre inviata una notifica e-mail all'indirizzo e-mail principale dell'account del negozio per avvisare il commerciante di intervenire nella dashboard di Zonos, dove può elaborare manualmente qualsiasi rimborso applicabile.

Sintomo: Gli ordini si completano in Zonos Checkout e compaiono nella dashboard di Zonos, ma non compare nulla nel pannello di amministrazione Miva.

Causa: Zonos invia un webhook ORDER_CREATED (HTTP POST) all'endpoint /mm5/json.mvc del tuo negozio. Sui siti di sviluppo, la sicurezza a livello server spesso blocca questa richiesta prima che raggiunga Miva. Le cause più comuni sono:

• HTTP Basic Auth -- Se il sito di sviluppo presenta una richiesta di password (Plesk, cPanel, .htaccess, ecc.), il webhook viene rifiutato con un errore 401 Unauthorized. Inserisci gli IP di Zonos nella whitelist del tuo .htaccess o della configurazione Plesk in modo che bypassino la richiesta di autenticazione.
• Cloudflare WAF / IP Access Rules -- Se il sito è instradato tramite Cloudflare, le sue regole di sicurezza potrebbero bloccare il POST prima che raggiunga il tuo server. Aggiungi una regola WAF per consentire le richieste POST in cui il percorso URL contiene /mm5/json.mvc, oppure inserisci gli IP di Zonos direttamente nella whitelist delle IP Access Rules di Cloudflare.
• Allowlist IP a livello server -- Se il sito di sviluppo limita il traffico solo a IP specifici (comune negli ambienti di staging bloccati agli IP dell'ufficio o della piattaforma), le richieste webhook di Zonos vengono scartate silenziosamente senza risposta. Aggiungi tutti gli IP di invio dei webhook Zonos alla allowlist del tuo server (Plesk IP Access Restriction Manager, cPanel IP Blocker, o le regole di sicurezza del tuo firewall/pannello di hosting).

IP di invio webhook Zonos

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

Questo di solito riguarda solo i siti di sviluppo/staging -- i siti Miva di produzione sono generalmente pubblici e non richiedono la whitelist degli IP. In caso di dubbi su come configurarlo, contatta il tuo hosting provider o il supporto Miva.

Le informazioni sui prodotti possono influire sull'importo di dazi e imposte dovuti e sul costo di spedizione. Più informazioni sui prodotti fornisci a Zonos, più preciso sarà il preventivo restituito. Zonos può generare un preventivo anche quando queste informazioni non sono disponibili, ma consiglia di fornire i seguenti dettagli chiave sui prodotti per migliorare l'accuratezza:

• Peso: Il peso influisce sul costo di spedizione, che può influire su dazi o imposte. I pesi nelle schede prodotto Miva vengono utilizzati automaticamente da Zonos quando presenti.
• Dimensioni: Le dimensioni possono influire sul costo di spedizione, che può influire su dazi o imposte. Zonos può utilizzare le dimensioni del prodotto (lunghezza, larghezza e altezza) impostate su ciascun prodotto in Miva, ma devi mapparle nell'app Zonos per un'integrazione corretta.
• Codici HS: I codici HS influiscono sulle aliquote dei dazi e a volte possono influire sulle imposte. Zonos può utilizzare i codici HS impostati nelle schede prodotto Miva, ma devi mappare il campo codice HS nell'app Zonos.
• Paese di origine: Il Paese di origine di un prodotto influisce sulle aliquote dei dazi e può influire sulle imposte. Miva non può inviare a Zonos il Paese di origine dei prodotti, quindi devono essere aggiunti tramite Zonos Catalog.

Dettagli prodotto trasmessi a Zonos da Miva 

Nota: In alternativa, puoi inserire una qualsiasi delle informazioni sopra in Catalog, sostituendo quelle memorizzate e trasmesse da Miva.

Scopri di più sulle informazioni prodotto per piattaforma.