Partner Order API

Dieses Dokument ersetzt das bisherige Turor-OMS-Paket (POST /restApi/v1/dropShippingOrder, GET /restApi/v1/dropShippingOrderItem/{id}). Diese Endpunkte und ihre HTTP-Basic-Zugangsdaten sind veraltet und dürfen nicht mehr verwendet werden. Die feldweise Zuordnung finden Sie in Anhang A am Ende dieser Seite.

---

Benötigen Sie diese API?

Die meisten Partner nicht. Wenn Sie WooCommerce oder Shopify einsetzen, verwenden Sie stattdessen unser Plugin — siehe WooCommerce oder Shopify. Entwickeln Sie nur dann gegen diese API, wenn Sie ein individuelles oder eigenes System betreiben.

Der Katalogimport sowie das Aktuellhalten von Beständen und Preisen wird separat in Catalog feed beschrieben.

Eine PDF-Fassung dieser Seite steht Ihren Entwicklern zur Verfügung: Partner Order API v1.0 (PDF).

1. Umgebungen

Alle Beispiele in diesem Dokument verwenden die Basis-URL der Produktionsumgebung. Tokens werden nicht zwischen Umgebungen geteilt — fragen Sie Ihren Account Manager nach einem Staging-Token, wenn Sie zuerst testen möchten.

---

2. Authentifizierung

Jede Anfrage führt Ihr Konto-Token als Bearer-Token mit:

Authorization: Bearer YOUR_ACCOUNT_TOKEN

Es ist dasselbe Token, das Sie für den Produktkatalog-Feed verwenden (GET /api/v1/feeds/catalog.csv). Sie finden es auf der Seite Account Ihres Cosmetic Wholesale Logins, zusammen mit Ihrer Feed-URL.

Hinweise:

• Das Token identifiziert Ihr Konto. Geben Sie es niemals in clientseitigem Code oder einem öffentlichen Repository preis.
• Tokens können jederzeit über Ihr Konto widerrufen und neu ausgestellt werden. Ein widerrufenes Token liefert 401.
• Es werden kein Benutzername und kein Passwort verwendet. Die alten HTTP-Basic-Zugangsdaten sind für die Bestellübermittlung nicht mehr gültig.
• X-Feed-Token: YOUR_ACCOUNT_TOKEN wird als alternativer Header akzeptiert.

---

3. Voraussetzungen

Eine Bestellung wird nur angenommen, wenn alle folgenden Bedingungen erfüllt sind:

1. Ihr Konto ist freigeschaltet und im Kanal dropshipping.
2. Ihr Dropshipping-Abonnement ist aktiv — andernfalls liefert jede Anfrage 403 subscription_required.
3. Ihr Wallet verfügt über ausreichendes Guthaben für die Bestellung — andernfalls wird die Bestellung angelegt und zurückgehalten (402, siehe Abschnitt 6).
4. Jede ean in der Bestellung existiert in Ihrem Katalog-Feed und ist auf Lager.

Produkttitel, Bilder und Preise senden Sie nicht — sie stammen aus unserem Katalog. Sie senden lediglich die EAN und die Menge.

---

4. Eine Bestellung anlegen

POST /dropshipping/orders

Request-Header

Authorization: Bearer YOUR_ACCOUNT_TOKEN
Content-Type: application/json

Request-Body

{
  "externalRef": "ORD123456",
  "payment": "WALLET",
  "shipping": {
    "firstName": "Name",
    "lastName": "LastName",
    "company": "TestCompany",
    "address1": "Main Street 123",
    "address2": "",
    "postcode": "1072 HM",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "",
    "email": "customer@example.com"
  },
  "lines": [
    { "ean": "6291107455365", "quantity": 2 },
    { "ean": "3607348816552", "quantity": 3 }
  ]
}

Felder

Aus Kompatibilitätsgründen werden snake_case-Aliase akzeptiert: external_ref, first_name, last_name, address_1, address_2 sowie qty für quantity.

