Markt --- E-Mail-Checkout (für Integratoren)

Zuletzt aktualisiert: Aug 31, 2026Abschnitt: Integrationen

Mailoo hostet Ihren Onlineshop nicht. Die Market-Integration bietet Ihnen eine Katalog-API, optionale Bestell-APIs für einen einfachen „Warenkorb-Snapshot → Bestellung per E-Mail"-Ablauf sowie Dashboard-APIs für den Projekteigentümer zum Auflisten von Bestellungen und Statusänderungen.

Verwandt: Kataloglese und Attribute --- market-catalog-csv{.interpreted-text role="doc"} / market-catalog-external-api{.interpreted-text role="doc"}. OpenAPI --- https://api.mailoo.app/docs/v1.

Architektur

  • Warenkorb / Katalog-Cache: Verwalten Sie den Warenkorbstatus auf der Integrator-Website (z. B. localStorage oder ein Client-Store). Aktualisieren Sie Preise mit ``GET /api/v1/market/.../effective-price?kind=...`` und dem Preisarten-Schlüssel (oder denselben Auflösungsregeln) vor dem Absenden, damit Summen mit dem Server übereinstimmen. Siehe market-catalog-external-api{.interpreted-text role="doc"} (Preisarten und effektiver Preis).
  • Zugangsdaten: Alle ``X-API-Key``-Aufrufe laufen über Ihren Server oder BFF, niemals aus öffentlichen Browser-Bundles.
  • Bestellung einreichen: Ihr BFF sendet per ``POST`` an Mailoo mit ``market.order.submit``; Mailoo speichert einen Zeilen-Snapshot und aufgelöste Preise, sendet eine Bestätigungsmail an den Käufer wenn diese Market-Integration ausgehendes SMTP konfiguriert hat (Dashboard Connection & settings → Outbound email (SMTP) --- dasselbe outboundMail wie bei FORM-/CONTACT-Integrationen) und gibt ein einmaliges ``accessToken`` für schreibgeschütztes Polling zurück. Globales Plattform-SMTP (GLOBAL_SMTP_*) wird nicht für diese E-Mail verwendet.
  • Nach dem Einreichen: Der Käufer (oder Ihre SPA) kann ``GET /api/v1/market/public/orders/{orderId}?token=`` ohne API-Schlüssel aufrufen, bis das Token abläuft. Wenn das Token verloren geht, hat der Käufer nur die E-Mail und die Bestell-ID, die Sie in der Benutzeroberfläche anzeigen.
  • Back-Office: Der Projekteigentümer verwendet Bearer-Routen unter ``/api/v1/projects/{uid}/integrations/{id}/market/orders/...`` zum Auflisten, Lesen und Statusändern von Bestellungen.

Bestellung erstellen (BFF)

  • ``POST {baseUrl}/api/v1/market/{projectUid}/integrations/{integrationId}/orders``
  • Header: ``X-API-Key`` mit ``market.order.submit`` (oder FULL)
  • Body (JSON):
  • ``customerEmail`` (erforderlich) --- Käuferadresse (auf Kleinbuchstaben normalisiert)
  • ``items`` (erforderlich, nicht leer) --- jedes Element:
  • ``productId`` --- muss in dieser Integration ``PUBLISHED`` sein
  • ``priceKindId`` oder ``priceKindKey`` (genau eines) --- die Preisart. Bevorzugen Sie ``priceKindKey`` (z. B. base) für Integrator-Konfiguration; ``priceKindId`` ist die interne CUID, wenn Sie sie bereits haben (z. B. aus ``GET .../price-lists/...``-Zeilen).
  • ``quantity`` --- positiver Dezimal-String (z. B. "2", "1.5")
  • ``variantId`` --- erforderlich wenn das Produkt Varianten hat, weggelassen (oder null) wenn nicht
  • ``measurementUnitId`` --- optional; Standard ist die Produkt-Standardeinheit + effective-price-Auflösungsregeln
  • ``note``, ``metadata`` --- optional (integratordefiniert)

Antwort (201): ``data.id``, ``data.status`` (beginnt als NEW), ``data.accessToken`` (nur in der Käufer-Session speichern / an den Client für UX zurückgeben), ``data.accessExpiresAt``, ``data.totalAmount``, ``data.currency`` und ``data.emailToCustomer`` (ob outboundMail der Integration senden konnte: SENT / FAILED / NOT_CONFIGURED).

Öffentliches Lesen (Käufer)

  • ``GET {baseUrl}/api/v1/market/public/orders/{orderId}?token={accessToken}``
  • Oder ``X-Market-Order-Token: {accessToken}``
  • Kein ``X-API-Key``. Ungültiges/fehlendes Token gibt 404 zurück (gleich wie unbekannte Bestellung), um die Existenz nicht offenzulegen.

Token-TTL beträgt standardmäßig 72 Stunden; die API kann ``MARKET_ORDER_ACCESS_TOKEN_TTL_HOURS`` (1--720) auf dem Mailoo-Host setzen.

Eigentümer-Dashboard (JWT)

Authentifizierte Routen (Zusammenfassung):

  • ``GET .../market/orders`` --- Liste (optionale ``limit``-Abfrage, max. 100)
  • ``GET .../market/orders/{orderId}`` --- vollständiger Snapshot + Zeilen-``attributesSnapshot``
  • ``PATCH .../market/orders/{orderId}`` --- ``{ "status": "...", "note"?: "..." }`` (Statusübergänge: Endstatus ``REJECTED``, ``FULFILLED``, ``CANCELLED`` können nicht in einen anderen Status wechseln)
  • ``GET .../market/orders/{orderId}/status-events`` --- Prüfprotokoll

Status: ``NEW``, ``PROCESSING``, ``CONFIRMED``, ``REJECTED``, ``FULFILLED``, ``CANCELLED``.

API-Schlüssel-Berechtigungen

  • ``market.external-read`` --- nur Katalog-``GET``-Aufrufe; auf einem BFF verwenden, das Produktseiten abruft.
  • ``market.order.submit`` --- nur ``POST .../orders``; kann ein separater beschränkter Schlüssel auf dem Checkout-BFF sein.
  • Sie können einen FULL-Schlüssel nur in vertrauenswürdigen Backends verwenden; für minimale Privilegien trennen Sie Lese- von Submit-Schlüssel wie oben.

:::: note ::: title Note :::

Das Mailoo-Dashboard ist die Admin-Konsole; der kundenseitige Checkout läuft auf Ihrer Website und ruft Mailoos öffentliche API genauso auf wie jeder Dritte. ::::

📚