Checkout für Miva

Innerhalb von 24 Stunden nach der Anmeldung kontaktiert Sie ein dedizierter Onboarding-Ansprechpartner, um einen maßgeschneiderten Integrationsprozess zu starten.

Wichtig: Die unten aufgeführten Schritte dienen als Referenz – Ihr Onboarding-Ansprechpartner führt Sie durch sie.

1. Laden Sie das Modul aus dem Miva App Store herunter oder fordern Sie die Datei zonos.mvc direkt bei Zonos an.
2. Gehen Sie in Ihrem Miva-Admin zu Domain Settings -> Modules -> Add Module, laden Sie die Datei zonos.mvc hoch und klicken Sie auf Add.

3. Gehen Sie zu Settings -> Modules, suchen Sie Zonos und klicken Sie auf Install. Bestätigen Sie, dass der Status Installed angezeigt wird.

Gehen Sie in Miva zu Users -> API Tokens und klicken Sie auf Add API Token. Konfigurieren Sie es wie folgt:

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- klicken Sie auf Generate, um einen Signierschlüssel zu erstellen
• Timestamp: Require Timestamp Within 30 seconds

Aktivieren Sie auf dem nächsten Bildschirm Customer Service & Sales, damit der Token Bestellungen erstellen und ändern kann. Klicken Sie auf Save.

Navigieren Sie zum Checkout-Modul in Miva über Miva -> Utility Settings -> Zonos und füllen Sie dann die folgenden Felder aus:

1. Store ID: Kopieren Sie Ihre Zonos-Kontonummer aus dem Dashboard -> Settings -> Account -> Integrations.
2. Zonos API Key: Ihr geheimer API-Schlüssel (niemals weitergeben).
3. Zonos Public Key: Ihr öffentlicher Schlüssel.
4. Store Currency: Die Basiswährung Ihres Shops (z. B. USD).
5. Environment: Wählen Sie Live für den Produktivbetrieb oder Test zum Testen.
6. Checkout Button Selector: CSS-Selektor für Ihren Checkout-Button (Beispiel: a[href*="checkout.html"]).
7. Hidden Selectors: Zum Ausblenden inländischer Zahlungsoptionen und anderer Details, die für internationale Kunden nicht relevant sind.
8. Import Orders: Aktivieren, um abgeschlossene Zonos-Bestellungen automatisch in den Miva-Admin zu importieren. Dies erfordert, dass Webhooks im nächsten Schritt registriert werden.

Klicken Sie oben rechts auf Update, um vor dem Fortfahren zu speichern.

Bestellungen werden im 10.x-Modul per Webhook importiert. Frühere Modulversionen verwendeten stattdessen eine Order-Success-URL/einen Endpunkt.

Klicken Sie nach dem Speichern Ihrer Einstellungen auf Register Webhooks. Dadurch wird Ihr Shop mit Zonos verbunden, sodass abgeschlossene Bestellungen automatisch importiert, Stornierungen synchronisiert und Versand-Updates an Miva zurückgemeldet werden.

Webhooks müssen registriert sein, damit der Bestellimport, die Stornierungssynchronisierung und die Versand-Updates funktionieren. Das Kontrollkästchen Import Orders erfordert, dass Webhooks registriert sind.

Scrollen Sie nach unten, um die restlichen Felder auszufüllen:

1. Miva API Token: Der Access Token aus dem API-Token, das Sie im Schritt API-Token erstellen angelegt haben.
2. Miva API Signature: Der Signing Key aus demselben API-Token-Eintrag.
3. Image Type: Legt fest, welche Produktbildgröße im Zonos-Checkout angezeigt wird (Main funktioniert für die meisten Shops).
4. Additional Field Mappings: Optional können Sie benutzerdefinierte Miva-Felder Zonos-Attributen/-Metadaten zuordnen (Farbe, Material, Größe usw.). Wir empfehlen, den HS code zuzuordnen, wenn Sie in Ihren Miva-Produktlisten produktspezifische HS-Codes festgelegt haben. Das ist nicht erforderlich, um ein Zoll- und Steuerangebot zu erstellen, da wir produktspezifische HS-Codes verwenden können, die Sie in Catalog eingegeben haben, oder Ihren Standard-HS-Code nutzen können. Es wird jedoch empfohlen; die Genauigkeit der Landed-Cost-Berechnungen steigt erheblich mit korrekt klassifizierten Produkten. Um ein Feld in Miva zuzuordnen, erstellen Sie ein benutzerdefiniertes Feld für den HS-Code und ordnen Sie es dann unter Utility Settings -> Zonos zu.

