STOCKSQUARE Dokumentation

Order Event-API

Letzte Änderung: 27.02.2023

Willkommen bei der Dokumentation der Stocksquare Order Event-API. Mit dieser API erhalten Sie Benachrichtigungen über neu eingegangene Bestellungen sowie Statusänderungen zu bereits vorhandenen Bestellungen.

Die Order Event-API beruht auf der Ausgabe von Ereignissen, die Stocksquare Ihnen zur Verfügung stellt und durch Ihr System im Sinne Ihrer Geschäftslogiken verarbeitet werden kann.

Hinweis: Die Order Event-API unterstützt aktuell nur die Übermittlung von Events durch Stocksquare. Zu einem späteren Zeitpunkt wird die API auch die Auslösung von Statusänderung durch Ihre Systeme unterstützen.

Event Typen

Order Events

Nachfolgende Event-Typen werden aktuell von der Order Event-API bereitgestellt:

CREATE Eine neue Bestellung liegt von einem Marktplatz vor
CLAIM Artikel einer Bestellung wurden einer Filiale bzw. einem Warenlager zugewiesen
UNCLAIM Die Zuordnung von Artikel einer Bestellung zu einer Filiale bzw. einem Warenlager wurde wieder aufgehoben.
CANCEL Artikel einer Bestellung wurden als storniert an den Marktplatz übermittelt
FULFILL Eine Bestellung wurde vollständig oder in Teilen an den Kunden versendet
RETURN Eine Rücksendung wurde erfasst und an den Marktplatz übermittelt

Hinweis: Eine Reduktion der Event-Typen kann individuell vereinbart werden. Im Standard werden alle Event-Typen übermittelt.

Übertragung von Events

Events werden erst bei Stocksquare gespeichert und können dann per HTTP Webhook oder per SFTP Upload bereitgestellt werden.

Das Format der Dateien bzw. des Webhook Body ist dabei identisch:

{
  "events" : [
    {EVENT1},
    {EVENT2}
    ...
  ]
}

HTTP Webhook

Für die Nutzung des Webhooks müssen ein HTTPS Endpunkt sowie ein API Key für diesen Endpunkt bereitgestellt werden. Der API Key wird als HTTP Header “x-api-key” übertragen. Die Events selbst werden per PUT Request an den Endpunkt übertragen.

Es werden maximal 10 Events pro Request übertragen, der Request Timeout beträgt 5 Sekunden. Sollte der Endpunkt innerhalb dieses Zeitfensters den Erhalt der Events nicht mit 200 OK oder 201 CREATE bestätigen, wird in folgenden Intervallen versucht, die Events erneut zu pushen:

1. retry: 10 Minuten
2. retry: 1 Stunde
3. retry: 4 Stunden
4. retry: 8 Stunden
5. retry: 16 Stunden
6. retry: 24 Stunden
7. retry: 36 Stunden
8. retry: 48 Stunden
9. retry: 72 Stunden
10. retry: 96 Stunden

Alle Events werden immer in der Reihenfolge der Entstehung übertragen. Schlägt eine Übertragung fehl, blockiert diese auch die Übertragung nachfolgender Events. Nach Auflösung der Störung werden alle bis dahin zurückgehaltenen Events in Paketen von maximal 10 Events pro Request übertragen. Erneute Übertragungsversuche von Events erfolgen immer mit der ursprünglichen event_id, sodass doppelte Verarbeitungen vermieden werden können.

Hinweis: Falls eine Verarbeitung der Events bis zum Ablaufen des Timeouts nicht zuverlässig garantiert werden kann, wird eine Zwischenspeicherung der erhaltenen Events mit nachgelagerter Verarbeitung empfohlen.

SFTP

Für die Nutzung über SFTP muss ein SFTP Account bereitgestellt werden, auf diesen werden dann die Events als *.json Dateien Abgelegt. Eine Datei enthält maximal 100 Events.

Beispiel Benachrichtigungen für die einzelnen Ereignistypen

