Einleitung
Dieses Dokument hilft dir dabei, eine Dropshipping-Integration zu erstellen und sie im Marketplace App zu veröffentlichen. Es beschreibt die übergeordneten Ziele und die Struktur, die du beim Aufbau von Provider-Integrationen (z. B. Logistik, Fulfillment, Shipping) befolgen solltest, die sich mit der Plattform verbinden und über den Marketplace verteilt werden.
Dropshipping-Integration
1. Marketplace App Erstellung
Erstelle deine App im Marketplace: Lege den Distributionstyp fest (Agency oder Sub-Account), vervollständige das App-Profil, füge die erforderlichen OAuth-Scopes hinzu und generiere Client Credentials (Client ID/Secret). Damit wird die Identität und die Berechtigung deiner App definiert.
Für eine detaillierte Anleitung siehe: How to get started with the Developer's Marketplace.
Abhängig von den APIs, die du nutzen möchtest (Produkte, Preise, Orders, Fulfillments, Webhooks usw.), musst du die entsprechenden OAuth-Scopes zur App hinzufügen. Die vollständige Liste findest du hier: Scopes.
2. Autorisierungs-Handling für Marketplace App
Konfiguriere die OAuth Redirect URL in den App-Einstellungen und implementiere anschließend einen GET-Callback-Endpunkt, um den Authorization Code zu empfangen. Tausche den Code gegen Access-/Refresh-Tokens aus, speichere sie sicher und richte einen POST-Webhook-Endpunkt ein; trage dessen URL in den App-Einstellungen ein. Weise anschließend Locations/Accounts der App zu und überprüfe die Verbindung.
Für eine detaillierte Anleitung siehe: How to get started with the Developer's Marketplace.
3. Produkt-Sync (Plattform → ProfitBoost)
Nutze die Public API, um zuerst ein Produkt zu erstellen und anschließend einen oder mehrere Preise für dieses Produkt anzulegen. Für einfache Produkte hast du einen einzelnen Preis; für Variantenprodukte erstellst du einen Preis pro Variantenkombination.
Produkt-Erstellung (High-Level):
Erstelle ein Produkt mit den Kernfeldern: Name, locationId, Beschreibung, productType (PHYSICAL/DIGITAL), availableInStore, Bild und Medias.
Für Variantenprodukte füge Varianten hinzu (z. B. Farbe, Größe). Bewahre die Option-IDs auf, da sie für die Preis-Erstellung erforderlich sind.
Preis-Erstellung:
Erstelle einen Preis, der auf die Produkt-_id verweist: inkl. locationId, Typ (one_time/recurring), Währung, Betrag, SKU und optional Inventory-Flags.
Für Variantenprodukte übergib variantOptionIds, die der jeweiligen Kombination entsprechen (z. B. [Farbe: Rot, Größe: Klein]).
Für physische Produkte füge shippingOptions mit Gewicht (value, unit) und Dimensionen (length, width, height, unit) hinzu.
Optional: Nachdem Preise erstellt wurden, kannst du Bilder bestimmten Varianten zuordnen, indem du die Product Medias mit priceIds aktualisierst, damit der Store die passenden Variantenbilder rendert.
Für eine detaillierte Anleitung (Beispiele und Payloads): Create a Product with Price using Public API.
Für die Liste der APIs und Standard-Response-Felder: Integrations API — Standard Response Fields.
4. Order Webhooks (ProfitBoost → Provider)
Abonniere zwei Webhooks: OrderCreate und OrderStatusUpdate. Diese steuern den Export von Orders zu deinem Provider und nachfolgende Updates.
OrderCreate Webhook (Schema-Highlights):
Enthält Order-Header (IDs, Daten), Kundeninformationen, Shipping-/Billing-Adressen, Line Items mit Preis/SKU, Währung/Beträgen und optional Metadaten.
Nutze ihn, um die Order im Provider zu erstellen oder zu upserten. Mappe jedes Line Item auf die Provider-SKU/Variante.
Schema: OrderCreate
OrderStatusUpdate Webhook (Schema-Highlights):
Enthält Order-ID/Status-Transitions (z. B. pending → completed/cancelled), Zeitstempel und ggf. Fulfillment-Signale.
Nutze ihn, um die Provider-Order nur dann zu erstellen, wenn der Status geeignet ist (z. B. Completed), oder um sie zu stornieren/anzuhalten.
Schema: OrderStatusUpdate
Nutze diese Webhooks, um ein provider-spezifisches Order-Payload zu erstellen (Mapping von Items zu SKUs/Varianten, Adressen, Summen) und die Order zu erstellen oder zu aktualisieren.
5. Fulfillment Webhooks (Provider → ProfitBoost)
Abonniere die Shipment-/Fulfillment-Webhooks deines Providers. Wenn eine Sendung erstellt oder aktualisiert wird, baue ein Fulfillment-Payload für die entsprechende ProfitBoost-Order und sende es.
Mapping Provider Shipment → ProfitBoost Fulfillment:
Order: interne Order-ID in ProfitBoost
Items: price/variant IDs und Mengen
Tracking: trackingNumber, shippingCarrier, trackingUrl
Optional: Customer-Benachrichtigung
Nutze die API zur Erstellung des Fulfillments: Create Order Fulfillment.
Beispiel Request Body:
{ "items": [{ "priceId": "66b6021be68f7a98102ba272", "qty": 2 }], "trackings": [ { "trackingNumber": "1Z999AA10123456784", "shippingCarrier": "UPS", "trackingUrl": "https://wwwapps.ups.com/WebTracking/track?trackNums=1Z999AA10123456784" } ], "notifyCustomer": true}6. Custom Pages (Optional)
Wenn du deine Marketplace-App mit erweiterten UI/Flows ausbauen möchtest, nutze Custom Pages. Diese ermöglichen es, provider-spezifische Setups, erweiterte Einstellungen oder Dashboards innerhalb von ProfitBoost einzubetten und gleichzeitig den User-Kontext zu erhalten.
Typische Use Cases: Connection-Wizards, Verifikationsschritte, Shipping-Präferenzen, Carrier-Mapping, Troubleshooting-Seiten.
Authentifizierung/User Context: Übergib und validiere den User-Kontext gemäß Anleitung, um den installierenden User/Location sicher zu identifizieren.
Siehe: User context in Marketplace apps.
Fazit
Du hast nun ein kompaktes Blueprint für eine vollständige Dropshipping-Integration:
Marketplace App erstellen und OAuth konfigurieren
Produkt- und Preis-Sync über die APIs
Order Webhooks zur Übergabe an deinen Provider nutzen
Fulfillment Webhooks verarbeiten und zurück an ProfitBoost senden
Optional: UX mit Custom Pages erweitern
Nutze die verlinkten Dokumentationen für Details und Payload-Beispiele bei der Umsetzung der einzelnen Schritte.