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

This guide describes the RESTful API of the OpenWMS.org WMS Receiving Service module and its usage. Some general terms and definitions are explained and declared in the first part of the document whereas in the second part the usage of the API is shown in a more use-case-driven approach.

Representation Formats

Basically JSON is used as representation format by default if not otherwise requested or mentioned below. XML format is supported for the index pages as well, but must be requested explicitly. Furthermore a vendor specific JSON format is used to represent resource representations. Therefore it’s absolutely required the 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.

resources.drawio
Table 1. ProductVO
Attribute Description

description

Textual descriptive text

baseUnit

The http status of the error

sku

The product id is part of the unique business key
Table 2. ReceivingOrderVO
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
Table 3. ReceivingOrderPositionVO
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 AUTOMATIC or MANUAL

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
Table 4. CaptureRequestVO
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
Table 5. CaptureDetailsVO
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

orderId

String

An unique identifier of the ReceivingOrder to create, if not provided the server generates an ID

positions[]

Array

An array of positions, must not be empty

positions[].@class

String

The type of the ReceivingOrderPosition

positions[].positionId

Number

Unique identifier of the ReceivingOrderPosition within the ReceivingOrder

positions[].priority

Number

The current priority of the ReceivingOrder the position belongs to

positions[].quantityExpected

Object

The expected quantity of the Product

positions[].quantityExpected.@class

String

Must be one of the static values to identify the type of UOM

positions[].quantityExpected.unitType

Array

Must be one of the static values to identify the concrete UOM

positions[].quantityExpected.magnitude

Number

The amount

positions[].product.sku

String

The SKU of the expected Product

positions[].details

Object

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/11314304-0503-4907-9c44-54b81319c521
Content-Type: application/vnd.openwms.receiving-order-v1+json
Content-Length: 999

{
  "ol" : 0,
  "createDt" : "2024-06-28T19:38:22.752154493Z",
  "lastModifiedDt" : "2024-06-28T19:38:22.752154493Z",
  "pKey" : "11314304-0503-4907-9c44-54b81319c521",
  "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.707722943077794",
      "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" : 1719603502753
  } ]
}

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-06-28T19:38:22.545866000Z",
  "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.3662307642640137",
      "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" : 1719603502545,
    "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.6433081218183538",
      "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" : 1719603502545,
    "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" : 1719603502545
  } ],
  "details" : {
    "Supplier no" : "182",
    "Supplier name" : "Bangee Ltd. Hongkong"
  }
}
Path Type Description

pKey

String

The synthetic unique identifier of the ReceivingOrder

orderId

String

The business key of the ReceivingOrder

state

String

The current state of the ReceivingOrder

details

Object

Stores arbitrary detail information according to the ReceivingOrder

positions[].positionId

Number

The position of the ReceivingOrderPosition

positions[].priority

Number

The current priority of the ReceivingOrder the position belongs to

positions[].@class

String

The type of the ReceivingOrderPosition

positions[].state

String

The state of the ReceivingOrderPosition

positions[].quantityExpected

Object

The expected quantity to be received

positions[].quantityExpected.magnitude

Varies

The expected quantity amount

positions[].quantityExpected.unitType

Varies

The expected quantity type

positions[].quantityReceived

Object

The already received quantity

positions[].quantityReceived.magnitude

Varies

The received quantity amount

positions[].quantityReceived.unitType

Varies

The received quantity type

positions[].details

Object

Stores arbitrary detail information according to the ReceivingOrderPosition

positions[].transportUnitBK

String

The business key of the captured TransportUnit

positions[].transportUnitTypeName

String

The name of the captured TransportUnitType

positions[].product

Object

The expected Product to be received

positions[].product.baseUnit

Varies

The default unit and quantity the Product is shipped

positions[].product.baseUnit.unitType

Varies

The default unit type of the Product

positions[].orderId

String

The unique id of the ReceivingOrder the position belongs to

positions[].createDt

Number

