Zum Inhalt

Putaway über die API

Eine PUTAWAY-Anfrage beauftragt die Einlagerung von Ware. Sie kann vorhandene Beladungen auffüllen, leere Boxen nutzen oder neue Boxen erstellen. Die Ware wird erst beim Bestätigen des jeweiligen Einlagerungsjobs als Bestand gebucht.

Die Bedienung in der NoyesStorage App beschreibt Einlagerungsaufträge. Alle Feldtypen stehen in der API-Endpunktreferenz.

Voraussetzungen

  • Jede verwendete SKU muss bereits existieren. Das Anlegen einer SKU legt noch keine Box, Beladung oder Ware an.
  • Für jede Position müssen erlaubte Boxgrößen und Maximalmengen vorliegen: entweder in den SKU-Stammdaten oder in der Position der Anfrage.
  • Verwenden Sie die API-Key-Authentifizierung. Zum Erstellen ist api.requests.putaway.create erforderlich. Für die Statusabfrage benötigen Sie api.requests.view, für Jobs und deren Abhängigkeiten api.jobs.view, für Bestätigungen api.jobs.trigger.

1. Einlagerung prüfen

Senden Sie POST /api/v2/requests mit dry_run: true. Das Beispiel setzt eine vorhandene SKU SKU-123 und genügend freien Platz für eine große Box voraus.

{
  "type": "PUTAWAY",
  "id": "PO-42",
  "dry_run": true,
  "entities": [
    {
      "entity_type": "Sku",
      "entity_id": "line-1",
      "sku_id": "SKU-123",
      "quantity": 6,
      "allowed_box_size_capacities": {"large": 10},
      "options": {
        "strategy_chain": ["CREATE_STORAGE_CONTAINER"],
        "constraints": []
      }
    }
  ]
}

Eine erfolgreiche Vorschau kann so aussehen:

{
  "dry_run": true,
  "entities": [
    {
      "entity_id": "line-1",
      "sku_id": "SKU-123",
      "entity_type": "Sku",
      "possible_quantity": 6,
      "existing_load_quantity": 0,
      "new_load_quantity": 6,
      "error_messages": [],
      "error_keys": []
    }
  ],
  "request": null
}

possible_quantity ist die einlagerbare Menge. existing_load_quantity nennt den Anteil zum Auffüllen vorhandener Beladungen; new_load_quantity den Anteil für neue Beladungen. Die Vorschau speichert keine Anfrage und reserviert keinen Platz. Eine erfolgreiche Vorschau garantiert deshalb nicht, dass eine spätere Anfrage noch angenommen werden kann.

Positionen und Mengen

Eine Anfrage enthält 1 bis 100 Positionen. quantity ist eine positive ganze Zahl, kein Text und keine Dezimalzahl. Verwenden Sie die Feldnamen genau wie im Beispiel, etwa dry_run statt dryRun. Unbekannte Felder werden abgewiesen.

sku_id bezeichnet den Artikel. entity_id bezeichnet eine Position innerhalb dieser Anfrage und muss dort eindeutig sein. So können zwei Positionen dieselbe SKU mit unterschiedlichen Regeln anfordern. Ohne entity_id verwendet die API die Position als Text, beginnend mit "0". Für die spätere Zuordnung empfiehlt sich eine eigene, eindeutige Positions-ID.

Boxgrößen und Maximalmengen

allowed_box_size_capacities ordnet jeder erlaubten Boxgröße eine maximale Stückzahl zu. Erlaubte Größen sind micro, mini, small, medium und large.

Wert in der Position Wirkung
Feld fehlt oder {} Regeln aus den SKU-Stammdaten verwenden.
Nicht leeres Objekt, etwa {"large": 10} Nur diese Regeln für die Position verwenden; SKU-Regeln nicht ergänzen.

Die Überschreibung ändert keine SKU-Stammdaten. Zum Auffüllen einer vorhandenen Beladung müssen deren Boxgröße und gespeicherte Maximalmenge zu den wirksamen Regeln passen. Freier Platz allein reicht dafür nicht aus.

Strategien und feste Vorgaben

Die strategy_chain wird der Reihe nach abgearbeitet. Jede Strategie übernimmt die passende Menge; nur der Rest geht an die nächste Strategie.

Strategie Verwendung
ADD_TO_EXISTING_STOCK Geeignete vorhandene Beladungen derselben SKU auffüllen.
USE_EXISTING_EMPTY_CONTAINER Geeignete leere Boxen für neue Beladungen nutzen.
CREATE_STORAGE_CONTAINER Neue Boxen und Beladungen auf freier Carrier-Fläche erstellen.
MATCH_CREATED_SAME_DAY Nur geeignete Beladungen auffüllen, die am aktuellen Betriebstag erstellt wurden.

CONTAINER bezeichnet in diesen API-Strategien eine Box. Verwenden Sie in der Anfrage die Strategienamen genau wie in der Tabelle angegeben.

