Zum Inhalt

Übersicht

Der NoyesStorage ist so konzipiert, dass er eigenständig über die NoyesStorage App betrieben werden kann; eine Integration ist nicht erforderlich. Soll der NoyesStorage automatisiert mit anderen Systemen kommunizieren, steht eine Schnittstelle (engl. Application Programming Interface, API) zur Verfügung. Dieser Abschnitt bietet eine Schnellstartanleitung für die Integration des NoyesStorage über seine API, etwa für folgende Anwendungsfälle:

  • die Übergabe von Bestelldaten aus einem Online-Shop an den NoyesStorage,
  • das automatische Drucken von Rechnungen, wenn Kundenaufträge kommissioniert werden, und
  • die Synchronisation des ERP-Systems mit den Lagerbeständen im NoyesStorage.

Die NoyesStorage-API basiert auf REST, verwendet das JSON-Datenformat für Anfragen und Antworten und nutzt gängige HTTP-Methoden (siehe Tabelle unten). Integrationen nutzen die öffentliche REST-API unter /api/v2/… (OpenAPI unter /api/openapi.json), z. B. POST /api/v2/requests für Abruf-, Kommissionier- und Nachschubaufträge.

Alle verfügbaren Endpunkte, Anfragemodelle und Parameter finden Sie in der API-Endpunktreferenz. Die interaktive API-Dokumentation des jeweiligen NoyesStorage ist außerdem unter /api erreichbar.

HTTP Kommunikation in der NoyesStorage API

Methode Erklärung
POST Neue Ressourcen anlegen oder Daten an den NoyesStorage senden (z. B. eine Fulfillment-Anfrage übermitteln). Beispiel: /api/v2/requests
GET Daten aus dem NoyesStorage abrufen (z. B. den Status von Anfragen prüfen). Beispiel: /api/v2/requests
PUT Bestehende Ressourcen aktualisieren.
DELETE Ressourcen aus dem NoyesStorage entfernen.

Standard HTTP Antworten und Status der NoyesStorage API

Status Erklärung
200 OK Die Anfrage war erfolgreich.
201 Created Eine neue Ressource wurde erfolgreich angelegt.
202 Accepted Die Anfrage wurde angenommen und wird asynchron verarbeitet.
400 Bad Request Die Anfrage wurde abgelehnt, zum Beispiel weil sie eine Geschäftsregel verletzt. Die Antwort beschreibt den Grund.
401 Unauthorized Eine Authentifizierung ist erforderlich.
403 Forbidden Dem authentifizierten Aufrufer fehlt die erforderliche Berechtigung.
404 Not Found Die angeforderte Ressource existiert nicht.
409 Conflict Die Anfrage passt nicht zum aktuellen Zustand, zum Beispiel weil sich ein Job oder die Kapazität inzwischen geändert hat. Fragen Sie den aktuellen Zustand erneut ab.
422 Unprocessable Entity Die Eingabe wurde nicht verarbeitet, zum Beispiel wegen eines unbekannten Felds, eines falschen Datentyps oder einer unzulässigen Belegung. Nur bei Fehlern im Aufbau der Anfrage nennt die Antwort die betroffenen Felder. Bei einer unzulässigen Belegung prüfen Sie den aktuellen Zustand, bevor Sie die Anfrage wiederholen.
500 Internal Server Error Auf dem Server ist ein Fehler aufgetreten.

Ablehnung wegen gegenläufiger Requests (0x5089)

Für SKUs mit dem Verhalten bei Leerstand Zuweisung aufheben (on_empty_sku_action: UNASSIGN) lehnt der NoyesStorage gegenläufige Anfragen für dieselbe SKU ab: eine Fulfillment-Anfrage, solange eine Putaway- oder Replenishment-Anfrage für die SKU offen ist, sowie eine Replenishment-Anfrage bei offenem Fulfillment. Putaway prüft dagegen die Sicherheit seiner konkreten Ziele und kann parallel zu Fulfillment angelegt werden. Die Regel und ihre Ausnahmen beschreibt Management von SKUs.