Klicken Sie auf Update, um alle Einstellungen zu speichern.

Nachdem Sie Ihr Konto und Ihr Modul eingerichtet haben, sind Sie bereit zum Testen:

• Versandangebote testen
• Eine Testbestellung auf Ihrer Website aufgeben
• Bestellablauf durch Ihre Systeme testen
• Ihre Website testen

Erfahren Sie, wie Sie diese Tests durchführen. Sie müssen während des Testens das Feld Environment des Moduls auf Test setzen.

Nach Abschluss der Tests sind Sie bereit für den Go-Live! Setzen Sie Environment auf Live, bestätigen Sie, dass Ihre Zonos-Zugangsdaten korrekt sind, und stellen Sie sicher, dass Webhooks in Ihrem Live-Shop registriert sind.

1. Gehen Sie zu dashboard.zonos.com -> Hello -> Hello Settings.
2. Aktivieren Sie Currency behavior.
3. Geben Sie den CSS-Selektor ein, der auf Ihre Produktpreis-Elemente zielt (z. B. .price).

Zonos Hello wandelt Preise automatisch um und zeigt sie in der lokalen Währung des Käufers an, sobald dies aktiviert ist.

Versandabmessungen, Ursprungsland und HS-Code, die im Miva-Katalog festgelegt sind, werden automatisch an Zonos übergeben und, sofern vorhanden, für Landed-Cost-/Versandangebote verwendet. Es ist keine zusätzliche Zuordnung zur Konfiguration erforderlich.

Wenn Ihr Shop konfigurierbare Produkte verkauft, bei denen sich alle Varianten eine einzige SKU teilen, speichern Mivas Standard-Product-Shipping-Rules einen Satz Abmessungen pro Produkt, sodass jede Konfiguration unabhängig von der Kundenauswahl als gleich groß behandelt wird.

Miva und Zonos unterstützen Abmessungen auf Variantenebene, dies erfordert jedoch die individuelle Einrichtung jeder Variante. Das kann bei Shops mit Hunderten oder Tausenden Konfigurationen, die sich nicht auf einzelne Varianten abbilden lassen, unpraktikabel sein.

Diese Funktion löst das, indem sie die Abmessungen pro Konfiguration direkt aus dem Warenkorb beim Checkout ausliest -- unter Verwendung der individuellen Logik, die Ihr Shop bereits zu ihrer Berechnung einsetzt, zum Beispiel durch das Auslesen von Abmessungen aus der Produktbeschreibung.

Voraussetzungen

• Ihr Shop muss beim Hinzufügen von Artikeln zum Warenkorb bereits benutzerdefinierte Abmessungsspalten für Warenkorbartikel befüllen (dies erfolgt auf Miva-Seite, außerhalb des Zonos-Moduls).
• Sie müssen die genauen Spaltennamen kennen, die Sie verwenden.

Konfiguration

Geben Sie diese Spaltennamen in die drei entsprechenden Felder im Zonos-Modul-Admin ein. Lassen Sie sie leer, um auf die Standard-Product-Shipping-Rules zurückzufallen -- die Funktion ist vollständig optional und wirkt sich nicht auf Shops aus, die sie nicht nutzen.

Wenn im Zonos Dashboard ein Versandetikett erstellt oder eine Sendungsverfolgungsnummer eingegeben wird, werden die Sendungsverfolgungsnummer und der Sendungsstatus automatisch an die entsprechende Bestellung im Miva-Admin übertragen. Dies erfordert, dass Webhooks registriert sind (siehe den Schritt Webhooks registrieren oben).