Hinweis: Die über die Order Event-API bereitgestellten Daten sind teilweise abhängig von den Daten der Marktplätze. Insbesondere personenbezogene Daten, die für die Ausführung einer Bestellung nicht zwingen erforderlich sind, werden nicht von allen Marktplätzen zur Verfügung gestellt.

WARNUNG: Falls Sie für die Ermittlung des verfügbaren Bestands auch Bestellungen im Status “NEW” berücksichtigen, können aktuell Stornierungen für Artikel automatisiert erfolgen, da Stocksquare intern auch mit virtuellen Bestandsreduzierungen arbeitet. Bitte sprechen Sie uns an, um hier eine Lösung abstimmen zu können.

Eingang einer neuen Bestellung (CREATE)

Im CREATE Event werden alle verfügbaren Informationen einer neuen Bestellung übertragen. Im Bereich der Rechnungs- und Lieferanschrift sind die E-Mailadresse und der Adresszusatz als optional anzusehen, da diese nicht für jede Bestellung vorliegen.

Beispiel JSON Payload für ein CREATE Event (enthält alle items):

{
  "events": [
    {
      "retailer": "1111",
      "shop": "VS",
      "marketplace": "otto.de",
      "state": "NEW",
      "timestamp": "2021-10-29T12:36:09+0200",
      "event_id": "181b085b-118d-40e5-9ea9-ae84cc9b47ea",
      "event_type": "CREATE",
      "original_marketplace_ordernumber": "hjn1xx2dm1",
      "ccp_order_id": "300250393",
      "order_timestamp": "2021-10-29T12:34:57+0200",
      "invoice": {
        "firstName": "Max",
        "lastName": "Tester",
        "street": "Heegbarg",
        "houseNo": "30",
        "addressAddition": "Adresszusatz Rechnung",
        "city": "Hamburg",
        "postalCode": "22391",
        "country": "DE",
        "email": "max.tester@test.de",
        "marketplace_customer_id"  : "1077529"
      },
      "shipping": {
        "firstName": "Max",
        "lastName": "Tester",
        "street": "Heegbarg",
        "houseNo": "30",
        "addressAddition": "Adresszusatz Paketlabel",
        "city": "Hamburg",
        "postalCode": "22391",
        "country": "DE",
        "email": "max.tester@test.de"
      },
      "order_items": [
        {
          "position": 1,
          "ean": "4047393517957",
          "quantity": 1,
          "state": "NEW",
          "ccp_item_id": "7001111111",
          "article_number": "12345ABCD",
          "single_price": 4.99,
          "gross_price": 4.99,
          "currency": "EUR"
        }
      ],
      "shipping_costs" : 2.95
    }
  ]
}

Zuweisung einer Bestellung zu einer Filiale (CLAIM)

Ein CLAIM Event wird immer dann erzeugt, wenn ein oder mehrere Artikel einer Bestellung einer Filiale oder einem Warenlager zugeordnet wurden. Dieser Prozess kann mehrfach für einzelne oder alle Artikel einer Bestellung durchlaufen werden, wenn z.B. ein Artikel in einer Filiale nicht gefunden wird. Bislang wird nur die nun gültige Filialzuordnung im CLAIM Event übertragen.

Beispiel JSON Payload für ein CLAIM Event:

{
  "events": [
    {
      "retailer": "1111",
      "shop": "VS",
      "marketplace": "otto.de",
      "state": "WORK",
      "timestamp": "2021-10-29T12:40:26+0200",
      "event_id": "2786fca1-1e7a-495d-a7fd-d934693d106c",
      "event_type": "CLAIM",
      "original_marketplace_ordernumber": "yop9w7gz3a",
      "ccp_order_id": "300000000.76829255",
      "order_timestamp": "2021-10-29T12:34:57+0200",
      "order_items": [
        {
          "position": 1,
          "ean": "4047393517957",
          "quantity": 1,
          "state": "WORK",
          "claim": [
            {
              "shop": "SHOP1",
              "claimed_quantity": 1
            }
          ],
          "ccp_item_id": "7001111111",
          "article_number": "12345ABCD",
          "single_price": 4.99,
          "gross_price": 4.99,
          "currency": "EUR"
        }
      ],
      "shipping_costs" : 2.95
    }
  ]
}