Fulfillment- und Replenishment-Anfragen werden dann mit 400 Bad Request abgelehnt. Die betroffene Position trägt in detail.entity_feedback den Fehlercode 0x5089:

{
  "detail": {
    "request_id": "order-4711",
    "entity_feedback": [
      {
        "sku_id": "sku-a",
        "error_code": "0x5089",
        "human_string": "Request cannot be performed for entity: 'sku-a'. SKU has an outstanding putaway request."
      }
    ]
  }
}

Putaway-Anfragen und die Putaway-Vorschau schließen bei Zuweisung aufheben Beladungen als Auffüllziel aus, die durch ausstehende interne Entnahmen leer werden können. Andere Ziele bleiben entsprechend den Anfrageoptionen verfügbar. Ist keine vollständige sichere Belegung möglich, meldet die Antwort NOT_ALLOCATABLE_UNDER_CURRENT_POLICY.

Die gesamte Anfrage wird nicht angelegt. Senden Sie sie erneut, sobald die gegenläufige Anfrage abgeschlossen oder abgebrochen ist. Werten Sie dafür den Fehlercode bzw. Fehlerschlüssel aus, nicht den Meldungstext.

API-Key verwalten

API-Keys erhalten eigene API-Berechtigungen und keine App-Rolle. Sie erlauben keinen Zugriff auf App-Seiten. Die Auswahl wird unter Rollen und Berechtigungen mit einer Animation erläutert. Änderungen an einer Benutzerrolle ändern nicht die separat gespeicherte Berechtigungsauswahl eines API-Keys.

Berechtigungen

Die Standardrollen Admin und Super Admin können API-Keys anzeigen, erstellen, bearbeiten und löschen. Bei benutzerdefinierten Rollen hängen die verfügbaren Aktionen von den zugewiesenen API-Key-Berechtigungen ab.

So erstellen Sie einen API-Key:

  1. Öffnen Sie in der NoyesStorage App Einstellungen > API-Key.
  2. Wählen Sie API-Key hinzufügen.
  3. Geben Sie einen aussagekräftigen Namen ein.
  4. Wählen Sie nur die API-Berechtigungen aus, die die Integration benötigt. Ein neuer API-Key hat zunächst keine Berechtigungen. Sie können nur Berechtigungen vergeben, die Sie selbst besitzen.
  5. Legen Sie die Gültigkeitsdauer fest. Das vorausgewählte Ablaufdatum liegt 30 Tage nach der Erstellung. Sie können stattdessen ein anderes zukünftiges Datum wählen oder Kein Ablaufdatum aktivieren.
  6. Wählen Sie erneut API-Key hinzufügen und kopieren Sie den erstellten Schlüssel in das Zielsystem.

Um die Berechtigungen eines bestehenden API-Keys zu ändern, wählen Sie den Schlüssel in der Tabelle und anschließend Bearbeiten. Nicht mehr benötigte oder möglicherweise kompromittierte Schlüssel löschen Sie über API-Key löschen.

Für Integrationen, die die Bearbeitungsreihenfolge selbst bestimmen, gibt es die API-Berechtigung api.jobs.confirmOutOfOrder (Freie Bestätigung). Sie erlaubt die Bestätigung jedes EXECUTING-Jobs über POST /v2/trigger/{job_id}, auch wenn er in seinem Sequenzbereich noch nicht an der Reihe ist. Andere Job-Status bleiben gesperrt. Bei PUTAWAY muss die ID des tatsächlich gewählten ausführenden Jobs verwendet werden; die geplante Entity eines Jobs wird dadurch nicht geändert.

Diese Berechtigung ist bei keinem API-Key vorausgewählt und muss ausdrücklich zusätzlich zu api.jobs.trigger vergeben werden. Admin und Super Admin erhalten dafür die Rollenberechtigung API-Keys freie Bestätigung erlauben (api_keys.grant_loose_confirmation). Anderen Rollen kann diese Rollenberechtigung gezielt zugewiesen werden; die Berechtigung zur API-Key-Verwaltung allein genügt dafür nicht. Bestehende API-Keys werden dadurch nicht erweitert.

