logo

Dispatch import service

Imports dispatches

Import dispatch

Imports closed outbound dispatch data with all associated receptacle and mail item information.

Access to this method is authorized by the Import dispatches operation.

Note: You can only import closed dispatches and receptacles. Dispatch update is not supported.

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 dispatch, receptacle, bundle, inner bag or mail item.
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 insert a parcel in a letter receptacle.
5 No transport found for the dispatch.
6 The route exists but is not compatible with the dispatch.
7 Data already exists in the database.
8 Failure storing the dispatch, receptacle, bundle , inner bag or mail item.
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.
12 Configuration based rejection
Securityips_token
Request
query Parameters
returnDocuments
string <boolean>

Default value false

useAlternateRoutes
string <boolean>

Default value false. Enables the use of routes marked as alternate.

Request Body schema: application/json
DispatchId
required
string <= 20 characters ^[A-z0-9]{20}$

Dispatch identifier. Format must be compliant with S8 UPU standard

DispatchPreviousSerialNo
number <= 4 characters ^[0-9]{4}$

Previous dispatch serial number (omitted for the first dispatch of the series)

DispatchWeight
required
number <float> ^[0-9]{9}\.[0-9]{3}$

Dispatch weight

DispatchEarliestDeparture
required
string <date-time>

Earliest possible departure date/local time of the dispatch

DispatchRouteScheduleIdentifier
string <= 36 characters ^[A-z0-9]{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.

DispatchClosureDateTime
required
string <date-time>

Date/time of the dispatch closure event. Time is local, plus offset from GMT

DispatchProductType
string or null

Product type

Null UPU parcels

C e-commerce parcels

G Interconnect Standard

H Interconnect Premium

K Kahala

M PRIME

P EPG

Enum: "C" "G" "H" "K" "M" "P"
DispatchComments
string <= 256 characters ^[A-z0-9]{256}$

Comment on the dispatch

required
Array of objects (DispatchOtbCNs)
required
Array of objects (Receptacles)
Responses
200

Success

400

Bad Request

401

Unauthorized

404

Not Found

500

Internal Server Error

post/DispatchImportService.svc/rest/dispatch
Request samples
application/json
{
  • "DispatchId": "CHZRHBNZAKLAAUN00005",
  • "DispatchPreviousSerialNo": 4,
  • "DispatchWeight": 10.5,
  • "DispatchEarliestDeparture": "2020-06-30 00:00",
  • "DispatchRouteScheduleIdentifier": "8E98516B-1864-4B86-AB45-1CB92117D60D",
  • "DispatchClosureDateTime": "2020-06-29T16:38:06+01:00",
  • "DispatchProductType": "C",
  • "DispatchComments": null,
  • "DispatchOtbCNs": [
    ],
  • "Receptacles": [
    ]
}
Response samples
application/json
{
  • "Dispatch": {
    }
}

Add receptacles to dispatch

The imported receptacles will have state closed and will be inserted into an open dispatch.

  • The dispatch may be specified explicitly (by FID).
  • The dispatch may be chosen automatically depending on the receptacle characteristics.
  • The dispatch may be created if no suitable open dispatch exists.

The API response will include all necessary documents for the closed receptacle (all the documents that would be printed if the receptacle was closed in IPS)

Access to this method is authorized by the Import dispatches operation.

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 General error.
2 Mandatory value not provided.
3 A property value in the request contains an invalid value or is in the wrong format.
4 Receptacle mail subclass not compatible with dispatch.
5 Creation of the loose mail bundle(s) is prohibited for dispatch with certain mail subclass.
6 Non-exempt bundle in exempt receptacle.
7 Duplicate mail item identifiers.
8 Inner bag not found.
9 Dispatch not found.
10 Dispatch not opened.
11 Failed to create dispatch.
12 Failed to create and close receptacle.
13 Failed to close dispatch.
14 Failed to obtain dispatch lock.
Securityips_token
Request
query Parameters
closeDispatch
string <boolean>

Default value false. The url parameter closeDispatch indicates that the dispatch should be closed after the receptacle has been imported. The last receptacle closed will be marked as final. If the dispatch contains open receptacles, then these will be closed if the parameter “AllowAutoCloseReceptacles” is true (the default value); if the parameter “AllowAutoCloseReceptacles” is false, then it is not possible to close this dispatch.

allowAutoCloseReceptacles
string <boolean>

Default value true. See parameter "closeDispatch" for more details.

allowCreateDispatch
string <boolean>

Default value true. If set to true, IPS will create a new dispatch if no appropriate dispatch found. If set to false will only allow receptacles with an appropriate dispatch existing in IPS.

evaluateSampling
string <boolean>

Default value false. Indicates if receptacle is to be evaluated for (outbound) sampling (as per IPS sampling rule configuration).

useAlternateRoutes
string <boolean>

Default value false. Enables the use of routes marked as alternate.

Request Body schema: application/json
DispatchFId
string = 20 characters

Dispatch identifier

OrigOfficeFCd
string (OfficeFcd) <= 6 characters ^[A-z0-9]{6}$

The full code of an office including its country code

DestOfficeFCd
string (OfficeFcd) <= 6 characters ^[A-z0-9]{6}$

The full code of an office including its country code

MailSubClassFCd
string <= 2 characters ^[A-z0-9]{2}$

Dispatch mail subclass

MailCategoryCd
string (MailCategoryCd)

The mail category code that indicates the transport type and conveyance of the mail

  • A = Air
  • B = S.A.L.
  • C = Surface
  • D = Prio by surface
Enum: "A" "B" "C" "D"
EarliestDispatchClosingTime
string <date-time>

Earliest possible departure date/local time of the dispatch

required
object
object
object
Responses
200

Success

400

Bad Request

401

Unauthorized

404

Not Found

500

Internal Server Error

post/DispatchImportService.svc/rest/receptacles
Request samples
application/json
{
  • "DispatchFId": "PLWAWACZPRGAAUN20003",
  • "OrigOfficeFCd": "FRCDGA",
  • "DestOfficeFCd": "FRCDGA",
  • "MailSubClassFCd": "UN",
  • "MailCategoryCd": "A",
  • "EarliestDispatchClosingTime": "2020-06-30 00:00",
  • "Receptacle": {
    },
  • "EventInformation": {
    },
  • "DispatchCNDetails": {
    }
}
Response samples
application/json
{
  • "Result": {
    }
}
➔ Next to DNL service