Hinweis: Falls Artikel einer Bestellung erneut zugeordnet werden müssen, werden für die betroffenen Bestellpositionen erneute CLAIM Events mit der neuen Zuordnung ausgelöst. Dies umfasst auch Situationen, in denen die erneute Zuordnung der bisherigen entspricht.

Hinweis: Stocksquare erwartet, dass ein nach der Übertragung des CLAIM Events erzeugter Bestandsfeed alle offenen und bereits zugeordneten Bestellungen berücksichtigt. Falls dies nicht möglich ist, sprechen Sie uns bitte an!

Aufhebung der Zuweisung einer Bestellung zu einer Filiale (UNCLAIM)

Ein UNCLAIM Event kann optional immer dann erzeugt werden, wenn die Zuweisung von einem oder mehreren Artikeln einer Bestellung zu einer Filiale oder einem Warenlager wieder aufgehoben wird. Betroffene Auftragspositionen befinden sich dadurch erneut im Auftragspool und können von dort erneut einer Filiale oder einem Warenlager zugeordnet werden. Falls entsprechende Auftragspositionen nicht erfüllbar sind, kann eine Stornierung der Auftragsposition im Anschluss erfolgen.

Beispiel JSON Payload für ein UNCLAIM Event:

{
  "events": [
    {
      "retailer": "1111",
      "shop": "VS",
      "marketplace": "otto.de",
      "state": "WORK",
      "timestamp": "2021-10-29T12:40:26+0200",
      "event_id": "2786fca1-1e7a-495d-a7fd-d934693d106c",
      "event_type": "UNCLAIM",
      "original_marketplace_ordernumber": "yop9w7gz3a",
      "ccp_order_id": "300000000.76829255",
      "order_timestamp": "2021-10-29T12:34:57+0200",
      "order_items": [
        {
          "position": 1,
          "ean": "4047393517957",
          "quantity": 1,
          "state": "WORK",
          "claim": [
            {
              "shop": "SHOP1",
              "claimed_quantity": -1
            }
          ],
          "ccp_item_id": "7001111111",
          "article_number": "12345ABCD",
          "single_price": 4.99,
          "gross_price": 4.99,
          "currency": "EUR"
        }
      ],
      "shipping_costs" : 2.95
    }
  ]
}

Stornierung einer Bestellung (CANCEL)

Beispiel JSON Payload für ein CANCEL Event:

{
  "events": [
    {
      "retailer": "1111",
      "shop": "VS",
      "marketplace": "otto.de",
      "state": "WORK",
      "timestamp": "2021-10-29T12:39:09+0200",
      "event_id": "cfd7de5e-28a3-4a09-b6f4-6b1757928158",
      "event_type": "CANCEL",
      "original_marketplace_ordernumber": "hjn1xx2dm1",
      "ccp_order_id": "300250393",
      "order_timestamp": "2021-10-29T12:34:57+0200",
      "order_items": [
        {
          "position": 2,
          "ean": "4047393517958",
          "quantity": 1.0,
          "state": "CANCEL",
          "ccp_item_id": "7001111112",
          "article_number": "23456BCDE",
          "single_price": 4.99,
          "gross_price": 4.99,
          "currency": "EUR",
          "cancelled_quantity": 1
        }
      ]
    }
  ]
}

Versand einer Bestellung (FULFILL)

Beispiel JSON Payload für ein FULFILL Event:

{
  "events": [
    {
      "retailer": "1111",
      "shop": "VS",
      "marketplace": "otto.de",
      "state": "FULFILL",
      "timestamp": "2021-10-29T12:40:26+0200",
      "event_id": "2786fca1-1e7a-495d-a7fd-d938e93d106c",
      "event_type": "FULFILL",
      "original_marketplace_ordernumber": "yop9w7gz3a",
      "ccp_order_id": "300000000.76829255",
      "order_timestamp": "2021-10-29T12:34:57+0200",
      "order_items": [
        {
          "position": 1,
          "ean": "4047393517957",
          "quantity": 1,
          "state": "FULFILL",
          "delivery": [
            {
              "shop": "SHOP1",
              "carrier": "dhlpaket",
              "return_carrier": "dhlpaket",
              "tracking_code": "00844382369942849400",
              "return_tracking_code": "00569469227384865860"
            }
          ],
          "ccp_item_id": "7001111111",
          "article_number": "12345ABCD",
          "single_price": 4.99,
          "gross_price": 4.99,
          "currency": "EUR"
        }
      ],
      "shipping_costs" : 2.95
    }
  ]
}