Carrier-Bewegung, automatische Auswahl, Scanner-Auswahl und die Markierung des nächsten Jobs behalten ihre Reihenfolge. Ohne diese Berechtigung wird eine Bestätigung außerhalb der Reihenfolge mit HTTP 409 und der ID des nächsten Jobs abgelehnt. Bei ausgeschalteter Sequenzierung bleibt die strikte Bestätigungsregel nur an Standorten mit betriebsbereitem Aufzug wirksam. Die ausdrückliche freie Bestätigung gilt unabhängig vom Sequenzbereich. Siehe auch die Sequenzierungsregeln.

Benutzer wählen unabhängig davon im Anfrage-Dashboard unter Bestätigung zwischen Strikt (Vorgabe) und Frei. Diese persönliche Einstellung erlaubt die manuelle Auswahl eines anderen ausführenden Jobs, auch bei der PUTAWAY-SKU-Auswahl.

API-Keys ohne Ablaufdatum

Verwenden Sie Kein Ablaufdatum nur, wenn ein regelmäßiger Austausch des API-Keys technisch nicht möglich ist. Prüfen Sie solche Schlüssel regelmäßig und ersetzen Sie sie, sobald sie nicht mehr benötigt werden.

In der Animation ist im Suchfeld Search API permissions der Text api.inventory. eingetragen. Er filtert die verfügbaren API-Berechtigungen nach ihrem technischen Schlüssel auf den Bereich Inventar; ausgewählt wird über die Kontrollkästchen. Löschen Sie den Suchtext, um wieder alle verfügbaren Berechtigungen anzuzeigen.

API-Berechtigungen im Erstellungsdialog gezielt auswählen

Authentifizierung und API-Key

Produktive Integrationen authentifizieren jede Anfrage mit einem API-Key, der in der NoyesStorage App ausgegeben wurde. Senden Sie den Schlüssel als Bearer Token im HTTP-Header Authorization:

Authorization: Bearer <api-key>

Geschützte Integrationsendpunkte benötigen einen gültigen API-Key im HTTP-Header sowie die für den jeweiligen Endpunkt erforderlichen Berechtigungen. Nutzen Sie dafür die HTTPS-Adresse des NoyesStorage. Anmeldung und andere ausdrücklich öffentliche Endpunkte sind davon ausgenommen.

Behandeln Sie API-Keys wie Passwörter: nicht in den Quellcode einchecken, nur in Secret Stores oder geschützten Umgebungsvariablen speichern und bei Verdacht auf Weitergabe in der App löschen und neu erstellen.

Filtern, Suchen, Sortieren und Pagination

Listen-Endpunkte wie GET /api/v2/skus, GET /api/v2/inventory_view, GET /api/v2/requests, GET /api/v2/jobs und GET /api/v2/events unterstützen je nach Ressource Filterparameter, Suche, Sortierung und Pagination.

Filter verwenden das Schema field__operator=value. Häufige Operatoren sind __eq für exakte Treffer, __gte und __lte für Bereiche sowie __ilike für Teiltreffer ohne Unterscheidung von Groß- und Kleinschreibung. Bei __in wird der Query-Parameter pro Wert wiederholt:

GET /api/v2/inventory_view?level_id__in=1&level_id__in=2

Kommagetrennte Listen wie ?level_id__in=1,2 werden nicht als mehrere Werte interpretiert.

Der Parameter search nutzt field:value-Ausdrücke. Die Suche findet Teiltreffer und unterscheidet nicht zwischen Groß- und Kleinschreibung. Die unterstützten Suchfelder sind endpunktspezifisch und in der search-Parameterbeschreibung des jeweiligen Endpunkts aufgeführt:

GET /api/v2/skus?search=id:tee

Mehrere Suchbegriffe können mit den großgeschriebenen Operatoren AND und OR kombiniert werden. Eine Ebene von Klammern wird unterstützt:

GET /api/v2/inventory_view?search=sku_id:tee AND (box_id:2 OR carrier_id:2)

