×

anpa# STOCKSQUARE Dokumentation

Order Event-API

Letzte Änderung: 09.05.2022

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 Ereignisse werden aktuell von der Order Event-API bereitgestellt:

Ü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:

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"
      },
      "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"
        }
      ]
    }
  ]
}

Zuweisung einer Bestellung zu einer Filiale (CLAIM)

Ein CLAIM Event wird immer dann erzeugt, wenn eine ode 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"
        }
      ]
    }
  ]
}

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!

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"
        }
      ]
    }
  ]
}

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"
        }
      ]
    }
  ]
}

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
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 are optional.
shipping shipping address addressAddition & email are optional.
order_items list of ordered items

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)

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
Szenario 2
Szenario 3

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
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)