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.createerforderlich. Für die Statusabfrage benötigen Sieapi.requests.view, für Jobs und deren Abhängigkeitenapi.jobs.view, für Bestätigungenapi.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.