Skip to content

Get Shipments

This section gives an overview of the API calls used for getting or reading Shipments.

GetShipments

Location /v1/Logistics/GetLocalShipments
Location /v1/Logistics/GetReceiveShipments
Location /v1/Logistics/GetDispatchShipments
Location /v1/Logistics/GetCollectOnlyShipments
Location /v1/Logistics/GetShipments

Gets a list of all the previously registered shipments. Shipments are queried for each ShipmentType.

Also see ShipmentStates for a complete list of available states that can be used in the request.

{
    # Mandatory Fields
    "pageNo": 1,                    # Page number, starting from 1
    "pageSize": 10,                 # Number of items on a single page. Min: 1, Max: 500
    "activeShipments": true/false,  # True or false if to return active shipments or inactive shipments.
                                    #  Active shipments are shipments that are being processed.
                                    #  Inactive shipments are shipments that are completed or cancelled.
                                    #  Either this flag or the ShipmentState should be specified.
    "shipmentState": null/["",""]   # Array of strings containing the shipment states to filter for.
                                    #  Either this property or the ActiveShipments should be specified.

    # Optional fields
    "userUid": "",                  # Unique id of the user that is linked to the shipment.
    "bookedPupUid": "",             # Unique id of the pickuppoint to filter shipments for. this will
                                    #  only return any shipments that are CURRENTLY linked to the PUP. 
    "shipmentUid": "",              # Unique id of the shipment to return. Make sure the PageNo is
                                    #  set to '1' and the PageSize is more than '0'.
    "updatedSince": "",             # Date/time since the last change. This can be null.
    "sortBy":   null/"CreatedAsc"   # The desired sort to use. These sorts are supported:
                                    # CreatedAsc / CreatedDesc -> Sort by created date/time.
                                    # ActivityAsc / ActivityDesc -> Sort by last activity.
}

POST /v1/Logistics/GetLocalShipments HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json

{
    "pageNo": 1,
    "pageSize": 10,
    "activeShipments": true,
    "updatedSince": "2015-03-25T16:14:01"   
}

The response contains one source or target 'type'. It is either a user or an address. It is possible that the from or to address is not specified at all, even when it is a ReceiveShipment or DispatchShipment. In that case the address property will not be part of the result set for that Shipment. Please note that in most cases the addresses (when specified) only contains a name. 

{
  "items": [
    {
      "shipmentUid": "472843a...7fd6eabe4",
      "dateCreated": "2015-09-25T15:07:52",
      "typeCode": "LocalPupShipment",
      "stateStart": "2015-03-25T16:14:01",
      "stateCode": "LockerAssigned",
      "referenceNo": null,                          # Omitted when not specified 
      "referenceCaseNo": null,                      # Omitted when not specified 
      "description": null,                          # Omitted when not specified 
      "fromUserName": "OfficeService",              # Omitted when not specified 
      "fromUserUid": "a274baf...eba1170",           # Omitted when not specified
      "fromAddress": {                              # Omitted when not specified
        "name": "James B",
        "street": null,                             # Can contain multiple lines
        "mailbox": null,
        "city": null,
        "countryIso2": null
      },
      "toUserName": "test@klm.nl",                  # Omitted when not specified 
      "toUserUid": "638f2fa...7fd6ea2fa",           # Omitted when not specified 
      "toAddress": {                                # Omitted when not specified
        "name": "Melissa Washington",
        "street": "Office 10A\r\nStreet 10",        # Can contain multiple lines
        "mailbox": "1012 AA",
        "city": "Amsterdam",
        "countryIso2": "NL"
      },
      "swapsShipmentUid": null,
      "bookedPupName": null,
      "bookedPupUid": null,
      "bookedLockerName": null
    }
  ],
  "pageNo": 1,
  "pageSize": 10,
  "totalItems": 1,
  "totalPages": 1,
  "success": true,
  "error": null,
  "message": null
}

GetShipmentObjects

Location /v1/Logistics/GetShipmentObjects

Gets the related objects of the shipment

{
    # Mandatory Fields
    "shipmentUid": "..."            # Unique id of the shipment to query.
}

