Die erste Bestellung

Dieser Ablauf legt eine Bestellung an. Du brauchst einen API-Schlüssel mit merchant_order:read (Vorschau und Abfrage) und merchant_order:create (Anlage).

1. Bestellung vorbereiten

Speichere den Inhalt als order.json. Die SKU und die Motiv-URL ersetzt du durch eigene Werte.

{
  "external_reference": "SHOP-10045",
  "delivery_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "house_number": "1",
    "postcode": "50667",
    "city": "Köln",
    "country": "DE",
    "email": "[email protected]"
  },
  "billing_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "house_number": "1",
    "postcode": "50667",
    "city": "Köln",
    "country": "DE",
    "email": "[email protected]"
  },
  "items": [
    {
      "sku": "TSHIRT-SCHWARZ-M",
      "external_id": "LINE-1",
      "amount": 2,
      "processings": [
        {
          "processing_type": "DTG",
          "position": "FRONT",
          "design_url": "https://example.com/designs/motiv-001.png"
        }
      ]
    }
  ]
}

Preise, Versandart und Hersteller sendest du nicht mit. Preise stammen aus dem Katalog, alles Übrige legt das System fest. Andere als die im Schema genannten Felder lehnt die API mit 403 ab. Eine Position mit amount 2 wird als zwei einzelne Stücke angelegt.

2. Vorschau

curl -X POST https://gateway.shirtee.cloud/api/orders/preview \
  -H "Authorization: Bearer $SHIRTEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @order.json

Die Vorschau schreibt nichts. Bei einem Fehler in den Angaben antwortet sie mit 422 und einem Code in extra.error, zum Beispiel UNKNOWN_SKU oder VARIANT_INACTIVE. Mehr dazu unter Vorschau vor Änderungen.

3. Anlegen

curl -X POST https://gateway.shirtee.cloud/api/orders \
  -H "Authorization: Bearer $SHIRTEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @order.json

Speichere den Idempotency-Key bei deiner Bestellung. Bei einem Timeout wiederholst du mit demselben Key und demselben Inhalt, es entsteht keine zweite Bestellung, siehe Bestellungen sicher wiederholen.

Die Antwort (201) enthält die Bestellung im Status direkt nach der Anlage, zum Beispiel:

{
  "id": 900001,
  "slug": "CL-7K3M9QX",
  "external_reference": "SHOP-10045",
  "status": "PENDING",
  "retention": null
}

Merke dir id. Sie adressiert die Bestellung in allen weiteren Aufrufen.

4. Status deuten

Normalerweise lautet der Status PENDING, danach läuft die Verarbeitung automatisch weiter. Je nach Prüfergebnis kann direkt nach der Anlage ein anderer Status stehen:

Status	Bedeutung
`PENDING`	Angelegt, die Verarbeitung startet automatisch
`PAUSE`	Kurze Wartezeit vor der Zuweisung
`CHECK`	Die Bestellung braucht eine Prüfung, zum Beispiel wegen einer inaktiven Variante oder weil kein Produktionspartner verfügbar ist. `retention` nennt den Grund.
`ERROR`	Ein Fehler hält die Bestellung an, zum Beispiel fehlende Preise. `retention` nennt den Grund.

CHECK und ERROR sind kein HTTP-Fehler: Die Bestellung existiert. Die Referenz der Operation POST /api/orders beschreibt alle Fälle.

5. Bestellung abfragen

curl "https://gateway.shirtee.cloud/api/orders/900001?tracking=true" \
  -H "Authorization: Bearer $SHIRTEE_API_KEY"

Mit tracking=true enthält die Antwort die Sendungen (Tracking-Nummer, Link, Versanddienstleister). Ohne den Parameter ist die Liste leer.

Hast du deine eigene Nummer vergeben, findest du die Bestellung auch darüber: GET /api/orders/by-external-reference/{external_reference}.