Copyright © 2005-2023
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
Overview
Representation Formats
Accept
header denotes the demanded type. Find the type in the examples below.
Dates in JSON
Date or datetime fields are not treated specially in JSON. Within the scope of this API a date or datetime field is always expected and
rendered as JSON String in ISO8601 format with timezone information and milliseconds: yyyy-MM-dd’T’HH:mm:ss.SSSTZD
.
Embedded Entities
For the sake of convenience some response entities may included embedded entities or even parts of it. A reference to the actual entity is provided as HAL link as well.
Error Responses
Beside the actual representation of resources, the server may result an error response in JSON format that contains basic information about the error occurred. This information is additional to the standard HTTP status code and may help clients to identify the error cause in order to re-phrase and send the request again.
Currently there are two types of errors with their own response formats.
Server Declined Errors
This kind of errors are sent by the server runtime environment even before the request had a chance to be processed.
An example response looks like this:
{
"timestamp": 1512400854941,
"status": 500,
"error": "Internal Server Error",
"exception": "org.ameba.oauth2.InvalidTokenException",
"message": "JWT expired at 2017-12-04T15:04:43Z. Current time: 2017-12-04T15:20:54Z, ...",
"path": "/v1/transport-units?bk=00000000000000004711"
}
The JSON structure contains the following fields.
Property Name | Description |
---|---|
timestamp |
When the error occurred on server side |
status |
The http status of the error |
error |
A short error text |
exception |
Internal class name of the Java exception type |
message |
A more descriptive error text describing the error in detail |
path |
The part of the URI for the REST resource that was queried |
API Declined Errors
Those errors are thrown within the REST API validation and processing logic. For example, if a client request does not match the expected format or has produced an error on server side, the API will decline the request and return a response with status client-side error (4xx).
The structure of the response is aligned to the RFC7808. An example response looks like this:
{
"message": "LocationGroup with name [NOT_EXISTS] not found",
"messageKey": "owms.common.common.lg.notFoundByName",
"obj" : [ "NOT_EXISTS" ],
"httpStatus" : "404",
"class" : "String"
}
The JSON structure contains the following fields.
Property Name | Description |
---|---|
message |
A short error text |
messageKey |
An unique identifier across the API that can be used to identify and translate the error message on the client side |
obj |
An array of possible passed arguments to the message |
httpStatus |
The http status of the error |
class |
The arguments type |
Following message keys are currently used:
Message Key | Description | Action |
---|---|---|
not.found |
The requested resource has not been found |
The resource does not exist anymore or has never existed. The resource identifier must be verified |
Resources
The API manages resources typically used in Goods In or Goods Receipt processing. All resources with their attributes are shown and described here.
Attribute | Description |
---|---|
description |
Textual descriptive text |
baseUnit |
The http status of the error |
sku |
The product id is part of the unique business key |
Attribute | Description |
---|---|
pKey |
The unique persistent identifier of the order |
state |
The current state |
orderId |
The unique business key |
positions |
An array of positions belonging to the order |
details |
A key/value dictionary of arbitrary values of the order |
Attribute | Description |
---|---|
positionId |
The unique persistent identifier of the order |
product |
The expected Product |
state |
The current state |
quantityReceived |
The quantity that has been received actually |
startMode |
Whether the position shall be processed |
transportUnitType |
The expected type of TransportUnit |
quantityExpected |
The expected/demanded quantity |
supplierPackagingUnit |
The expected PackagingUnit type |
details |
A key/value dictionary of arbitrary values of the position |
transportUnitId |
The business key of the expected TransportUnit |
Attribute | Description |
---|---|
product |
The Product received during the Goods In process |
details |
A key/value dictionary of arbitrary values captured during the Goods In process and stored on the position |
quantityReceived |
The quantity that has been received |
loadUnitLabel |
The unique identifier of the LoadUnit within the TransportUnit where the Product has been stored |
barcode |
The business key of the captured TransportUnit |
Attribute | Description |
---|---|
height |
The current measured height of the captured PackagingUnit |
width |
The current measured width of the captured PackagingUnit |
length |
The current measured length of the captured PackagingUnit |
weight |
The current measured weight of the captured PackagingUnit |
messageText |
Some arbitrary comment for the capture |
Index
The initial HTTP request to retrieve information about all available resources looks like the following. The Index page is a public available resource and does not need any authentication.
GET /index HTTP/1.1
Host: localhost:8080
The Index
resource is returned in the response body with the response status of 200-OK. This main Index
lists all primary resource
entities to follow next.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 125
{
"_links" : {
"receiving-order-index" : {
"href" : "http://localhost:8080/v1/receiving-orders/index"
}
}
}
A client application only needs to know about the agreed link names and follow the corresponding href
link to navigate to further
resources.
ReceivingOrder
A ReceivingOrder
represents an announcement of goods the are expected to be received at the warehouse. Usually these kind of orders are
sent by the ERP system prior to the actual physical goods receipt. A ReceivingOrder
is just the envelope that contains
ReceivingOrderPositions
, where each position determines the expected product and a quantity.
ReceivingOrder Index
The index with all possible operations on a ReceivingOrder
can be retrieved with a GET request:
GET /v1/receiving-orders/index HTTP/1.1
Host: localhost:8080
The response lists all the operations possible on ReceivingOrders
with a name and the corresponding href link:
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1137
{
"_links" : {
"receiving-order-findall" : {
"href" : "http://localhost:8080/v1/receiving-orders"
},
"receiving-order-findbypkey" : {
"href" : "http://localhost:8080/v1/receiving-orders/b65a7658-c53c-4a81-8abb-75ab67783f47"
},
"receiving-order-findbyorderid" : {
"href" : "http://localhost:8080/v1/receiving-orders?orderId=4711"
},
"receiving-order-create" : {
"href" : "http://localhost:8080/v1/receiving-orders"
},
"receiving-order-capture" : {
"href" : "http://localhost:8080/v1/receiving-orders/b65a7658-c53c-4a81-8abb-75ab67783f48/capture"
},
"receiving-order-blind-receipt" : {
"href" : "http://localhost:8080/v1/capture"
},
"receiving-order-complete" : {
"href" : "http://localhost:8080/v1/receiving-orders/b65a7658-c53c-4a81-8abb-75ab67783f49/complete"
},
"receiving-order-save" : {
"href" : "http://localhost:8080/v1/receiving-orders/b65a7658-c53c-4a81-8abb-75ab67783f46"
},
"receiving-order-patch" : {
"href" : "http://localhost:8080/v1/receiving-orders/b65a7658-c53c-4a81-8abb-75ab67783f45"
}
}
}
Create a ReceivingOrder
The POST
operation takes a flat structure of a simple ReceivingOrder
to create.
POST /v1/receiving-orders HTTP/1.1
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 430
Host: localhost:8080
{
"orderId" : "4712",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1"
},
"priority" : 0,
"details" : {
"p1" : "v1"
}
} ]
}
Path | Type | Description |
---|---|---|
|
|
An unique identifier of the ReceivingOrder to create, if not provided the server generates an ID |
|
|
An array of positions, must not be empty |
|
|
The type of the ReceivingOrderPosition |
|
|
Unique identifier of the ReceivingOrderPosition within the ReceivingOrder |
|
|
The current priority of the ReceivingOrder the position belongs to |
|
|
The expected quantity of the Product |
|
|
Must be one of the static values to identify the type of UOM |
|
|
Must be one of the static values to identify the concrete UOM |
|
|
The amount |
|
|
The SKU of the expected Product |
|
|
Some arbitrary detail information of the position |
If the ReceivingOrder
has been created successfully, the server returns the URI to the created resource in the Location
header:
HTTP/1.1 201 Created
Location: http://localhost:8080/v1/receiving-orders/182a780c-96b2-453d-bec2-934159dbbbab
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 1000
{
"ol" : 0,
"createDt" : "2024-08-03T14:20:13.874242494Z",
"lastModifiedDt" : "2024-08-03T14:20:13.874242494Z",
"pKey" : "182a780c-96b2-453d-bec2-934159dbbbab",
"orderId" : "4712",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.9007357128189071",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "4712",
"state" : "CREATED",
"priority" : 0,
"details" : {
"p1" : "v1"
},
"createDt" : 1722694813896
} ]
}
In case the client request did not match the server expectations because of invalid or missing fields in the request body, the server responds with:
HTTP/1.1 400 Bad Request
Content-Type: application/hal+json
Content-Length: 110
{
"message" : "Generic validation error",
"messageKey" : "core.validation.error",
"httpStatus" : "400"
}
Find a ReceivingOrder by Persistent Key
A HTTP GET request is required to lookup a `ReceivingOrder
by its synthetic persistent key.
GET /v1/receiving-orders/d8099b89-bdb6-40d3-9580-d56aeadd578f HTTP/1.1
Host: localhost:8080
If the ReceivingOrder
has been found, the server returns the order instance in the response body:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 2486
{
"ol" : 0,
"createDt" : "2024-08-03T14:20:13.268318000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578f",
"orderId" : "T4711",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.7308071764713802",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"details" : {
"Supplier" : "UNC Texas - Dallas",
"Unload" : "Unload carefully",
"Unload cond." : "Put to freezer zone"
},
"createDt" : 1722694813268,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 2,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "DOZ" ],
"magnitude" : 2
},
"product" : {
"sku" : "C2",
"foreignPKey" : "0.9245213489046762",
"label" : "L_C2",
"description" : "Notch M8",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694813268,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingTransportUnitOrderPositionVO",
"positionId" : 3,
"transportUnitBK" : "00000000000000004712",
"transportUnitTypeName" : "EURO",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694813268
} ],
"details" : {
"Supplier no" : "182",
"Supplier name" : "Bangee Ltd. Hongkong"
}
}
Path | Type | Description |
---|---|---|
|
|
The synthetic unique identifier of the ReceivingOrder |
|
|
The business key of the ReceivingOrder |
|
|
The current state of the ReceivingOrder |
|
|
Stores arbitrary detail information according to the ReceivingOrder |
|
|
The position of the ReceivingOrderPosition |
|
|
The current priority of the ReceivingOrder the position belongs to |
|
|
The type of the ReceivingOrderPosition |
|
|
The state of the ReceivingOrderPosition |
|
|
The expected quantity to be received |
|
|
The expected quantity amount |
|
|
The expected quantity type |
|
|
The already received quantity |
|
|
The received quantity amount |
|
|
The received quantity type |
|
|
Stores arbitrary detail information according to the ReceivingOrderPosition |
|
|
The business key of the captured TransportUnit |
|
|
The name of the captured TransportUnitType |
|
|
The expected Product to be received |
|
|
The default unit and quantity the Product is shipped |
|
|
The default unit type of the Product |
|
|
The unique id of the ReceivingOrder the position belongs to |
|
|
Timestamp when the position has been created. |
|
|
Timestamp when the ReceivingOrder has been created. |
In case the order does not exist, the server responds with a error of the 4xx-client family because the pKey
is expected to exist:
HTTP/1.1 404 Not Found
Content-Type: application/hal+json
Content-Length: 188
{
"message" : "ReceivingOrder with ID [unknown] does not exist",
"messageKey" : "owms.wms.rec.recOrderNotFound",
"obj" : [ "unknown" ],
"httpStatus" : "404",
"class" : "String"
}
Find a ReceivingOrder by Order ID
A HTTP GET
request is required to find a ReceivingOrder
by it’s identifying business key, the order ID.
GET /v1/receiving-orders?orderId=T4711 HTTP/1.1
Host: localhost:8080
If the ReceivingOrder
has been found, the server returns the order instance in the response body:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 2487
{
"ol" : 0,
"createDt" : "2024-08-03T14:20:13.590878000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578f",
"orderId" : "T4711",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.09311424062463658",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"details" : {
"Supplier" : "UNC Texas - Dallas",
"Unload" : "Unload carefully",
"Unload cond." : "Put to freezer zone"
},
"createDt" : 1722694813590,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 2,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "DOZ" ],
"magnitude" : 2
},
"product" : {
"sku" : "C2",
"foreignPKey" : "0.9611670421312368",
"label" : "L_C2",
"description" : "Notch M8",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694813590,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingTransportUnitOrderPositionVO",
"positionId" : 3,
"transportUnitBK" : "00000000000000004712",
"transportUnitTypeName" : "EURO",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694813590
} ],
"details" : {
"Supplier no" : "182",
"Supplier name" : "Bangee Ltd. Hongkong"
}
}
In case the order does not exist, the server responds in the same way like Find a ReceivingOrder by Persistent Key.
Find all ReceivingOrders
A HTTP GET request to the primary resource is required to find all `ReceivingOrders
. Notice, this method is foreseen for UI applications
and may change in future API versions.
GET /v1/receiving-orders HTTP/1.1
Host: localhost:8080
Returns an array of ReceivingOrders
or an empty array:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 2682
[ {
"ol" : 0,
"createDt" : "2024-08-03T14:20:13.673818000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578f",
"orderId" : "T4711",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.02055520678263889",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"details" : {
"Supplier" : "UNC Texas - Dallas",
"Unload" : "Unload carefully",
"Unload cond." : "Put to freezer zone"
},
"createDt" : "2024-08-03T14:20:13Z",
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 2,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "DOZ" ],
"magnitude" : 2
},
"product" : {
"sku" : "C2",
"foreignPKey" : "0.7493477464378344",
"label" : "L_C2",
"description" : "Notch M8",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"createDt" : "2024-08-03T14:20:13Z",
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingTransportUnitOrderPositionVO",
"positionId" : 3,
"transportUnitBK" : "00000000000000004712",
"transportUnitTypeName" : "EURO",
"state" : "CREATED",
"priority" : 0,
"createDt" : "2024-08-03T14:20:13Z"
} ],
"details" : {
"Supplier no" : "182",
"Supplier name" : "Bangee Ltd. Hongkong"
}
}, {
"ol" : 0,
"createDt" : "2024-08-03T14:20:13.673818000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578e",
"orderId" : "T4712",
"state" : "COMPLETED"
} ]
Cancel a ReceivingOrder
An earlier created ReceivingOrder
can be cancelled for further processing. The client needs to send a HTTP `DELETE request with the
unique identifier of the order.
PATCH /v1/receiving-orders/cafee20c-31a1-476f-8f39-562dd9074a62 HTTP/1.1
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 48
Host: localhost:8080
{
"orderId" : "4714",
"state" : "CANCELED"
}
If the ReceivingOrder
has been cancelled, the server returns with:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 215
{
"ol" : 2,
"createDt" : "2024-08-03T14:20:14.456656000Z",
"lastModifiedDt" : "2024-08-03T14:20:14.471672503Z",
"pKey" : "cafee20c-31a1-476f-8f39-562dd9074a62",
"orderId" : "4714",
"state" : "CANCELED"
}
In case the order couldn’t be cancelled because the order is already in process or has been processed, the server responds with:
HTTP/1.1 403 Forbidden
Content-Type: application/hal+json
Content-Length: 274
{
"message" : "Cancellation of ReceivingOrder with orderId [T4712] is not allowed because order is already in state [COMPLETED]",
"messageKey" : "owms.wms.rec.recOrderCancellationDenied",
"obj" : [ "T4712", "COMPLETED" ],
"httpStatus" : "403",
"class" : "String"
}
Receiving Goods
When products arrive at the warehouse they are usually announced with a ReceivingOrder
and its ReceivingOrderPositions
beforehand. This
is called an expected receipt. Also unexpected receipts may occur, any unplanned material that needs to be stored in the warehouse without
any previous received order information. Unexpected receipts may also happen as part of an expected receipt when a supplier ships more items
than previously announced in a ReceivingOrderPosition
. Multiple types of capturing exists for expected and blind receipts:
-
A
Product
is captured on aLoadUnit
-
A
Product
is captured on aLocation
-
A
TransportUnit
withoutProduct
information is captured on aLocation
The capturing process happens at the Goods In area of the warehouse, where material arrives and is identified (captured). In case of
expected receipts, the identified items or TransportUnits
are assigned to ReceivingOrderPositions
.
Expected Receipt: Capture a Product in a LoadUnit
The received Product
is identified and assigned to an existing ReceivingOrderPosition
. As part of the capturing process the items are
basically placed in a LoadUnit
on top of a TransportUnit
.
To capture the amount of a Product
in the context of a ReceivingOrder
the caller sends a POST
request to the server with the
identifying pKey
of the ReceivingOrder
as part of the URI:
POST /v1/receiving-orders/d8099b89-bdb6-40d3-9580-d56aeadd578f/capture HTTP/1.1
Content-Type: application/json
Content-Length: 385
Host: localhost:8080
[ {
"@class" : "org.openwms.wms.receiving.api.QuantityCaptureRequestVO",
"transportUnit" : {
"transportUnitBK" : "4711"
},
"loadUnitLabel" : "1",
"loadUnitType" : "EURO",
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1"
}
} ]
Path | Type | Description |
---|---|---|
|
|
Accepts multiple capture requests |
|
|
The type of capturing |
|
|
The TransportUnit where the material has been moved to |
|
|
The business key of the TransportUnit |
|
|
The identifier of the LoadUnit where the material has been put in |
|
|
(Optional) The type of the LoadUnit, in case it must be created |
|
|
The captured (received) quantity |
|
|
The captured (received) Product |
If an open and not satisfied ReceivingOrderPosition
with the captured Product
exists the captured quantity is assigned to that position
and the items are created in the LoadUnit
on top of the TransportUnit. The server responds with the updated `ReceivingOrder
instance:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 2488
{
"ol" : 0,
"createDt" : "2024-08-03T14:20:14.701103000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578f",
"orderId" : "T4711",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.1510725204399037",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "COMPLETED",
"priority" : 0,
"details" : {
"Supplier" : "UNC Texas - Dallas",
"Unload" : "Unload carefully",
"Unload cond." : "Put to freezer zone"
},
"createDt" : 1722694814701,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 2,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "DOZ" ],
"magnitude" : 2
},
"product" : {
"sku" : "C2",
"foreignPKey" : "0.6295342630131842",
"label" : "L_C2",
"description" : "Notch M8",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694814701,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingTransportUnitOrderPositionVO",
"positionId" : 3,
"transportUnitBK" : "00000000000000004712",
"transportUnitTypeName" : "EURO",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694814701
} ],
"details" : {
"Supplier no" : "182",
"Supplier name" : "Bangee Ltd. Hongkong"
}
}
If no open ReceivingOrderPosition
exists in the ReceivingOrder
or the Product
does match the list of expected Products
and
overbooking of that kind of Product
is not allowed, the server prohibits the goods receipt and responds with an error:
HTTP/1.1 409 Conflict
Content-Type: application/hal+json
Content-Length: 223
{
"message" : "Received a goods receipt but all ReceivingOrderPositions are already satisfied and unexpected receipts are not allowed",
"messageKey" : "owms.wms.rec.recOrderNoUnexpectedAllowed",
"httpStatus" : "409"
}
Overbooking means: In case Overbooking
is allowed for a Product
, the supplier can ship a higher amount of that Product
than
previously announced in the ReceivingOrderPosition
. If Overbooking
is forbidden, the server raises an exception. Overbooking can be
configured per Product
.
Expected Receipt: Capture an expected Product on a Location
The received Product
is identified and assigned to an existing ReceivingOrderPosition
. As part of the capturing process the items are
placed on a Location
directly without any carrier like a LoadUnit
or a TransportUnit
.
To capture the amount of a Product
in the context of a ReceivingOrder
the caller sends a POST
request to the server with the
identifying pKey
of the ReceivingOrder
as part of the URI:
POST /v1/receiving-orders/d8099b89-bdb6-40d3-9580-d56aeadd578f/capture HTTP/1.1
Content-Type: application/json
Content-Length: 336
Host: localhost:8080
[ {
"@class" : "org.openwms.wms.receiving.api.QuantityCaptureOnLocationRequestVO",
"actualLocation" : {
"erpCode" : "WE01"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1"
}
} ]
Path | Type | Description |
---|---|---|
|
|
Accepts multiple capture requests |
|
|
The type of capturing |
|
|
The Location where the material has been moved to |
|
|
The captured (received) quantity |
|
|
The captured (received) Product |
If an open and not satisfied ReceivingOrderPosition
with the captured Product
exists the captured quantity is assigned to that position
and the items are directly placed onto the given Location
. The server responds with the updated ReceivingOrder
instance:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 2489
{
"ol" : 0,
"createDt" : "2024-08-03T14:20:14.331555000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578f",
"orderId" : "T4711",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.14678558601824676",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "COMPLETED",
"priority" : 0,
"details" : {
"Supplier" : "UNC Texas - Dallas",
"Unload" : "Unload carefully",
"Unload cond." : "Put to freezer zone"
},
"createDt" : 1722694814331,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 2,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "DOZ" ],
"magnitude" : 2
},
"product" : {
"sku" : "C2",
"foreignPKey" : "0.7963450132604208",
"label" : "L_C2",
"description" : "Notch M8",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694814331,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingTransportUnitOrderPositionVO",
"positionId" : 3,
"transportUnitBK" : "00000000000000004712",
"transportUnitTypeName" : "EURO",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694814331
} ],
"details" : {
"Supplier no" : "182",
"Supplier name" : "Bangee Ltd. Hongkong"
}
}
If no open ReceivingOrderPosition
exists in the ReceivingOrder
or the Product
does not fit to the list of expected Products
, the
server prohibits the goods receipt and responds with an error:
HTTP/1.1 409 Conflict
Content-Type: application/hal+json
Content-Length: 223
{
"message" : "Received a goods receipt but all ReceivingOrderPositions are already satisfied and unexpected receipts are not allowed",
"messageKey" : "owms.wms.rec.recOrderNoUnexpectedAllowed",
"httpStatus" : "409"
}
Expected Receipt: Capture an expected TransportUnit on a Location
It may happen that an external supplier ships back existing TransportUnits
to the warehouse. In this case, the announced ReceivingOrder
contains ReceivingOrderPositions
that point to the expected TransportUnit
.
To capture the received TransportUnit
the operator identifies (e.g. scans) the TransportUnit
and the LoadUnit
on top (optional) and
the client device sends a POST
request to the server with the identifying pKey
of the ReceivingOrder
as part of the URI:
POST /v1/receiving-orders/d8099b89-bdb6-40d3-9580-d56aeadd578f/capture HTTP/1.1
Content-Type: application/json
Content-Length: 196
Host: localhost:8080
[ {
"@class" : "org.openwms.wms.receiving.api.TUCaptureRequestVO",
"transportUnit" : {
"transportUnitBK" : "00000000000000004712"
},
"actualLocation" : {
"erpCode" : "WE01"
}
} ]
Path | Type | Description |
---|---|---|
|
|
Accepts multiple capture requests |
|
|
The type of capturing |
|
|
The TransportUnit where the material has been moved to |
|
|
The business key of the TransportUnit |
|
|
The identifier of the LoadUnit where the material has been put in |
|
|
(Optional) The type of the LoadUnit, in case it must be created |
|
|
The captured (received) quantity |
|
|
The captured (received) Product |
If an open and not satisfied position with the expected TransportUnit
exists the ReceivingOrderPosition
is completely captured, means
all expected items are created, the state of the ReceivingOrderPosition
has changed to COMPLETED
and the server responds with the
updated ReceivingOrder
instance:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 2488
{
"ol" : 0,
"createDt" : "2024-08-03T14:20:14.585126000Z",
"pKey" : "d8099b89-bdb6-40d3-9580-d56aeadd578f",
"orderId" : "T4711",
"state" : "CREATED",
"positions" : [ {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 1,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1",
"foreignPKey" : "0.3492975114028738",
"label" : "L_C1",
"description" : "Skateboard gearings 608ZZ",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"details" : {
"Supplier" : "UNC Texas - Dallas",
"Unload" : "Unload carefully",
"Unload cond." : "Put to freezer zone"
},
"createDt" : 1722694814585,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingOrderPositionVO",
"positionId" : 2,
"quantityExpected" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "DOZ" ],
"magnitude" : 2
},
"product" : {
"sku" : "C2",
"foreignPKey" : "0.9616032014365317",
"label" : "L_C2",
"description" : "Notch M8",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
},
"orderId" : "T4711",
"state" : "CREATED",
"priority" : 0,
"createDt" : 1722694814585,
"quantityReceived" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 0
}
}, {
"@class" : "org.openwms.wms.receiving.api.ReceivingTransportUnitOrderPositionVO",
"positionId" : 3,
"transportUnitBK" : "00000000000000004712",
"transportUnitTypeName" : "EURO",
"state" : "COMPLETED",
"priority" : 0,
"createDt" : 1722694814585
} ],
"details" : {
"Supplier no" : "182",
"Supplier name" : "Bangee Ltd. Hongkong"
}
}
If no open ReceivingOrderPosition
with the captured TransportUnit
in the ReceivingOrder
exists, the server prohibits the receipt of
the TransportUnit
and responds with an error:
HTTP/1.1 409 Conflict
Content-Type: application/hal+json
Content-Length: 195
{
"message" : "Received a goods receipt but no open ReceivingOrderPositions with the expected TransportUnit exist",
"messageKey" : "owms.wms.rec.recOrderNoROPWithTU",
"httpStatus" : "409"
}
Blind Receipt: Capture a Product on a LoadUnit
Items of a Product
are received, without any ASN (Advanced Shipping Notice). Therefor this receipt cannot be captured and validated
against a ReceivingOrder
. The received items are created and put into a LoadUnit
on top of a TransportUnit
.
Similar to an expected receipt the caller sends a POST
request to the server but without any ReceivingOrder
reference in the URI:
POST /v1/capture HTTP/1.1
Content-Type: application/json
Content-Length: 385
Host: localhost:8080
[ {
"@class" : "org.openwms.wms.receiving.api.QuantityCaptureRequestVO",
"transportUnit" : {
"transportUnitBK" : "4711"
},
"loadUnitLabel" : "1",
"loadUnitType" : "EURO",
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1"
}
} ]
Path | Type | Description |
---|---|---|
|
|
Accepts multiple capture requests |
|
|
The type of capturing |
|
|
The TransportUnit where the material has been moved to |
|
|
The business key of the TransportUnit |
|
|
The identifier of the LoadUnit where the material has been put in |
|
|
(Optional) The type of the LoadUnit, in case it must be created |
|
|
The captured (received) quantity |
|
|
The captured (received) Product |
If successful the server responds with:
HTTP/1.1 204 No Content
Blind Receipt: Capture a Product on a Location
Items of a Product
are received, without any ASN (Advanced Shipping Notice). Therefor this receipt cannot be captured and validated
against a ReceivingOrder
. The received items are placed on a Location
directly without any carrier like a LoadUnit
or a TransportUnit
.
Similar to an expected receipt the caller sends a POST
request to the server but without any ReceivingOrder
reference reference in the
URI:
POST /v1/capture HTTP/1.1
Content-Type: application/json
Content-Length: 336
Host: localhost:8080
[ {
"@class" : "org.openwms.wms.receiving.api.QuantityCaptureOnLocationRequestVO",
"actualLocation" : {
"erpCode" : "WE01"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"product" : {
"sku" : "C1"
}
} ]
Path | Type | Description |
---|---|---|
|
|
Accepts multiple capture requests |
|
|
The type of capturing |
|
|
The Location where the material has been moved to |
|
|
The captured (received) quantity |
|
|
The captured (received) Product |
If successful the server responds with:
HTTP/1.1 204 No Content
Blind Receipt: Capture an unexpected TransportUnit on a Location
It may happen that an external supplier ships back empty TransportUnits
to the warehouse without any ASN (Advanced Shipping Notice)
information. To capture and create those TransportUnits
in the system the identifier, type and current Location
of the TransportUnit
must be passed to the API.
The client device sends a POST
request to the server with the mandatory TransportUnit
data in the request body:
POST /v1/capture HTTP/1.1
Content-Type: application/json
Content-Length: 228
Host: localhost:8080
[ {
"@class" : "org.openwms.wms.receiving.api.TUCaptureRequestVO",
"transportUnit" : {
"transportUnitBK" : "00000000000000004712",
"transportUnitType" : "FP"
},
"actualLocation" : {
"erpCode" : "WE01"
}
} ]
Path | Type | Description |
---|---|---|
|
|
Accepts multiple capture requests |
|
|
The type of capturing |
|
|
The actual captured TransportUnit where the goods are placed on |
|
|
The Location where the TransportUnit is placed on |
If the TransportUnit
has been created successfully the server responds with:
HTTP/1.1 204 No Content