Tracking kann auch direkt in Miva eingegeben werden. Verwenden Sie den Eingabedialog Enter Tracking Number bei jeder Zonos-Bestellung -- die Sendungsverfolgungsnummer und der Sendungsstatus werden automatisch mit dem Zonos Dashboard synchronisiert.

Das Debug-Log ist im Miva-Admin unter den Zonos-Moduleinstellungen zugänglich. Es zeichnet den vollständigen Lebenszyklus jedes vom Modul verarbeiteten Bestellereignisses auf -- Importe, Tracking-Synchronisierungen, Stornierungen und ausgehende Stornierungsanfragen an Zonos -- einschließlich sowohl Erfolgen als auch Fehlern.

Jeder Eintrag enthält die Zonos-Bestell-ID, die Miva-Bestell-ID und, sofern relevant, kundenbezogene Details wie die Fehlerantwort der Miva- oder Zonos-API. Das macht es zur vollständigsten Informationsquelle zur Fehlerdiagnose.

Das Log speichert nur die letzten 500 Zeilen. Ältere Einträge werden nicht archiviert. Prüfen Sie es daher zeitnah nach Auftreten eines Problems -- frühere Ereignisse könnten bereits überschrieben worden sein.

Öffentliches Fehlerprotokoll (kein Login erforderlich) 

Ein zweites, öffentlich zugängliches Protokoll ist über eine direkte URL verfügbar -- kein Miva-Admin-Login erforderlich. Es zeichnet nur Fehler auf (keine Erfolge) und enthält keine personenbezogenen Kundendaten oder sensible Daten. Jeder Eintrag ist zur schnellen Identifizierung mit der Modulversion versehen (z. B. [v10.09]).

URL-Format:

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

Beispiel:

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: Der miva_store_code wird im Metadaten-Array der API-Antwort für alle Dashboard-Bestellungen zurückgegeben.

Alle Zahlungsrückerstattungen müssen direkt über das Zonos Dashboard verarbeitet werden. Die Schaltflächen Refund, Capture und Void in Miva stehen für von Zonos importierte Bestellungen absichtlich nicht zur Verfügung. Rückerstattungen, die in Zonos verarbeitet werden, aktualisieren die Zahlungsbeträge der entsprechenden Miva-Bestellung nicht automatisch -- die Miva-Bestellung behält die ursprünglich erfassten Beträge bei und wird nicht mit der Rückerstattungsaktivität in Zonos synchronisiert.

Bei Bestellstornierungen hängt das Verhalten vom aktuellen Status der Bestellung ab:

• Open (noch nicht versandt): Das Stornieren in Miva storniert die Bestellung auch in Zonos und hebt die Zahlungsautorisierung auf. Da Zonos die Zahlung erst bei Versand der Bestellung erfasst, wird dem Kunden nie tatsächlich etwas berechnet, und eine separate Rückerstattung ist nicht erforderlich.
• Shipped oder Completed: Das Stornieren in Miva markiert die Miva-Bestellung als storniert, aber Zonos lehnt die Stornierung ab, da die Bestellung bereits ausgeführt wurde und nicht mehr für eine automatische Stornierung infrage kommt. In diesem Fall wird der Miva-Bestellung eine interne Notiz hinzugefügt -- sichtbar nur für das Shop-Personal, niemals für den Kunden -- die erklärt, dass die Bestellung in Zonos bearbeitet werden muss. Zusätzlich wird eine E-Mail-Benachrichtigung an die primäre E-Mail-Adresse des Shop-Kontos gesendet, die den Händler darauf hinweist, im Zonos Dashboard tätig zu werden, wo er eine etwaige Rückerstattung manuell verarbeiten kann.

Symptom: Bestellungen werden im Zonos Checkout abgeschlossen und erscheinen im Zonos Dashboard, aber im Miva-Admin taucht nichts auf.

