You are here:

Create and close consignments

Imports consignment data with all associated receptacle and mail item information. Generates and includes consignment documents as applicable.

The API can import outbound receptacles. These must be closed and already exist in IPS.

The API can import receptacles in transit. These may or may not already exist in IPS.

The consignment update process is not supported. Consignments have to be manually reopened, modified and closed in IPS.

Values set by IPS during import

The following consignment and receptacle values in the IPS tables are automatically set by IPS during import:

Consignment level

The GUID
The postal status set to NULL
The state indicator set to 62 (closed)
The event type set to 301 (Close consignment (Otb))
The conveyance type is automatically set by IPS based on the mail category of the dispatch:
- If mail category is A or D then conveyance type = P
- If mail category is B or C then conveyance type = N
The number of receptacles

Receptacle level

The state indicator set to 22 (closed)
The event type is set to 105 (Change receptacle consignment (Otb))

Triggers

The import of a consignment triggers the creation of:

Accounting dispatch and transit segment information (if the selected route has a closed transit point)
'Events' information
PRECON EDI messages (if activated in the EDI exchanges configuration)
CARDIT EDI messages (if activated in the EDI exchanges configuration)

HTTP request

POST http://[hostname:port]/IPSAPIService/ConsignmentImportService.svc/rest/consignment?token={token}

Parameters

Parameter	Mandatory?	Description
`token`	Y	GUID for authorization

Error

In addition to the standard error codes described in Response codes, the IPS API returns a 404 error code for specific error cases, with additional error information as listed in the table below.

Code	Description
1	Mandatory data is missing from the consignment.
2	A property value in the request contains an invalid value or is in the wrong format.
3	Reference data not found.
4	The request contains inconsistent data. For example, if trying to send a receptacle to the wrong destination office.
5	No transport found for the consignment.
6	The route exists but is not compatible.
7	Data already exists in the database.
8	Failure storing the consignment.
9	The request body does not match the specified structure.
10	Unexpected error handled by the API.
11	Error returned from internal IPS business process.

Request body format

The HTTP body will contain the following fields in JSON format.

Parent	Mandatory/ Optional	Field	Format	Description	Allowed values	Example
Parent	Mandatory/ Optional	Field	Format	Description	Allowed values	Example
-	O	consignmentId	an..12	Consignment identifier		PTLISL000002 Format must be compliant with S32 UPU standard
-	O	consignmentSealNumber	an..15
-	M	consignmentMailCategory	an..1
-	M	consignmentConveyanceType	an...1
-	M	consignmentDepartureDate	YYYY-MM-DD HH:MM	Earliest possible departure date/local time of the consignment		2020-06-30 00:00
-	O	consignmentEMSInd	an…1		1-True, 0-False False if this property is missing in the request.
-	O	consignmentRouteScheduleIdentifier	an..36	Unique identifier of the route schedule (GUID or, in a future IPS release, user friendly route schedule identifier). If omitted, IPS will look for the earliest suitable route schedule after the specified departure date and time.		8E98516B-1864-4B86-AB45-1CB92117D60D
-	M	consignmentOriginOffice	an…6
-	M	consignmentDestinationOffice	an…6
-	O	consignmentComments	an..256
-	O	consignmentTransitOnlyInd	an…1		1-True, 0-False False if this property is missing in the request.
-	O	consignmentContainerId	An..35
	M	Receptacles	Array of Receptacle objects
Receptacle	M	receptacleId	an..29	Receptacle identifier		CHZRHBNZAKLAAUN00001001100105 Format must be compliant with S9 UPU standard
Receptacle	M	receptacleInsertionDateTime	YYYY-MM-DD THH:MM:SS+/-HH:MM	Closure event date/time. Time is local, plus offset from GMT		2020-06-29T16:38:06+01:00

Response body format

The body format for a 200 response is as follows:

Level	Field	Format	Description	Allowed values	Example
1	consignmentId	an..12	Consignment identifier		PTLISL000002 Format must be compliant with S32 UPU standard
Routing information (repeated for each transport segment in the route)
2	transportType	an..2	The type of transport segment	PL Plane TR Train TK Truck SH Ship	PL
2	transportCompanyCode	an..10	The code of the transport company operating the segment	From IPS list of transport companies	LX
2	transportNumber		The number of transport segment		123
2	departureLocation	an..5	The code of the segment departure location	UN location codes	CHZRH
2	departureDT	YYYY-MM-DD HH:MM	The departure date and time of the transport segment (local time)		2020-10-08 21:15
2	arrivalLocation	an..5	The code of the segment arrival location	UN location codes	SGSIN
2	arrivalDT	YYYY-MM-DD HH:MM	The arrival date and time of the transport segment (local time)		2020-10-09 06:20
2	transitOE	an..6	The exchange office of closed transit at the segment destination (empty if no closed transit occurs at the segment destination)	Value from UPU Code List 108	SGSINA
Printable manifests and labels (repeated for each document generated) are also included. See the response example for the format.