logo
API docs by Redocly

EDI Engine API for Developers (v1)

Download OpenAPI specification:Download

License: Contact PTC for terms and conditions

Introduction

The EDI Engine API offers GET and POST methods to request operational business data - converted from EDI messages received from partners - or to import data into EDI Engine to generate EDI messages.

This API reference explains each of the API endpoints, with example REST requests and responses included.

Authorization

To use the EDI Engine API, you need to include a token, EDI mail box and application id with each call.

Event Mapping Services

Imports mapping between operational event codes and EDI event codes

Import Event Mapping

Before starting to use the EDI Engine APIs, operational events need to be mapped to EDI event types.

Mail systems define their own operational events, which can be associated with EDI event types. EDI engine allows to define mapping between these two types of events so that mail systems can extract or send business data based on operational events. The mapping can be defined only between events that are associated with the same type of mail unit types:

Mail unit type code Description
MI Mail item
RC Receptacle
DP Dispatch
CS Consignment
CR Customs response / Referral
CT Container
PP Postal payment
RS Referral response

Examples of possible mapping entries:

  • mail item operational events with code 1 shall trigger EMSEVT EMA message
  • receptacle events with code 130 shall trigger RESCON and RESDES messages

The event mapping configuration API allows to map one or more operational events to one same EDI event type. The following mapping allows to generate EMSEVT EMD event for two different operational events:

  • 30 operational event - EMSEVT EMD event
  • 42 operational event - EMSEVT EMD event

In order to convert incoming EDI events to operational events, the event mapping configuration API allows to map one EDI event type to one operational event type. The parameter preferredReverseMapping is set to true to define the reverse mapping.

Access to this method is authorized by token.

The mapping does not allow to specify EDI message version.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
header Parameters
applicationId
required
string

A specific string defined for country

address
required
string

EDI mailbox address (like NL330). If operator has several mailbox addresses one can be configured in the system

Request Body schema: application/json
Array of objects (MappingData)

Array that has all mapping data

Responses

Request samples

Content type
application/json
{
  • "mapping": [
    ]
}

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Mail Items Services

Imports and retrieves mail item data

Export Mail Items

Retrieves a list of mail items' business data - converted from imported EMSEVT messages - based on query parameters

Access to this method is authorized by token.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
query Parameters
itemIdentifier
string
Example: itemIdentifier=RU993618685NL

Specifies the unique identifier of a mail item. When provided, only the data associated with this specific mail item will be retrieved.

events
Array of strings
Example: events=["1", "8", "30"]

A list of operational events that client is interested in

localDateFrom
required
string <date-time>
Example: localDateFrom=2024-02-29T13:20:00

Specifies local date and time on or after operational events recorded

localDateTo
string <date-time>
Example: localDateTo=2024-02-29T13:30:00

Specifies local date and time on or before operational events recorded

timeOffset
number <double>
Example: timeOffset=1

Time zone value between local time and UTC time

header Parameters
applicationId
required
string

A specific string defined for country

address
required
string

EDI mailbox address (like NL330). If operator has several mailbox addresses one can be configured in the system

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": {
    }
}

Import Mail Items

Imports mail item data.

  • Mail items are created if they do not exist
  • Mail items' data is updated if mail items exist and EDI messages are resent with new data

Access to this method is authorized by token.

IIS limits the packet size; therefore: it is not recommented to include more than 200 mail items' data in a single call.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
header Parameters
applicationId
required
string

A specific string defined for country

address
required
string

EDI mailbox address (like NL330). If operator has several mailbox addresses one can be configured in the system

Request Body schema: application/json
Array of objects (MailItemData)

Responses

Request samples

Content type
application/json
{
  • "mailItems": [
    ]
}

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Customs Declaration Data Services

Imports and retrieves customs declaration data

Export Customs Declaration Data

Retrieves customs declaration business data - converted from imported ITMATT messages - based on query parameters

Access to this method is authorized by token.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
query Parameters
itemIdentifier
string
Example: itemIdentifier=CP163815968CH

S10 item identifier. If specified, customs declarations data only for this identifier will be retrieved.

localDateFrom
string <date-time>
Example: localDateFrom=2024-02-29T13:20:00

Specifies local date and time on or after customs declaration data recorded

localDateTo
string <date-time>
Example: localDateTo=2024-02-29T13:30:00

Specifies local date and time on or before customs declaration data recorded

timeOffset
number <double>
Example: timeOffset=1

Time zone value between local time and UTC time

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": {
    }
}

Import Customs Declaration Data

Imports customs declaration data.

  • Customs declaration data is created if it does not exist
  • Customs declaration data is updated if declaration exist and EDI messages are resent with new data

Access to this method is authorized by token.

IIS limits the packet size; therefore: it is not recommented to include more than 200 customs declaration data in a single call.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
Request Body schema: application/json
Array of objects (CustomsDeclarationData)

Responses

Request samples

Content type
application/json
{
  • "customsDeclarations": [
    ]
}

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Cargo Consignments Services