Wenn options fehlt, verwendet die API die konfigurierte Putaway-API-Vorlage. Wenn options angegeben ist, gelten die angegebenen Felder und deren Schema-Standardwerte. Insbesondere bedeutet options: {} die Reihenfolge ADD_TO_EXISTING_STOCK, USE_EXISTING_EMPTY_CONTAINER, CREATE_STORAGE_CONTAINER, ohne zusätzliche Vorgaben. Geben Sie die Optionen ausdrücklich an, wenn Ihre Integration unabhängig von der Systemvorlage sein soll.

constraints: ["SAME_CARRIER_AS_PREVIOUS_ENTITY"] bindet eine Position an den Carrier der vorherigen Position. Diese Vorgabe ist zwingend und wird bei Platzmangel nicht aufgehoben. Sie ist an der ersten Position ungültig. Zusammenhängende gebundene Positionen müssen gemeinsam auf einen Carrier passen und mindestens einen gemeinsam erlaubten Balkon haben.

Balkone

Für jede Position gilt die erste ausdrücklich gesetzte Balkonvorgabe in dieser Reihenfolge: Position → Anfrage → SKU → Putaway-Standardbalkone. Ohne Vorgabe bleibt die Auswahl unbeschränkt, soweit der Balkon vom Lagerplatz erreichbar ist.

balcony_ids Wirkung auf jeder Stufe
Feld fehlt oder null Die nächste Stufe verwenden.
[] Keine Einschränkung; keine Vorgabe der nächsten Stufe übernehmen.
Beispielsweise [1, 2] Nur diese Balkone erlauben; niedrigere Stufen ersetzen.

Beispiel: Die Anfrage erlaubt [1], eine Position setzt aber []. Diese Position darf jeden erreichbaren Balkon verwenden. Mit null würde sie [1] übernehmen. Die geprüften Balkonregeln werden mit der Anfrage gespeichert; spätere Änderungen der SKU- oder Standardvorgaben ändern diese Anfrage nicht. Details zur Erreichbarkeit und zu Standardbalkonen stehen unter Ausgabeorte für Anfragen.

2. Request erstellen und verfolgen

Senden Sie dieselbe Anfrage mit dry_run: false. Die API prüft die verfügbare Kapazität erneut, einschließlich bereits eingeplanter Mengen anderer offener Arbeiten. Nur wenn alle Positionen vollständig umsetzbar sind, wird die Anfrage angenommen. Es wird keine teilweise angenommene Anfrage angelegt.

Bei Erfolg liefert die API HTTP 200 und eine PutawayResponse. Die angelegte Anfrage steht im Feld request; ihre öffentliche ID steht unter request.id, nicht direkt unter id wie im Fulfillment-Beispiel der Integrationsübersicht. Ohne eigene id erzeugt die API eine. Die neue Anfrage hat den Status ACCEPTED. Das bedeutet „angenommen“, nicht „Ware bereits eingelagert“.

Fragen Sie die Anfrage über GET /api/v2/requests?id__eq=PO-42 ab. Das Ergebnis steht in items. Verwenden Sie weiterhin die Filter und Pagination aus der Integrationsübersicht.

Jobs können sich vor dem Start ändern

Zu einer Anfrage gehören mehrere Jobs. Eine Position kann auf mehrere Einlagerungsjobs verteilt sein. Solange Jobs den Status CREATED haben, kann das System sie neu planen und ersetzen. Job-IDs und Ziele sind in dieser Phase daher keine dauerhafte Zusage. Laden Sie die aktuellen Jobs vor einer Bedienaktion erneut.

Das System gibt die Arbeit je Carrier frei, also nicht zwingend alle Jobs der Anfrage gleichzeitig. Abhängigkeiten können auch zu Jobs einer anderen Anfrage bestehen, wenn derselbe Carrier genutzt wird.

GET /api/v2/requests/{request_id}/job-graph zeigt Jobs und ihre Abhängigkeiten. Wie die Job-Liste berücksichtigt dieser Endpunkt die Einstellung api.jobs.showCreated: Ist sie ausgeschaltet, fehlen Jobs im Status CREATED, auch gemeinsame Vorgängerjobs. Die Antwort enthält nur Verbindungen zwischen den zurückgegebenen Jobs. Der angezeigte Graph kann deshalb unvollständig sein. Eine leere Vorgängerliste bedeutet nicht, dass Sie den Job bereits ausführen dürfen.

3. Ware bestätigen oder eine Teilmenge abbrechen

Ein Einlagerungsjob hat den Typ PLACING_STOCK. Bestätigen Sie ihn erst im Status EXECUTING und nach der tatsächlichen Platzierung der Ware. Seine details enthalten die Handlung, das Ziel und die aktuell erlaubten Positionen mit ihren Mengen in candidate_entities.

selection_state Bedeutung
FIXED Genau eine Position steht zur Verfügung.
PENDING Mehrere Positionen stehen zur Auswahl.
SELECTED Eine Auswahl wurde bereits angewendet.