Timestamp when the position has been created.

createDt

String

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

{
  "ol" : 0,
  "createDt" : "2024-06-28T19:38:22.610732000Z",
  "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.13892833388015546",
      "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" : 1719603502610,
    "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.09015224978643133",
      "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" : 1719603502610,
    "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" : 1719603502610
  } ],
  "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-06-28T19:38:22.663015000Z",
  "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.9466707902255926",
      "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-06-28T19:38:22Z",
    "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.33154352136512344",
      "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-06-28T19:38:22Z",
    "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-06-28T19:38:22Z"
  } ],
  "details" : {
    "Supplier no" : "182",
    "Supplier name" : "Bangee Ltd. Hongkong"
  }
}, {
  "ol" : 0,
  "createDt" : "2024-06-28T19:38:22.663015000Z",
  "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/21ddd234-9a33-41d0-abff-cb1654ed72b1 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-06-28T19:38:22.251548000Z",
  "lastModifiedDt" : "2024-06-28T19:38:22.266040943Z",
  "pKey" : "21ddd234-9a33-41d0-abff-cb1654ed72b1",
  "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 a LoadUnit

  • A Product is captured on a Location

  • A TransportUnit without Product information is captured on a Location

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

[]

Array

Accepts multiple capture requests

[].@class

String

The type of capturing

[].transportUnit

Object

The TransportUnit where the material has been moved to

[].transportUnit.transportUnitBK

String

The business key of the TransportUnit

[].loadUnitLabel

String

The identifier of the LoadUnit where the material has been put in

[].loadUnitType

String

(Optional) The type of the LoadUnit, in case it must be created

[].quantity

Object

The captured (received) quantity

[].product

Object

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

{
  "ol" : 0,
  "createDt" : "2024-06-28T19:38:22.482669000Z",
  "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.16709550892630531",
      "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" : 1719603502482,
    "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.45947152924322054",
      "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" : 1719603502482,
    "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" : 1719603502482
  } ],
  "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

[]

Array

Accepts multiple capture requests

[].@class

String

The type of capturing

[].actualLocation

Object

The Location where the material has been moved to

[].quantity

Object

The captured (received) quantity

[].product

Object

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-06-28T19:38:22.103071000Z",
  "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.9058384160989554",
      "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" : 1719603502103,
    "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.48061302291108987",
      "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" : 1719603502103,
    "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" : 1719603502103
  } ],
  "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

[]

Array

Accepts multiple capture requests

[].@class

String

The type of capturing

[].transportUnit

Object

The TransportUnit where the material has been moved to

[].transportUnit.transportUnitBK

String

The business key of the TransportUnit

[].loadUnitLabel

String

The identifier of the LoadUnit where the material has been put in

[].loadUnitType

String

(Optional) The type of the LoadUnit, in case it must be created

[].quantity

Object

The captured (received) quantity

[].product

Object

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-06-28T19:38:22.376813000Z",
  "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.3731372154227408",
      "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" : 1719603502376,
    "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.8250339805246831",
      "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" : 1719603502376,
    "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" : 1719603502376
  } ],
  "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

[]

Array

Accepts multiple capture requests

[].@class

String

The type of capturing

[].transportUnit

Object

The TransportUnit where the material has been moved to

[].transportUnit.transportUnitBK

String

The business key of the TransportUnit

[].loadUnitLabel

String

The identifier of the LoadUnit where the material has been put in

[].loadUnitType

String

(Optional) The type of the LoadUnit, in case it must be created

[].quantity

Object

The captured (received) quantity

[].product

Object

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

[]

Array

Accepts multiple capture requests

[].@class

String

The type of capturing

[].actualLocation

Object

The Location where the material has been moved to

[].quantity

Object

The captured (received) quantity

[].product

Object

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

[]

Array

Accepts multiple capture requests

[].@class

String

The type of capturing

[].transportUnit

Object

The actual captured TransportUnit where the goods are placed on

[].actualLocation

Object

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