Ursache: Zonos sendet einen ORDER_CREATED-Webhook (HTTP POST) an den /mm5/json.mvc-Endpunkt Ihres Shops. Auf Dev-Sites blockiert die serverseitige Sicherheit diese Anfrage oft, bevor sie Miva erreicht. Häufige Ursachen:

• HTTP Basic Auth -- Wenn die Dev-Site eine Passwortabfrage hat (Plesk, cPanel, .htaccess usw.), wird der Webhook mit 401 Unauthorized abgelehnt. Setzen Sie die IPs von Zonos in Ihrer .htaccess- oder Plesk-Konfiguration auf die Whitelist, damit sie die Authentifizierungsabfrage umgehen.
• Cloudflare WAF / IP Access Rules -- Wenn die Site über Cloudflare läuft, können dessen Sicherheitsregeln den POST blockieren, bevor er Ihren Server erreicht. Fügen Sie eine WAF-Regel hinzu, die POST-Anfragen zulässt, deren URL-Pfad /mm5/json.mvc enthält, oder setzen Sie die IPs von Zonos direkt in Cloudflares IP Access Rules auf die Whitelist.
• Serverseitige IP-Allowlist -- Wenn die Dev-Site den Datenverkehr auf bestimmte IPs beschränkt (üblich bei Staging-Umgebungen, die auf Büro- oder Plattform-IPs beschränkt sind), werden Zonos-Webhook-Anfragen stillschweigend ohne Antwort verworfen. Fügen Sie alle Zonos-Webhook-Zustell-IPs zur Allowlist Ihres Servers hinzu (Plesk IP Access Restriction Manager, cPanel IP Blocker oder die Sicherheitsregeln Ihrer Firewall/Ihres Hosting-Panels).

Zonos-Webhook-Zustell-IPs

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

Dies betrifft in der Regel nur Dev-/Staging-Sites -- produktive Miva-Sites sind normalerweise öffentlich zugänglich und benötigen kein IP-Whitelisting. Wenden Sie sich bei Unsicherheiten an Ihren Hosting-Anbieter oder den Miva-Support.

Produktinformationen können die Höhe der fälligen Zölle und Steuern sowie die Versandkosten beeinflussen. Je mehr Produktinformationen Sie Zonos bereitstellen, desto präziser wird das zurückgegebene Angebot. Zonos kann ein Angebot auch erstellen, wenn diese Informationen nicht verfügbar sind, empfiehlt aber die folgenden wichtigen Produktdetails zur Verbesserung der Genauigkeit:

• Gewicht: Das Gewicht beeinflusst Ihre Versandkosten, was Zölle oder Steuern beeinflussen kann. Gewichte in Ihren Miva-Produktlisten werden von Zonos automatisch verwendet, wenn vorhanden.
• Abmessungen: Abmessungen können Ihre Versandkosten beeinflussen, was Zölle oder Steuern beeinflussen kann. Zonos kann Produktabmessungen (Länge, Breite und Höhe) nutzen, die bei jedem Produkt in Miva festgelegt sind, aber Sie müssen sie für eine ordnungsgemäße Integration in der Zonos-App zuordnen.
• HS-Codes: HS-Codes beeinflussen Zollsätze und können manchmal Steuern beeinflussen. Zonos kann die in Ihren Produktlisten in Miva festgelegten HS-Codes verwenden, aber Sie müssen das HS-Code-Feld in der Zonos-App zuordnen.
• Ursprungsland: Das Ursprungsland eines Produkts beeinflusst Zollsätze und kann Steuern beeinflussen. Miva kann das Ursprungsland Ihrer Produkte nicht an Zonos senden, daher müssen sie über Zonos Catalog hinzugefügt werden.

Von Miva an Zonos übergebene Produktdetails 

Hinweis: Alternativ können Sie alle oben genannten Informationen in Catalog eingeben und die von Miva gespeicherten und übergebenen Informationen überschreiben.

Mehr erfahren über Produktinformationen nach Plattform.