This article will explain how to use the Consignor 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 Consignor 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.
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 |
| 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. |
| Type: string |
| Required: No |
| Default: false |
| 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> |
| 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: DateTime |
| 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 |
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"
}
]