Mit *:value wird über alle für den jeweiligen Endpunkt unterstützten Suchfelder gesucht:

GET /api/v2/inventory_view?search=*:tee

Der Parameter sort_by akzeptiert kommagetrennte Feldnamen. Ein Feld ohne Vorzeichen oder mit + sortiert aufsteigend, - sortiert absteigend:

GET /api/v2/requests?sort_by=created_at,-updated_at

Pagination verwendet page und size. Die Seitennummerierung beginnt bei page=1; ohne abweichende Anfrage liefert die API standardmäßig page=1 und size=50:

GET /api/v2/skus?page=1&size=50

Funktionsweise der Anfrageausführung

Der NoyesStorage arbeitet mit einer Warteschlange. Ein Arbeitspaket wird durch eine Anfrage angefordert und in mehrere Jobs aufgeteilt. Jobs werden entsprechend ihren Abhängigkeiten und den verfügbaren Ressourcen ausgeführt; unabhängige Arbeiten können parallel laufen. Anfragen und Jobs zeigen ihren Bearbeitungsstand über einen Status an.

Requests

Anfragen sind Aufträge, die an den NoyesStorage gesendet werden. Die folgende Tabelle listet die verfügbaren Anfragetypen mit ihren Beschreibungen auf. Über die API können Fetch-, Fulfillment-, Replenishment- und Putaway-Anfragen zur Aus- und Einlagerung gesendet werden. Der Putaway-Leitfaden erklärt die Einlagerung einschließlich Lagerregeln, Vorschau und Bestätigung der Ware.

Priorität von Requests

Für über die API erstellte Fetch-, Fulfillment-, Replenishment- und Putaway-Anfragen kann optional das Feld priority als Zahl mitgesendet werden. Ohne Angabe verwendet der NoyesStorage die normale Priorität 10. Anfragen, die über die NoyesStorage App erstellt werden, werden standardmäßig mit der hohen Priorität 20 gesendet.

Priorität Wert Verhalten
Niedrig 5 Wird als normale Anfrage in der Warteschlange behandelt.
Normal 10 Standardwert, wenn keine Priorität angegeben wird.
Hoch 20 Wird vor normalen Anfragen in der Warteschlange berücksichtigt.

Prioritäten über 10 werden als Priority-Anfragen behandelt und vor normalen Anfragen in die Bearbeitung aufgenommen. Die tatsächliche Ausführung hängt weiterhin vom aktuellen Systemzustand ab, zum Beispiel von verfügbaren Carriern, Balkonen, NoyesBots und freien Bearbeitungspositionen.

Ausgabeorte für Requests

Logistische Anfragen können mit dem optionalen Feld balcony_ids auf bestimmte Balkone beschränkt werden. Die drei API-Zustände, die Reihenfolge für alle vier Anfragetypen und Beispiele finden Sie unter Ausgabeorte über die API festlegen.

Requests im NoyesStorage

Request Description
FULFILLMENT A Logistic Request consisting of SKU entities to pick.
REPLENISHMENT A Logistic Request consisting of SKU entities to refill.
PUTAWAY Stores SKU quantities by topping up existing loads, using empty boxes or creating boxes under the requested storage rules.
FETCH A Logistic Request consisting of Fetch-Carrier-Entities.
RFID_MAINTENANCE A System Control Request to write and/or check RFID Tags on a specified Level.
ONBOARD A System Control Request to add a NoyesBot to any Level.
OFFBOARD A System Control Request to remove a specific NoyesBot from a Level.
PAUSE A System Control Request that prevents Bots from receiving new commands.
RESUME A System Control Request to allow all Bots to get new commands after a PAUSE Request.
UNCHARGING A System Control Request to remove a NoyesBot from a Charging Station.
RECHARGE A System Control Request to move a NoyesBot to a Charging Station.

Eigene Positions-IDs für Fulfillment, Replenishment und Fetch

