Manage Shipments
This section gives an overview of the API calls used for managing Shipments.
SetShipmentDetails
Location /v1/Logistics/SetShipmentDetails
Sets (overrides) the shipment details like reference numbers and description.
{
# Mandatory Fields
"shipmentUid": "", # Unique id of the shipment that should be changed.
"Description": "", # Description of the shipment (string).
"ReferenceNo": "", # Reference number of the shipment (string).
"ReferenceCaseNo": "" # Related case number of the shipment (string).
}
POST /v1/Logistics/SetShipmentDetails HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"shipmentUid": "472843a4322a4a2686286f07fd6eabe4",
"Description": null,
"ReferenceNo": "DA489784984627",
"ReferenceCaseNo": "I1701-1982"
}
{
"success": true/false, # Command executed successfully
"error": null, # Error code (if any)
"message": null # Error message (if any)
}
AddShipmentObject
Location /v1/Logistics/AddShipmentObject
Adds an object to the shipment.
{
# Mandatory Fields
"shipmentUid": "...", # Unique ID of the shipment to which you want to add the new item
"details": {
"referenceNo": "TestRef", # Your reference number
"description": "TestDesc",
"weight": 1234, # Weight in grams
"count": 2, # Total object parts
"dimension": { # Dimension of the package in centimeters
"width": 40,
"height": 30,
"length": 60
}
},
# Optional Fields.
"changePickUpAccess": true, # Create new access code for pickup.
"changeDropOffAccess": true # Create new access code for drop off.
# You can get the new code by calling the `GetShipmentAccessCode` function
}
POST /v1/Logistics/AddShipmentObject HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"shipmentUid": "256d670c-5ec7-4641-8bf6-d4eb8c176359",
"details": {
"referenceNo": "My Ref",
"description": "My description",
"weight": 1000,
"count": 1,
"dimension": {
"width": 40,
"height": 30,
"length": 60
}
},
"changePickUpAccess": true,
"changeDropOffAccess": true
}
{
"shipmentUid": "710adbe...fdea72", # Unique id of the shipment requested.
"shipmentObjectUid": "7a0e489...78f166", # Unique identifier of the shipment object associated with the shipment.
"success": true,
"error": null,
"message": null
}
RemoveShipmentObject
Location /v1/Logistics/RemoveShipmentObject
Removes an item from a shipment
{
# Mandatory Fields
"shipmentUid": "...", # Unique ID of the shipment you want to remove the item from
"shipmentObjectUid": "7a0e489...78f166" # Unique ID of the object you want to delete
}
POST /v1/Logistics/RemoveShipmentObject HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"shipmentUid": "256d670c-5ec7-4641-8bf6-d4eb8c176359",
"shipmentObjectUid": "7a0e489...78f166"
}
{
"shipmentUid": "710adbe...fdea72", # Unique id of the shipment requested.
"shipmentObjectUid": "7a0e489...78f166", # Unique identifier of the shipment object associated with the shipment.
"success": true,
"error": null,
"message": null
}
SetShipmentReceiver
Location /v1/Logistics/SetShipmentReceiver
Sets the shipment's receiver to the specified user. This is only valid when the shipment has no receiver (yet) and when the shipment is not (yet) in the ReadyForPickup state.
{
# Mandatory Fields
"shipmentUid": "", # Unique id of the shipment that should be changed.
"toUserUid": "", # Unique id of the user to set as the receiver.
# Optional Fields
"caseReferenceNew": null, # Is specified (not null) this will override the case reference number on
# the specified shipment. This only applies if RemoveReceiver is false.
"removeReceiver": true/false # If set to true the receiver will be removed. The receiver can only be
# removed if the shipment has a user and if the shipment is not already
# picked up by the user (state=ReadyForPickup). Any value specified in
# the ToUserUid field will be ignored.
# Default: false
}
POST /v1/Logistics/SetShipmentReceiver HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"shipmentUid": "472843a4322a4a2686286f07fd6eabe4",
"toUserUid": "638f2fa4722a4a2686286f07fd6ea2fa"
}
{
"success": true/false, # Command executed successfully
"error": null, # Error code (if any)
"message": null # Error message (if any)
}
error code |
Description |
|---|---|
| Generic Error Codes | Any of the generic error codes. |
| InvalidShipmentState | The booking is in a different status, so the recipient can no longer be set. |
CancelShipment
Location /v1/Logistics/CancelShipment
Cancels a previously registered shipment, releasing any booked lockers.
{
# Mandatory Fields
"shipmentUid": "", # Unique id of the shipment that should be cancelled.
}
POST /v1/Logistics/CancelShipment HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"shipmentUid": "472843a4322a4a2686286f07fd6eabe4",
}
{
"success": true/false, # Command executed successfully
"error": null, # Error code (if any)
"message": null # Error message (if any)
}
SimulateLockerAccess
Location /v1/Logistics/SimulateLockerAccess
Only available in the staging-environment. Simulates access to a single locker using given pincode. This advances any shipment to its next state and can be usefull while integrating the API.
{
# Mandatory Fields
"pupUid": "", # Unique id of the pick up point to simulate locker access on.
"lockerName": "", # Name of the locker to simulate access on.
"pinCode": "", # Pincode to simulate on the locker.
}
POST /v1/Logistics/SimulateLockerAccess HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"pupUid": "6d35c61f3fba4186a8c276bb9b9a2f63",
"lockerName": "10",
"pinCode": "1234"
}
{
"success": true/false, # Command executed successfully
"error": null, # Error code (if any)
"message": null # Error message (if any)
}
UnlockShipmentLocker
Location /v1/Logistics/UnlockShipmentLocker
Unlocks a locker that is assigned to the the shipment. It can optionally validate the user's access code. When the shipment is in an invalid state, or not (yet) assigned to a locker, this call will fail.
Please note the unlockGoal attribute.
When the DropOff value is specified, it will unlock the lock only when the shipment is currently ready for drop off.
When PickUp is specified, the locker will only be unlocked when the shipment is ready for pick up.
When not specified (or null) the lock will open unconditionally of the shipment's state.
{
# Mandatory Fields
"shipmentUid": "", # Unique id of the shipment to unlock the locker for.
# Optional Fields
"unlockGoal": "", # Goal of the locker access.
# Valid values: DropOff, PickUp, null
"pinCode": "", # Access code to validate. When empty no code
# validation is applied and the locker will
# unlock unconditionally of the code.
}
POST /v1/Logistics/UnlockShipmentLocker HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json
{
"shipmentUid": "6d35c61f3fba4186a8c276bb9b9a2f63",
"unlockGoal": "DropOff",
"pinCode": null
}
{
"success": true/false, # Command executed successfully
"error": null, # Error code (if any)
"message": null # Error message (if any)
}
error code |
Description |
|---|---|
| Generic Error Codes | Any of the generic error codes. |
InvalidShipment |
Shipment is unknown or unmanagable by current account. |
InvalidShipmentState |
Shipment is known but can't be unlocked at this moment. |
UnlockNotAllowed |
Specified unlockGoal is not allowed at this moment. |
InvalidAccessCode |
A pinCode is specified but it is not valid. |
UnlockFailed |
Unlock failed for an unknown (could be hardware related) reason. |
ShipmentStatusUpdate (Callback)
Sent to the callback url when a shipment's status (stateCode) has changed.
Look at the protocol section for more information about callback messages.
{
"messageType": "ShipmentStatusUpdate",
"message": {
"shipmentUid": "", # Used in HMAC as value to hash
"stateCode": "WaitForReceiver",
"stateStart": "2015-03-25T16:14:01",
"shipmentType": "LocalPupShipment",
"referenceNo": "",
"referenceCaseNo": "",
"description": ""
}
}