Hinweis: Im Zuge eines FULFILL-Events wird in der Regel der Status aller Items einer Bestellung übertragen, auch wenn bislang (noch) nicht alle Artikel versendet oder einzelne Artikel storniert wurden. Für stornierte Artikel erfolgt die erneute Übertragung eines Events vom Typ CANCEL. Dieses unterscheidet sich nur im Status der Bestellung.

Erfassung einer Rücksendung (RETURN)

Beispiel JSON Payload für ein RETURN Event:

{
  "events": [
    {
      "retailer": "1111",
      "shop": "VS",
      "marketplace": "otto.de",
      "state": "RETURN",
      "timestamp": "2021-10-29T12:41:08+0200",
      "event_id": "0550b84a-d38d-429c-a479-497b34aae2e4",
      "event_type": "RETURN",
      "original_marketplace_ordernumber": "r7sbv5y827",
      "ccp_order_id": "300000000.16698605",
      "order_timestamp": "2021-10-29T12:34:57+0200",
      "order_items": [
        {
          "position": 1,
          "ean": "4047393517957",
          "quantity": 1,
          "state": "RETURN",
          "ccp_item_id": "7001111111",
          "article_number": "12345ABCD",
          "single_price": 4.99,
          "gross_price": 4.99,
          "currency": "EUR",
          "return_quantity": 1,
          "return_reason": "in_original_packaging"
        }
      ],
      "shipping_costs" : 2.95
    }
  ]
}

Schema

Order

name	description	values
event_id	unique id for an event
event_type	type of the event	CREATE, CANCEL, FULFILL, RETURN (in the future also: ANNOUNCED)
retailer	unique id for a retailer provided by Stocksquare
shop	ID of the shop on the marketplace (VS = virtual store)
marketplace	origin of the order	otto.de, limango.de, aboutyou.de, amazon.de
original_marketplace_ordernumber	original identifier referring to the order provided by the marketplace
ccp_order_id	identifier referring to the order provided by Stocksquare (guaranteed unique).
state	current state of this order	NEW, CANCEL, WORK, FULFILL, RETURN - NEW: A new received order. - CANCEL: The whole order is canceled. - WORK: The order waits to be shipped. Some order items may have already been shipped or cancelled. - FUFILL: The order is completely fulfilled. Individual order items may have been cancelled or returned. - RETURN: The order is fully returned.
timestamp	timestamp of this event
order_timestamp	timestamp of the order provided by the marketplace
invoice	invoice recipient	addressAddition, email and marketplace_customer_id are optional.
shipping	shipping address	addressAddition & email are optional.
order_items	list of ordered items
shipping_costs	shipping_costs per order (only provided for values greater than 0)

order_item

name	description	values
position	order line item position
ccp_item_id	SKU provided by Stocksquare
article_number	SKU provided by the retailer
ean	EAN
quantity	order quantity	Currently always 1. If a future supported marketplace should provide values greater than 1, Stocksquare will adjust the API if necessary. If you want to sell divisible products, a double would also be possible here.
state	state of the order line item	NEW, CANCEL, FULFILL, RETURN - NEW: A new received order item - CANCEL: The order item is canceled. - WORK: The order item waits to be shipped. - FUFILL: The order item is fulfilled. - RETURN: The order item is returned.
single_price	selling price per unit
gross_price	selling price of the order item position
currency	currency
cancelled_quantity	cancelled quantity (only provided for cancelled order line items)
return_quantity	received and accepted returned quantity (only provided for returned order items)
return_reason	return reason submitted to the marketplace or condition of the item (only provided for returned order items)
delivery	list of delivery informations (multiple values if delivered in multiple packages from one location)n
shipping_costs	shipping_costs per order (only provided for values greater than 0)