Bei POST /api/v2/requests mit type: FULFILLMENT, REPLENISHMENT oder FETCH können Sie jeder Position eine optionale entity_id zuweisen, etwa die Positions-ID aus Ihrem ERP-System. Die sku_id bezeichnet weiterhin die SKU. So lassen sich auch mehrere Positionen derselben SKU getrennt zuordnen:

{
  "type": "FULFILLMENT",
  "id": "order-4711",
  "entities": [
    {"sku_id": "SKU-123", "quantity": 2, "entity_id": "order-4711-line-a"},
    {"sku_id": "SKU-123", "quantity": 3, "entity_id": "order-4711-line-b"}
  ]
}

Die IDs müssen innerhalb einer Anfrage eindeutig sein. Sie müssen Strings sein; Zahlen und Boolean-Werte werden abgelehnt. Leere Strings und Strings, die nur aus Leerzeichen bestehen, sind ungültig. Gültige Strings werden unverändert übernommen, einschließlich Unicode-Zeichen und Leerzeichen.

Wenn entity_id fehlt oder null ist, wird die nullbasierte Position als String verwendet: "0", "1", usw. Auch diese automatisch vergebenen IDs müssen eindeutig bleiben. Beispielsweise kollidiert eine explizite ID "1" bei der ersten Position mit der automatisch vergebenen ID der zweiten Position; die gesamte Anfrage wird dann abgelehnt. In verschiedenen Anfragen können Sie dieselbe Positions-ID wiederverwenden. Diese Regeln entsprechen den Positions-IDs bei PUTAWAY.

Mit dem Python-Client können Sie dafür SkuEntityInput verwenden:

from nys_client import SkuEntityInput, NysClient

client = NysClient(api_key="<api-key>", base_url="https://<noyesstorage-url>")
request = client.requests.create_fulfillment(
    [
        SkuEntityInput(
            sku_id="SKU-123", quantity=2, entity_id="order-4711-line-a"
        ),
        SkuEntityInput(
            sku_id="SKU-123", quantity=3, entity_id="order-4711-line-b"
        ),
    ],
    id="order-4711",
)

Die bisherige Tupel-Schreibweise bleibt möglich: client.requests.create_fulfillment([("SKU-123", 2)]). Dabei wird die ID "0" vergeben. Typisierte Positionen und Tupel können in einer Liste gemischt werden.

Für Replenishment können Sie SkuEntityInput und für Fetch CarrierEntityInput aus nys_schemas verwenden:

from nys_schemas import CarrierEntityInput, SkuEntityInput

client.requests.create_replenishment([
    SkuEntityInput(sku_id="SKU-123", quantity=2, entity_id="refill-line-a")
])
client.requests.create_fetch([
    CarrierEntityInput(carrier_id="101", entity_id="fetch-line-a")
])

create_replenishment akzeptiert weiterhin SKU-Mengen-Tupel; create_fetch akzeptiert weiterhin Carrier-ID-Strings. Bei Fetch enthält die REST-Position carrier_id statt sku_id und quantity. Auch hier bleibt die entity_id von der Carrier-ID getrennt.

Die NoyesStorage App zeigt automatisch erzeugte IDs ab "1" an. Über die Überschrift der Entity-Karte können Sie eine eigene ID eintragen. Die App entfernt führende und abschließende Leerzeichen und sendet die angezeigten IDs explizit.

Replenishment-Positionen behalten ihre ID auf REFILLING-Jobs; Fetch-Positionen behalten sie auf CHECKING-Jobs.

Die Antwort auf die Anfrage zeigt entity_id und sku_id getrennt. Jeder zur Position gehörende PICKING- oder PICKING_ALERT-Job trägt die ursprüngliche Positions-ID. Entstehen mehrere Jobs für eine Position, etwa weil die Menge aus mehreren Boxen kommissioniert wird, teilen diese Jobs dieselbe entity_id.

Bei aktivierter externer Kommissionierung kann eine teilweise verfügbare Position in eine interne und eine externe Position aufgeteilt werden. Die zusätzliche Position erhält in der Antwort auf die Anfrage eine eigene eindeutige ID; der zugehörige Warnhinweis enthält die ursprüngliche ID als source_entity_id. Der PICKING_ALERT-Job behält die ursprüngliche Positions-ID, ebenso wie die internen PICKING-Jobs. So bleibt die Zuordnung zur ERP-Position erhalten.