Bei mehreren Möglichkeiten können die einfachen SKU- und Mengenfelder des Jobs noch leer sein. Verwenden Sie die angebotenen Kombinationen aus entity_id und quantity. Senden Sie keine frei gewählte Menge.

Für einen Job, der für line-1 ausschließlich die Menge 6 anbietet, senden Sie POST /api/v2/trigger/{job_id}:

{
  "trigger_status": "SUCCEEDED_TRIGGER",
  "selected_entity_id": "line-1"
}

Die veralteten Auswahlfelder selected_request_entity_idx und selected_request_entity_id werden abgewiesen, auch wenn sie null enthalten. Verwenden Sie ausschließlich selected_entity_id für die Positionsauswahl. Ältere Trigger-Felder und zusätzliche Metadaten bleiben zulässig; die Prüfung der unterstützten Statuswerte bleibt bestehen.

Die API bucht die bestätigte Ware, bevor sie die weitere Job-Ausführung benachrichtigt. Je nach Handlung wird eine vorhandene Beladung aufgefüllt, eine Beladung in einer vorhandenen Box angelegt oder eine neue Box mit Beladung angelegt.

Um die angebotene Menge stattdessen als abgebrochen zu erfassen, senden Sie:

{
  "trigger_status": "CANCELLED_TRIGGER",
  "selected_entity_id": "line-1"
}

Der Abbruch zählt diese Menge als erledigt, aber nicht als eingelagert. Er ändert keine Boxen, Beladungen oder Bestände. Prüfen Sie bei den Anfragepositionen succeeded_quantity und cancelled_quantity, statt aus der erledigten Gesamtmenge auf den Wareneingang zu schließen.

Bereits eingelegte Ware

Wenn Ware bereits physisch eingelegt wurde, muss sie vor dem Fortsetzen mit dem gebuchten Bestand abgeglichen werden. Ein Abbruch nimmt keine Ware physisch aus dem Lager.

Verlorene Antwort und Neustart

Wenn die Antwort auf eine Bestätigung verloren geht, kann dieselbe Bestätigung für denselben Job erneut gesendet werden. Verwenden Sie denselben Ausgang und dieselbe Positions-ID. Die API verwendet dann die bereits gebuchte Menge; bereits gebuchte Ware wird nicht ein zweites Mal gebucht. Eine nachträgliche Änderung einer angewendeten Auswahl oder des Ausgangs wird abgewiesen.

Das ist keine allgemeine Zusage für wiederholtes POST /requests. Prüfen Sie nach einer verlorenen Antwort auf die Anfrageerstellung zuerst anhand Ihrer Anfrage-ID, ob die Anfrage bereits existiert.

Ein Neustart erhält bereits bestätigte und abgebrochene Mengen. Noch offene Arbeit wird wieder aufgenommen und kann neu geplant werden. Lesen Sie die aktuelle Anfrage und ihre Jobs erneut, bevor Sie die Bearbeitung fortsetzen.

Fehler behandeln

HTTP-Status Bedeutung und nächster Schritt
400 Die Anfrage ist unter den gegebenen Daten oder Regeln nicht umsetzbar: etwa unbekannte SKU, fehlende Kapazitätsregeln oder kein passender Platz. Prüfen Sie detail und passen Sie die Eingabe an.
400 mit NOT_ALLOCATABLE_UNDER_CURRENT_POLICY bei offenen Entnahmen Für SKUs mit Zuweisung aufheben werden Beladungen ausgeschlossen, die ausstehende interne Entnahmen leeren können. Erlauben Sie passende alternative Ziele oder prüfen Sie die verfügbare Kapazität. Bleibt nach den Entnahmen Bestand übrig, darf die Beladung im Rahmen ihrer aktuellen freien Kapazität aufgefüllt werden.
409 bei Erstellung Die Kapazität hat sich während der Annahme geändert. Prüfen Sie erneut und wiederholen Sie bei weiterhin passender Kapazität die Anfrage.
409 bei Bestätigung Die Aktion passt nicht mehr zum aktuellen oder bereits bestätigten Zustand. Lesen Sie den Job erneut; ändern Sie keine bereits angewendete Auswahl.
422 Der Aufbau der Eingabe ist ungültig, etwa ein unbekanntes Feld, eine falsche Menge oder eine ungültige Vorgabe. Korrigieren Sie die angegebenen Felder.

Bei unbekannten SKUs enthält detail.missing_sku_ids die fehlenden IDs. Bei Planungsfehlern kann detail.entities die Ergebnisse je Position mit error_keys und error_messages enthalten. Nicht jeder Fehler hat dieselbe Struktur; verlassen Sie sich nicht ausschließlich auf einen Meldungstext.

Die angezeigte SKU-Gesamtkapazität ist keine Reservierung für diese Anfrage. Ob eine konkrete Menge passt, hängt auch von Boxgrößen, erlaubten Balkonen, Strategien und bereits eingeplanter Arbeit ab. Verwenden Sie dafür die Putaway-Vorschau.