This article will explain how to use the API to create and manage containers. It will explain the possible parameters and list the different methods used.
Go to:
Authentication and HTTP responses
Using the API requires the use of tokens (Client IDs and Client Secrets. The authorization and authentication is compliant with OAuth2 and all the methods of the public API will have authorization token (access_token) in the Http Header.
To learn how to create a token, please read this article: API configuration setup.
Our recommendation for all Portal Apis is to use the HTTPS (version TLS 1.2 minimum) in order to function properly and have enhanced security.
Endpoint
https://customer-api.consignorportal.com/ApiGateway/Containers/Containers
(The endpoint can only be used for sending requests and not opened in a browser)
Meaning of HTTP status codes:
HTTP Status Code - 200 OK --> Data successfully received and is sent for processing
HTTP Status Code - 401 Unauthorized --> Not valid credentials
HTTP Status Code - 400 Bad Request --> Invalid input data
HTTP Status Code - 500 InternalServerError --> Unknown error
Parameters
| ParentIdentifier |
| This is the identifier of the “parent” container. This could be a barcode on a shipment or package, or this could be related to a virtual container. If this is a virtual container it would reference either an ID or a string (example could be to reference a “delivery route” --> London east). |
| Type: string |
| MinLength: 2 |
| MaxLength: 50 |
| Required: Yes |
| IsVirtualParent |
| If this option is set to true it means that the property “ParentIdentifier” refers to a virtual entity and is not linked to a physical shipment or package. The string used for input will be reused in case you reference the same string again. |
| Type: bool |
| Required: No |
| Default: false |
| ActionCenterUuid |
| This refers to unique indentifier of ActionCenter. Provide this identifier if you intend to use Scan App. ActionCenterUuid will be associated to all container definitions and to the template in case of a virtual container. |
| Type: string |
| Required: No |
| ChildrenIdentifier |
|
This refers to the list of items that will be added into the parent container. This refers to the barcodes used on shipments or packages. Maximum number of items in this list is set to 50. If you need to add more items to a container use the separate action 2.2 "Add Children to Container". |
| Type: List<string> |
| Min item length: 2 |
| Max item length: 50 |
| Required: yes |
| Maximum count: 50 |
| DateCreated |
| Local Iso8601datetime with offset. Example of correct format: "2019-07-01T17:55:13+02:00". Please note that we only support the extended notations, not the basic notations without hyphens. |
| Type: DateTimeOffset |
| Required: Yes |
| MaxDaysOld |
| The maximum days of validity of ParentIdentifier if referenced against shipment or packages. This is not used for the virtual containers. Default number of days will be set to 10 days. |
| Type: int |
| Required: no |
| Default: 10 |
| Maximum value: 90 |
| EventCode |
| If you would like to add an event along with the container you can input a EventCode. This will then be populated on all children on the given container. |
| Type: string |
| Required: No |
Methods
Actions available
|
Action |
Resource |
GET |
POST |
PUT |
PATCH |
DELETE |
|
/Containers/ |
NO |
YES |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/ |
NO |
NO |
YES |
NO |
NO |
|
|
/Containers/{Uuid}/Close/ |
NO |
YES |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/Events/ |
NO |
YES |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/Children/Count/ |
YES |
NO |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/Children/ |
YES |
NO |
NO |
NO |
NO |
|
|
/Containers/children/{identifier} |
YES |
NO |
NO |
NO |
NO |
|
|
/Containers/Active?identifier={ identifier}&pageSize={pageSize}&pageIndex={pageIndex} |
YES |
NO |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/Lock/ |
YES |
NO |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/Lock/ |
NO |
YES |
NO |
NO |
NO |
|
|
/Containers/{Uuid}/Lock/ |
NO |
YES |
NO |
NO |
NO |
Create container
HTTP POST: /../Containers/
Will create the container and return back the unique identifiers needed.
Request syntax
{
"ParentIdentifier":string,
"ChildrenIdentifier" : [string],
"DateCreated" : datetime,
"IsVirtualParent" : bool,
"MaxDaysOld" : int,
"EventCode" :string
}
Response syntax
{
"ParentUuid":string
}
Request example:
{
"ParentIdentifier":"4015468532135485",
"ChildrenIdentifier" : [{"4015468532198642"},{"4015468532142516"}]
"DateCreated" : "2013-07-01T17:55:13+02:00",
"IsVirtualParent" : false,
"MaxDaysOld" : 15,
"EventCode" : "B542"
}
Response example:
{ "911BD835-DBAE-4881-9590-5F00E5812060" }
Add children to container
HTTP PUT: /../Containers/{uuid}/
Use this call in order to add one more children to existing container. If EventCode is provided, this will propagate the event to children attached to the container.
Container unique identifier will be provided in the URI {uuid}.
Request syntax
{
"ChildrenIdentifier" : [string],
"DateCreated" : datetime,
"MaxDaysOld" : int,
"EventCode" : string
}
Response syntax
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Request example: ParentUuid will be provided in URL.
{
"ChildrenIdentifier" : [
{
"40100000000000000004"
},
{
"40100000000000000005"
},
{
"40100000000000000006"
}
],
"DateCreated" : "2013-07-01T17:55:13+02:00",
"IsVirtualParent" : false,
"EventCode" : "A5458"
}
Response example:
HTTP 200 OK
Close container
HTTP POST: /../Containers/{uuid}/Close
Use close container in order to close and update the relationship for all the connected children. Once the the tree is closed, no more children can be added to container.
Container unique identifier will be provided in the URI {uuid}.
Request syntax
ParentUuid from uri
Response syntax
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Request example:
ParentUuid will be provided in URL.
Response example:
HTTP 200 OK
Send event to container
HTTP POST: /../Containers/{uuid}/Event
Use Event call in order to send event on a container and it’s linked children. The event will be propagated to all level children. In case of a closing event (defined on the event), the status of container will be set to "Closed" (since all children would be considered closed, the container will also be automatically closed). ParentUuid will be provided in URL. EventCode is mandatory.
Container unique identifier will be provided in the URI {uuid}.
Request syntax
{
"EventCode" : string,
"DateCreated" : datetime
}
Response syntax
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Request example:
ParentUuid will be provided in URL.
{
"EventCode" : "B5469",
"DateCreated" : "2013-07-01T17:55:13+02:00"
}
Response example:
HTTP 200 OK
Get container children count
HTTP GET: /../Containers/{uuid}/Count
Use Count call in order to get the count of total number of level 1 children (as the container might contain other virtual containers with its own children, the total count could be higher if you count all levels)
Container unique identifier will be provided in the URI {uuid}.
Request syntax
ParentUuid from uri
Response syntax
intValue
Request example:
GET …./ /Containers/911BD835-DBAE-4881-9590-5F00E5812060/Count
Response example:
5
Get container children
HTTP GET: /../Containers/{uuid}/Children
Use Children call in order to get the list of level 1 children. HasChildren will be set to true in case they have children otherwise to false.
Container unique identifier will be provided in the URI {uuid}.
Request syntax
ParentUuid from uri
Response syntax
{
[
{
"ChildUuid": string,
"ChildIdentifier": string,
"HasChildren" : bool
}
]
}
Request example:
GET …./ /Containers/911BD835-DBAE-4881-9590-5F00E5812060/Children
Response example:
{
[
{
"ChildUuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
"ChildIdentifier": "Child1Identifier",
"HasChildren" : true
},
{
"ChildUuid": "BEDFBB40-C1BA-4900-94D3-80C5C24CFF06",
"ChildIdentifier": "Child2Identifier" ,
"HasChildren" : false
}
]
}
Get active parent of active child
HTTP GET: /../Containers/Children/{identifier}
Use Children call in order to get the active parent of active child based on child identifier. In case of no active container an empty response will be returned.
Child identifier will be provided in the URI { identifier } and is mandatory.
Request syntax
ChildIdentifier from uri
Response syntax
{
"ParentUuid": string,
"ParentIdentifier": string
}
Request example:
GET …./ /Containers/Children/4015468532198642
Response example:
{
"ParentUuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
"ParentIdentifier": "4015468532135485"
}
Get active containers
HTTP GET: /../Containers/Active?identifier={identifier}&&pageSize={pageSize}&&pageIndex={pageIndex}
Use active call in order to return all active first level containers associated to user context. In case of no active container an empty response will be returned.
Container identifier is optional and can be provided in the URI { identifier }. If provided, "starting with" filter will be applied on the string input.
Request syntax
pageSize: int from Uri; optional field; default value 50. Maximum value 50.
pageIndex: int from Uri; optional field
identifier:string from Uri; optional field
Response syntax
[
{
"Uuid": string,
"Identifier": string
}
]
Request example:
GET ….//Containers/Active
GET ….//Containers/Active?pageIndex=0
GET ….//Containers/Active?pageIndex=0&&pageSize=15
GET ….//Containers/Active?identifier=40154685321354
GET ….//Containers/Active?pageIndex=0&&identifier=40154685321354
GET ….//Containers/Active?pageIndex=0&&pageSize=15&&identifier=40154685321354
Response example:
[
{
"Uuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
"Identifier": "4015468532135485"
},
{
"Uuid": "241B3F4E-6D02-4EA5-A7FB-E728D4CC8148",
"Identifier": "4015468532135400"
}
]
Get active containers
HTTP GET: /../Containers/Active?identifier={identifier}&&pageSize={pageSize}&&pageIndex={pageIndex}
Use active call in order to return all active first level containers associated to user context. In case of no active container an empty response will be returned.
Container identifier is optional and can be provided in the URI { identifier }. If provided, "starting with" filter will be applied on the string input.
Request syntax
pageSize: int from Uri; optional field; default value 50. Maximum value 50.
pageIndex: int from Uri; optional field
identifier:string from Uri; optional field
Response syntax
[{
"Uuid": string,
"Identifier": string
}]
Request example:
GET ….//Containers/Active
GET ….//Containers/Active?pageIndex=0
GET ….//Containers/Active?pageIndex=0&&pageSize=15
GET ….//Containers/Active?identifier=40154685321354
GET ….//Containers/Active?pageIndex=0&&identifier=40154685321354
GET ….//Containers/Active?pageIndex=0&&pageSize=15&&identifier=40154685321354
Response example:
[
{
"Uuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
"Identifier": "4015468532135485"
},
{
"Uuid": "241B3F4E-6D02-4EA5-A7FB-E728D4CC8148",
"Identifier": "4015468532135400"
}
]
Get container by identifier or uuid
HTTP GET: /ContainerWS/Public/Containers/Container?identifier={identifier}&active={active}
HTTP GET: /ContainerWS/Public/Containers/Container?uuid={uuid}&active={active}
Use this call to retrieve containers by identifier or uuid and active status. By default, the search will be done only based on active containers. In case you want to get also the inactive containers, you should use "active" parameter with false value.
In case no container was found based on searching criteria provided, HttpStatus code 200 OK will be received with empty body.
Request syntax
identifier:string from Uri; optional parameter
uuid:string from Uri; optional parameter
active:bool from Uri; optional parameter; default value true
Response syntax:
[{
"ContainerUuid": string,
"ContainerIdentifier": string,
"LocalDate": datetime,
"IsActive" : bool,
"ChildrenCount" : bool
}]
Request example:
GET …./ /Containers/Container?identifier=40170726204100091188
GET …./ /Containers/Container?identifier=40170726204100091188&active=false
GET …./ /Containers/Container?identifier=40170726204100091188&active=true
GET …./ /Containers/Container?uuid=a0793270-5de8-4f6b-be1d-9321e43b703d
GET …./ /Containers/Container?uuid=a0793270-5de8-4f6b-be1d-9321e43b703d&active=false
GET …./ /Containers/Container?uuid=a0793270-5de8-4f6b-be1d-9321e43b703d&active=true
Response example:
Example 1:
[
{
"ContainerUuid": "c208421e-a249-4d7a-ba9a-35d85de6dd01",
"ContainerIdentifier": "40170726204100091188",
"LocalDate": "2019-08-30T10:53:07",
"IsActive": false,
"ChildrenCount": 3
},
{
"ContainerUuid": "6fc110ad-30cb-4166-bb3f-381813985fc5",
"ContainerIdentifier": "40170726204100091188",
"LocalDate": "2019-08-30T10:56:24",
"IsActive": false,
"ChildrenCount": 2
},
{
"ContainerUuid": "fd977b22-1c17-40cd-9966-7e8b92568dce",
"ContainerIdentifier": "40170726204100091188",
"LocalDate": "2019-08-30T10:57:57",
"IsActive": false,
"ChildrenCount": 2
}
]
Example 2:
[
{
"ContainerUuid": "a0793270-5de8-4f6b-be1d-9321e43b703d",
"ContainerIdentifier": "40170726204100105809",
"LocalDate": "2019-09-03T12:53:12",
"IsActive": true,
"ChildrenCount": 1
}
]
Lock container
HTTP POST: /ContainerWS/Public/Containers/{uuid}/Lock
Use this call to lock a virtual container. Once the container is locked, no children can be added to the container with “Add Children to Container” method. A new container should be created using “Create Container” method. "Create container" method will not be allowed if there is another not locked container for the same template. Only one virtual container per template at a time can be unlocked.
Only virtual active containers created by the owner that is initiating the request can be locked. In case of at least one criteria is not met BadRequest will be returned.
In case operation succeeded HttpStatus code 200 OK will be received with empty body.
Request syntax
containerUuid: mandatory parameter in the URI {uuid}.
Response syntax
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. In case the virtual container was already locked the operation will fail and BadRequest will be returned.
Request example
GET …./ / Containers/Public/Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/Lock
Response example
HTTP 200 OK
Unlock container
HTTP POST: /ContainerWS/Public/Containers/{uuid}/Unlock
Use unlock call to unlock the virtual active container.
Once the container is unlocked, children can be added to the container with “Add Children to Container” method.
A virtual container can be unlocked only if there is no other virtual container with the same template not locked.
Only virtual active containers created by the owner that is initiating the request can be unlocked. In case of at least one criteria is not met BadRequest will be returned.
In case operation succeeded HttpStatus code 200 OK will be received with empty body.
Request syntax
containerUuid: mandatory parameter in the URI {uuid}.
Response syntax
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. In case the virtual container is not locked the operation will fail and BadRequest will be returned.
Request example
GET …./ / Containers/Public/Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/Unlock
Response example
HTTP 200 OK