Response

{
  "id": "8f1c0b2e-6a3d-4f21-9b7e-0c5a4d2e1f33",
  "externalRef": "ORD123456",
  "omsReference": "ds:usr_2f9a1c:ORD123456",
  "createdVia": "dropshipping-api",
  "status": "PAID",
  "walletDebited": true,
  "omsPushStatus": "pending",
  "omsOrderItemIds": [],
  "tracking": []
}

HTTP-Statuscodes

---

5. Idempotenz

externalRef ist der Idempotenzschlüssel. Dieselbe externalRef zweimal zu senden, legt niemals eine zweite Bestellung an und belastet Ihr Wallet niemals doppelt:

• War der erste Versuch erfolgreich, liefert der zweite 200 mit der bestehenden Bestellung.
• Wurde der erste Versuch wegen unzureichenden Guthabens zurückgehalten, wiederholt der zweite Versuch die Wallet-Zahlung und liefert 201/200, sobald das Guthaben ausreicht.

Dadurch kann der Endpunkt bei Timeouts und Netzwerkfehlern gefahrlos erneut aufgerufen werden. Wiederholen Sie stets mit derselben externalRef — erzeugen Sie niemals eine neue für dieselbe Kundenbestellung.

---

6. Unzureichendes Guthaben: der 402-HOLD-Kontrakt

Dieses Verhalten hat in der alten OMS-API keine Entsprechung und ist der häufigste Integrationsfehler.

Wenn Ihr Wallet die Bestellung nicht decken kann:

HTTP/1.1 402 Payment Required

{
  "id": "8f1c0b2e-6a3d-4f21-9b7e-0c5a4d2e1f33",
  "externalRef": "ORD123456",
  "status": "HOLD",
  "reason": "INSUFFICIENT_WALLET",
  "walletDebited": false,
  "omsPushStatus": null,
  "omsOrderItemIds": [],
  "tracking": []
}

Was das bedeutet:

• Die Bestellung existiert in unserem System und ist reserviert. Sie wird weder abgelehnt noch gelöscht.
• Es wurde nichts belastet.
• Es wurde noch nichts an das Lager übermittelt.

Was Ihr System tun muss:

• Stornieren oder löschen Sie die Bestellung nicht auf Ihrer Seite. Belassen Sie sie in einem offenen bzw. in Bearbeitung befindlichen Status.
• Laden Sie Ihr Wallet auf.
• Senden Sie dieselbe externalRef erneut per POST, oder warten Sie einfach ab: Zurückgehaltene Bestellungen werden automatisch erneut versucht, sobald das Guthaben ausreicht.
• Fragen Sie per GET nach, bis walletDebited den Wert true hat und status nicht mehr HOLD ist.

Eine Stornierung bei 402 ist genau das, was den Abgleich zerstört — die Bestellung bleibt bei uns reserviert, während Ihr System sie für fehlgeschlagen hält.

---

7. Eine Bestellung auslesen

GET /dropshipping/orders/{id}
GET /dropshipping/orders?externalRef=ORD123456

{id} akzeptiert entweder die Cosmetic Wholesale id (UUID) oder Ihre eigene externalRef. Beide Formen liefern denselben Body wie der Anlage-Aufruf. Bestellungen sind an Ihr Token gebunden — Sie können nur Ihre eigenen Bestellungen auslesen.

GET https://cosmeticwholesale.eu/api/v1/dropshipping/orders?externalRef=ORD123456
Authorization: Bearer YOUR_ACCOUNT_TOKEN

Werte des Bestellstatus

---

8. Sendungsverfolgung

Die Sendungsverfolgung wird über denselben GET als Array zurückgegeben (eine Bestellung kann in mehreren Paketen versendet werden):