Die Endpunkte GET /api/v2/jobs und GET /api/v2/requests_and_jobs liefern die öffentliche Positions-ID im Feld entity_id der Job-Antwort. Reine Anfragezeilen im kombinierten Endpunkt haben dort null. Bei Putaway bleibt die ID bei einer noch offenen Auswahl null, bis eine Position ausgewählt ist.

Jobs

Jobs sind die einzelnen Aufgaben, die im System ausgeführt werden. Jede Anfrage kann mehrere Jobs erzeugen, die jeweils einem vordefinierten Lebenszyklus folgen. Die folgende Tabelle liefert einen Überblick über die im NoyesStorage verwendeten Jobs.

Jobs im NoyesStorage

Job Description
BUFFERING Moves a Carrier to a Buffer Space on the same Level.
RETRIEVING Moves a Carrier to a Balcony on the same Level.
STORING Moves a Carrier from the Balcony.
PICKING Lets the user pick a given amount out of a Box.
PICKING_ALERT Lets the user handle fulfillment quantities outside the NoyesStorage when the external picking feature is enabled.
REFILLING Lets the user refill a given amount into a Box.
PLACING_STOCK Lets the user confirm or cancel an offered Putaway quantity at its storage target. Stock is booked only on successful confirmation.
CHECKING Lets the user check a given Carrier Label.
PACKING Lets the user check the summary of a Request after all Entities have been worked on.
ONBOARDING Lets the user onboard a Bot to any level.
ONBOARDING_BD Adds a Bot to the Database and informs all Brain Components about it.
OFFBOARDING Moves a Bot to the Balcony.
OFFBOARDING_BD Lets the user remove a Bot from the Balcony.
OFFBOARDING_BC Moves a Bot to the Balcony.
PAUSE Ensures no Bot gets new commands.
RESUME Allows all Bots to get new commands after a PAUSE.
MOVING_BOT Moves a Bot to a target location/rotation/lifting state.
CONNECT_TO_BOTS Establishes a connection to all Bots that are in the Database.
REFRESH_LEVEL Updates the digital twin in the Bot Coordinator to the Database.
UNCHARGE_ALL Removes all Bots from the Charging Station.
CLEAR_AUTOBAHN Removes all Carriers from the Highway.
CHARGING Moves a given bot to a Charging Station.
UNCHARGING Removes a given bot from the Charging Station.
CHECK_RFID_TAG Checks the values written on an RFID Tag at the given Location and Rotation.
WRITE_RFID_TAG Writes values to an RFID Tag at the given Location and Rotation.
CHANGE_RFID_WRITING_MODE Changes whether or not a bot should ignore the values on an RFID Tag while driving.

Hinweis zu PICKING_ALERT

PICKING_ALERT erscheint nur, wenn die externe Kommissionierung für fehlende oder außerhalb des NoyesStorage zu bearbeitende Fulfillment-Mengen aktiviert ist. In diesem Fall können angenommene Fulfillment-Anfragen strukturierte Warnhinweise zu fehlenden oder extern zu bearbeitenden Mengen enthalten, und nachgelagerte Job-Daten können PICKING_ALERT-Jobs enthalten.

Job States

Jeder Job zeigt seinen Bearbeitungsstand über einen Status an. Die Tabelle gibt einen Überblick; die möglichen Übergänge hängen vom Job-Typ und der Aktion ab. Für Putaway beachten Sie zusätzlich die Hinweise zu veränderlichen Jobs und Bestätigungen.

Job States in the NoyesStorage System