claim

name	description	values
shop	shopId of the assigned location
claimed_quantity	assigned quantity

delivery

name	description	values
shop	shopId of the supplying location
carrier	carrier for the delivery	dhlpaket: DHL Paketversand
tracking_code	tracking code for the delivery
return_carrier	carrier for the return	dhlpaket: DHL Paketversand
return_tracking_code	tracking code for the return

Testsuite

Für die Anbindung an die Stocksquare Order Event-API steht Ihnen unsere Postman-Testsuite mit mehreren Testszenarien zur Verfügung:

Download Testsuite

Testszenarien

Szenario 1

Schritt 1: Bestellung eines Artikels
Schritt 2: Zuweisung eines Artikels zu einer Filiale
Schritt 3: Auslieferung eines Artikels in einem Paket
Schritt 3: Rücksendung eines Artikels

Szenario 2

Schritt 1: Bestellung von 2 Artikeln
Schritt 2: Zuweisung eines Artikels zu einer Filiale
Schritt 3: Stornierung eines Artikels (durch die Filiale oder durch das System)
Schritt 4: Auslieferung des weiteren Artikels in einem Paket
Schritt 5: Rücksendung eines Artikels

Szenario 3

Schritt 1: Bestellung von 3 Artikeln
Schritt 2: Zuweisung der Artikelel zu 2 unterschiedlichen Filialen
Schritt 3: Auslieferung der Artikel in 3 Paketen durch 2 Filialen

Konfiguration der Testsuite

Nachfolgende Variablen der Collection "Stocksquare Order Event API V1" erlauben eine leichte Anpassung:

variable	description	example values
RetailerWebHookURL	webhook url	`https://mysite.de/stocksquare-event-api/`
apiKey	your selected api key	TestApiKey
article_number1 ... article_number3	SKU article 1 to 3	12345ABCD
ean1 ... ean3	EAN article 1 to 3	4047393517957
price1 ... price3	price article 1 to 3	19.99
deliveringShopId1 ... 3	GLN, ShopId	SHOP1

Änderungshistorie

Datum	Änderung
27.02.2023	Erweiterung Event-Digramm um Zustandsübergänge
13.12.2022	Erweiterung um die Marktplätze aboutyou.de und amazon.de.
13.12.2022	Erweiterung von CREATE-Events um die Marktplatzkundennummer, falls diese vom Marktplatz bereitgestellt wird.
14.10.2022	Korrektur Postman Testsuite
11.08.2022	UNCLAIM-Events stehen nun zur Verfügung.
18.06.2022	Optionales UNCLAIM-Event ergänzt. Das UNCLAIM-Event kann im Verlauf des Juli 2022 bereitgestellt werden.
09.06.2022	Optionale Angabe der Versandkosten einer Bestellung in den Events ergänzt.
09.05.2022	Details zur Erzeugung von CLAIM Events ergänzt.
04.05.2022	Übertragungsverhalten via HTTP Webook detailliert
28.04.2022	Korrektur der Timestamps in allen Events (+0200 anstatt +02:00)
25.03.2022	Detaillierend des Verhaltes bei Übertragungsfehlern und zusätzliche Erläuterungen zur Quantity ergänzt.
24.03.2022	Benennung optionaler Attribute im CREATE-Event
02.02.2022	Artikelpreise in CANCEL-Events ergänzt und Testsuite aktualisiert
31.01.2022	Ergänzung von CLAIM-Events bei Zuweisung von Bestellpositionen zu einer Filiale bzw. einem Lager
15.11.2021	Korrektur Dokumentation & Testsuite V1: Eventübertragung über HTTPS erfolgt mittels PUT- anstelle von POST-Requests.
05.11.2021	Ergänzung Testsuite V1
04.11.2021	Ergänzung Hinweis zur erneuten Übertragung von CANCEL-Events bei Auslieferungen.
29.10.2021	Initiale Fassung (Erweiterter Konzeptionsstand)