{
  "id": "8f1c0b2e-6a3d-4f21-9b7e-0c5a4d2e1f33",
  "externalRef": "ORD123456",
  "status": "SHIPPED",
  "walletDebited": true,
  "omsPushStatus": "pushed",
  "omsOrderItemIds": ["418224", "418225", "418226"],
  "tracking": [
    {
      "provider": "postnl-3s",
      "trackingNumber": "3SXXXX00000000",
      "dateShipped": "2026-05-06T17:39:20.000Z"
    }
  ]
}

Fragen Sie höchstens einmal pro Stunde und Bestellung ab. Fragen Sie keine Bestellungen ab, die bereits COMPLETED, CANCELLED oder REFUNDED sind.

---

9. Fehlercodes

Fehler werden als { "error": "<message>", "code": "<code>" } zurückgegeben.

---

10. Beispiele

cURL — anlegen

curl -X POST https://cosmeticwholesale.eu/api/v1/dropshipping/orders \
  -H "Authorization: Bearer YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "ORD123456",
    "shipping": {
      "firstName": "Name",
      "lastName": "LastName",
      "address1": "Main Street 123",
      "postcode": "1072 HM",
      "city": "Amsterdam",
      "country": "NL"
    },
    "lines": [
      { "ean": "6291107455365", "quantity": 2 }
    ]
  }'

cURL — auslesen

curl "https://cosmeticwholesale.eu/api/v1/dropshipping/orders?externalRef=ORD123456" \
  -H "Authorization: Bearer YOUR_ACCOUNT_TOKEN"

PHP — anlegen

<?php

$token = 'YOUR_ACCOUNT_TOKEN';
$url   = 'https://cosmeticwholesale.eu/api/v1/dropshipping/orders';

$payload = [
    'externalRef' => 'ORD123456',
    'shipping' => [
        'firstName' => 'Name',
        'lastName'  => 'LastName',
        'address1'  => 'Main Street 123',
        'postcode'  => '1072 HM',
        'city'      => 'Amsterdam',
        'country'   => 'NL',
    ],
    'lines' => [
        ['ean' => '6291107455365', 'quantity' => 2],
    ],
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$order = json_decode($response, true);

if ($status === 402) {
    // Held for insufficient wallet balance.
    // Keep your order open and retry with the SAME externalRef after topping up.
} elseif ($status === 201 || $status === 200) {
    // Accepted. Store $order['id'] and poll for tracking.
}
?>

PHP — auslesen

<?php

$token       = 'YOUR_ACCOUNT_TOKEN';
$externalRef = 'ORD123456';
$url = 'https://cosmeticwholesale.eu/api/v1/dropshipping/orders/' . rawurlencode($externalRef);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $token]);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

---

Anhang A — Migration von den Turor-OMS-Endpunkten

Das alte Paket verwies auf https://omsback.turor.org/restApi/v1 mit HTTP-Basic-Zugangsdaten. Diese Zugangsdaten gehörten zu einem gemeinsam genutzten Systemkonto und umgingen die Wallet-, Bestands- und Abonnementebene. Sie werden nicht mehr ausgegeben, und bestehende werden zurückgezogen.

Endpunkte

Request-Felder

Response-Felder

Verhaltensänderungen, die Sie in Ihrem Code prüfen sollten

1. 402 ist kein Fehlschlag. Die alte API hatte keine Wallet-Ebene. Behandeln Sie 402 als "zurückgehalten, erneut mit derselben Referenz versuchen" — niemals als "Bestellung stornieren".
2. Wiederholungen sind sicher. externalRef dedupliziert; die alte Prüfung auf orderCreated: 0 wird durch die Unterscheidung zwischen 200 und 201 ersetzt.
3. Die Sendungsverfolgung ist zur Bestellung gewandert. Ein GET pro Bestellung ersetzt ein GET pro Position, und das Ergebnis ist ein Array.
4. Die Produktdaten gehören uns. Senden Sie keine Titel und Bild-URLs mehr.