State Description
CREATED Planned but not yet released. While the request is ACCEPTED, its CREATED jobs can be replaced during replanning. Once the request is EXECUTING, their job IDs stay stable. Hidden when api.jobs.showCreated is disabled.
ACCEPTED Job is ACCEPTED. These transitions are allowed: EXECUTING, ERROR, CANCELLING, ABORTED.
EXECUTING Job is EXECUTING and waiting to be triggered. These transitions are allowed: ERROR, CANCELLING, ABORTED.
SUCCEEDED Job is SUCCEEDED. No transitions are allowed. This is a final state.
CANCELLING Job is CANCELLING. A user requested this job to be cancelled. These transitions are allowed: CANCELLED, ABORTED.
CANCELLED Job is CANCELLED. A user requested this job to be cancelled. The CANCELLING was successful. This is a final state.
ABORTED Job is ABORTED due to a system problem. The system will try to recover from this. This is a final state.

Quickstart: Ein einfaches Integrationsbeispiel

Das folgende Python-Beispiel erstellt eine Fulfillment-Anfrage für zwei Stück einer SKU und fragt den Status der Anfrage regelmäßig ab. Ersetzen Sie https://<noyesstorage-url>, <api-key> und SKU-123 durch die Werte Ihrer Integration.

Der API-Key benötigt die Berechtigung zum Erstellen von Fulfillment-Anfragen. Zum Abrufen des Status benötigt er zusätzlich die Berechtigung zum Anzeigen von Anfragen.

import time

import requests


class SimpleERPIntegration:
    """Create requests in NoyesStorage and wait for their final status."""

    TERMINAL_STATUSES = {"SUCCEEDED", "CANCELLED", "ABORTED"}

    def __init__(self, base_url: str, api_key: str) -> None:
        self.requests_url = f"{base_url.rstrip('/')}/api/v2/requests"
        self.session = requests.Session()
        self.session.headers.update(
            {
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json",
            }
        )

    def create_fulfillment(self, sku_id: str, quantity: int) -> str:
        payload = {
            "type": "FULFILLMENT",
            "priority": 10,
            "entities": [{"sku_id": sku_id, "quantity": quantity}],
        }
        response = self.session.post(self.requests_url, json=payload, timeout=10)
        response.raise_for_status()
        return response.json()["id"]

    def get_request(self, request_id: str) -> dict:
        response = self.session.get(
            self.requests_url,
            params={"id__eq": request_id},
            timeout=10,
        )
        response.raise_for_status()
        items = response.json()["items"]
        if not items:
            raise LookupError(f"Request {request_id} was not found")
        return items[0]

    def wait_until_finished(self, request_id: str, interval: int = 10) -> dict:
        while True:
            request = self.get_request(request_id)
            if request["status"] in self.TERMINAL_STATUSES:
                return request
            time.sleep(interval)


integration = SimpleERPIntegration(
    base_url="https://<noyesstorage-url>",
    api_key="<api-key>",
)
request_id = integration.create_fulfillment("SKU-123", quantity=2)
result = integration.wait_until_finished(request_id)
print(result["status"])

Erläuterungen zum Code

  1. SimpleERPIntegration richtet eine HTTP-Sitzung ein und sendet den API-Key bei jeder Anfrage als Bearer Token.
  2. create_fulfillment erstellt die Anfrage mit POST /api/v2/requests. Bei Erfolg enthält die Antwort die eindeutige id der Anfrage.
  3. get_request ruft GET /api/v2/requests mit dem Filter id__eq auf. Da es sich um einen Listen-Endpunkt handelt, steht die gefundene Anfrage im Feld items der paginierten Antwort.
  4. wait_until_finished fragt den Status im gewählten Intervall ab und endet bei SUCCEEDED, CANCELLED oder ABORTED.

Eine Anfrage durchläuft abhängig vom Typ und Bearbeitungsfortschritt Status wie CREATED, ACCEPTED, EXECUTING, SUCCEEDED, CANCELLED oder ABORTED. Fragen Sie den Status in einem für Ihre Integration geeigneten Intervall ab. Verwenden Sie bei Listenabfragen die beschriebenen Filter-, Sortier- und Pagination-Parameter.

Weitere Anfragetypen, Pflichtfelder und Antwortmodelle finden Sie in der API-Endpunktreferenz.