Retrieve cargo consignments

This API method enables postal operators and customs authorities to retrieve scheduled arrival details for cargo consignments and the mail items they contain.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
query Parameters
capturedTimeStampFrom
required
string <date-time>
Example: capturedTimeStampFrom=2025-06-01T13:20:00

Specifies UTC date and time on or after cargo consignments information was recorded

capturedTimeStampTo
string <date-time>
Example: capturedTimeStampTo=2025-06-01T15:20:00

Specifies UTC date and time before cargo consignments information was recorded

senderReferenceNo
string

Identifier of the sender of the cargo consignment (e.g., EORI number for shipments into EU)

billNo
string
Example: billNo=HKG123456A

The identifier of the waybill / bill of lading

containerIdentifier
string
Example: containerIdentifier=AKE12345

A unique alphanumeric identifier representing the container

itemIdentifier
string

A mailitem identifier (S10, S26 or other) stored in container

transportNo
string
Example: transportNo=LX1279

A full transport number

arrivalLocationCode
string
Example: arrivalLocationCode=DEFRA

Arrival location code of a segment

arrivalDateFrom
string
Example: arrivalDateFrom=2024-02-29T10:20:00

The start of the arrival time range for filtering segments. Expressed in local time

arrivalDateTo
string
Example: arrivalDateTo=2024-02-29T14:20:00

The end of the arrival time range for filtering segments. Expressed in local time

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": {
    }
}

Import Cargo Consignments Data

Imports detailed information about containers and mail items included in cargo consignments.

This method is intended for use by consolidators’ IT systems and should be invoked whenever a consignment is prepared for dispatch to the destination country’s postal operator.

The method performs the following operations:

  • Creates new cargo consignments if they do not already exist in the system.
  • Updates existing cargo consignments and transmits the updated information to partner systems.
  • Validates the structural integrity of the consignment’s transport sequence and item identifiers.

Validation Rules:

  • The temporal and spatial order of transport segments must be preserved:
  • Segment N+1 must depart from the arrival location of segment N.
  • Segment N+1 must depart after the arrival date/time of segment N.
  • Container and mail item identifiers must be unique within the same consignment to prevent duplication and ensure traceability.

Note: Due to IIS packet size limitations, it is recommended to include no more than 200 cargo consignments in a single API call to ensure reliable processing.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
Request Body schema: application/json
Array of objects (ImportCargoConsignmentData)

Responses

Request samples

Content type
application/json
{
  • "cargoConsigments": [
    ]
}

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Reference Configuration Services

Retrieve a list of transport companies.

Returns a list of valid transport companies configured in the system.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": [
    ]
}

Retrieve transport company information

Retrieves information about a transport company for cargo transport data.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
query Parameters
code
required
string
Example: code=LH

Unique code of the transport company

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": {
    }
}

Register a transport company for cargo transport services

Creates a new entry in the system for a transport company involved in cargo logistics and optionally updates its validity status.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
Request Body schema: application/json
code
string [ 1 .. 17 ] characters

Unique code of the transport company (e.g., LH)

name
string [ 1 .. 256 ] characters

Transport company name (e.g., Deutsche Lufthansa Aktiengesellschaft)

codeSource
string [ 1 .. 8 ] characters

A short identifier representing the government agency or industry organization responsible for assigning or tracking company codes used in transportation and logistics. (e.g., IATA)

valid
boolean

Indicates whether the company is currently valid and operational. - true: The company is active and recognized as a valid entity. - false: The company is no longer valid.

Responses

Request samples

Content type
application/json
{
  • "code": "LH",
  • "name": "Deutsche Lufthansa Aktiengesellschaft",
  • "codeSource": "IATA",
  • "valid": true
}

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Retrieve a list of transport locations.

Returns a list of valid transport locations configured in the system.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": [
    ]
}

Retrieve transport location information

Retrieves information about a transport location for cargo transport data.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
query Parameters
code
required
string
Example: code=LH

Unique code of the transport location

Responses

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": {
    }
}

Register location information for cargo transport data

Imports information about location.

This method is intended to import data used in cargo consignment services.

Authorizations:
(Auth_TokenAuth_ApplicationIdAuth_EDI_Address)
Request Body schema: application/json
code
string [ 1 .. 5 ] characters

Unique code of the location (e.g., DEFRA)

name
string [ 1 .. 64 ] characters

Full location name (e.g., Frankfurt)

codeSource
string [ 1 .. 8 ] characters

A short identifier representing the government agency or industry organization responsible for assigning or tracking location codes used in transportation and logistics. (e.g., IATA)

valid
boolean

Indicates whether the location is currently valid and operational. - true: The location is active and recognized as a valid entity. - false: The location is no longer valid.

Responses

Request samples

Content type
application/json
{
  • "code": "DEFRA",
  • "name": "Frankfurt",
  • "codeSource": "IATA",
  • "valid": true
}

Response samples

Content type
application/json
{
  • "responseStatus": {
    },
  • "data": null
}