POST /v1/Logistics/GetShipmentObjects HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json

{
    "shipmentUid": "710adbe8560c4df7b43d2191acfdea72"
}

{
  "shipmentUid": "710adbe...fdea72",                    # Unique id of the shipment requested.
  "items": [ 
        "shipmentObjectUid": "7a0e489...78f166",        # Unique identifier of the shipment object associated with the shipment.
        "referenceNo": "402908467",                     # Your reference number
        "description": "",                              
        "weight": 1000,                                 # Weight in grams
        "count": 1,                                     # Total object parts
        "dimension": {                                  # Dimension of the package in centimeters
            "width": 40,
            "height": 30,
            "length": 60
        }
  ],
  "pageNo": 1,
  "pageSize": 10,
  "totalItems": 0,
  "totalPages": 0,
  "success": true,
  "error": null,
  "message": null
}

GetShipmentSwaps

Location /v1/Logistics/GetShipmentSwaps

Gets the related (chain of) shipments that the specified shipment swaps or will be swapped to.

{
    # Mandatory Fields
    "pageNo": 1,                    # Page number, starting from 1
    "pageSize": 10,                 # Number of items on a single page. Min: 1, Max: 500
    "shipmentUid": "..."            # Unique id of the shipment to query.
}

POST /v1/Logistics/GetShipmentSwaps HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json

{
    "pageNo": 1,
    "pageSize": 10,
    "shipmentUid": "710adbe8560c4df7b43d2191acfdea72"
}

{
  "shipmentUid": "710adbe...fdea72",        # Unique id of the shipment requested.
  "swapsShipmentUid": "dab0...352",         # Unique id the shipment that this shipment will swap (from).
  "swapWithShipments": [ "...", "..."],     # List of unique shipment ids that this shipment will swap to.
  "pageNo": 1,
  "pageSize": 10,
  "totalItems": 0,
  "totalPages": 0,
  "success": true,
  "error": null,
  "message": null
}

GetShipmentAccessConfig

Location /v1/Logistics/GetShipmentAccessConfig

Gets the shipment's access configuration information (like locker access codes).

Please note that there are three types of QR codes:

  1. A QR code that can only be scanned at the physical terminal (when installed) to unlock the locker for dropping off an item into a locker. These are the codes with Usage=DropOff and Type=Qr
  2. A QR code that can only be scanned at the physical terminal to unlock the locker for picking up an item into a locker. These are the codes with Usage=PickUp and Type=Qr
  3. A QR code that can only be scanned using the MyPup app. These are the codes with Usage=LinkCode and Type=Qr
{
    # Mandatory Fields
    "shipmentUid": "",      # Unique id of the shipment to retrieve the codes for.

    # Optional Fields
    "usage": null           # Filter the usage type to retrieve codes for. When jull all the codes will
                            # be returned. Valid values: DropOff, PickUp, LinkCode, or null
}

POST /v1/Logistics/GetShipmentAccessConfig HTTP/1.1
Host: api.staging.mypup.app
Authorization: Bearer ......
Content-Type: application/json

{
    "shipmentUid": "472843a4322a4a2686286f07fd6eabe4", 
    "usage": null
}

{
  "success": true/false,            # Command executed successfully
  "error": null,                    # Error code (if any)
  "items": [                        # List of access codes
    {
      "usage": "PickUp",            # Usage type of this access code. Valid values: DropOff, PickUp, LinkCode
      "type": "Code",               # Type of the access code/value. Valid values: Code
      "value": "1234"               # The access code that can be used to unlock the locker.
    },
    {
      "usage": "DropOff",           
      "type": "Code",               
      "value": "4321"               
    },
    {
      "usage": "LinkCode",          # A LinkCode is a code that can be used by the MyPup app to deeplink
                                    # directly to a shipment using by scanning this code via a QR image.
                                    # There could be multiple LinkCodes for a single shipment.
                                    # In that case, the LinkCode code is the most recent one.
      "type": "Qr",             
      "value": "U(JFH&*^G%*%^()H&"
    }
  ]
}