logo

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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
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
200

Success

400

Invalid data

post/api/v1/EventMapping
Request samples
application/json
{
  • "mapping": [
    ]
}
Response samples
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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
query Parameters
events
Array of strings

A list of operational events that client is interested in

Example: events=["1", "8", "30"]
localDateFrom
required
string <date-time>

Specifies local date and time on or after operational events recorded

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

Specifies local date and time on or before operational events recorded

Example: localDateTo=2024-02-29T13:30:00
timeOffset
number <double>

Time zone value between local time and UTC time

Example: timeOffset=1
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
200

Success

400

Invalid Input

get/api/v1//MailItems
Response samples
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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
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
200

Success

400

Invalid data

post/api/v1//MailItems
Request samples
application/json
{
  • "mailItems": [
    ]
}
Response samples
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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
query Parameters
itemIdentifier
string

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

Example: itemIdentifier=CP163815968CH
localDateFrom
string <date-time>

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

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

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

Example: localDateTo=2024-02-29T13:30:00
timeOffset
number <double>

Time zone value between local time and UTC time

Example: timeOffset=1
Responses
200

Success

400

Invalid Input

get/api/v1/CustomsDeclarations
Response samples
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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
Request Body schema: application/json
Array of objects (CustomsDeclarationData)
Responses
200

Success

400

Invalid data

post/api/v1/CustomsDeclarations
Request samples
application/json
{
  • "customsDeclarations": [
    ]
}
Response samples
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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
query Parameters
capturedTimeStampFrom
required
string <date-time>

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

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

Specifies UTC date and time before cargo consignments information was recorded

Example: capturedTimeStampTo=2025-06-01T15:20:00
senderReferenceNo
string

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

billNo
string

The identifier of the waybill / bill of lading

Example: billNo=HKG123456A
containerIdentifier
string

A unique alphanumeric identifier representing the container

Example: containerIdentifier=AKE12345
itemIdentifier
string

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

transportNo
string

A full transport number

Example: transportNo=LX1279
arrivalLocationCode
string

Arrival location code of a segment

Example: arrivalLocationCode=DEFRA
arrivalDateFrom
string

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

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

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

Example: arrivalDateTo=2024-02-29T14:20:00
Responses
200

Success

400

Invalid Input

get/api/v1/CargoConsignments
Response samples
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.

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
Request Body schema: application/json
Array of objects (ImportCargoConsignmentData)
Responses
200

Success

400

Invalid data

post/api/v1/CargoConsignments
Request samples
application/json
{
  • "cargoConsigments": [
    ]
}
Response samples
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Reference Configuration Services

Company information for cargo transport data

Imports information about company.

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

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
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)

Responses
200

Success

400

Invalid data

post/api/v1/RefConfig/Company
Request samples
application/json
{
  • "code": "LH",
  • "name": "Deutsche Lufthansa Aktiengesellschaft",
  • "codeSource": "IATA"
}
Response samples
application/json
{
  • "responseStatus": {
    },
  • "data": null
}

Location information for cargo transport data

Imports information about location.

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

SecurityAuth_Token and Auth_ApplicationId and Auth_EDI_Address
Request
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)

Responses
200

Success

400

Invalid data

post/api/v1/RefConfig/Location
Request samples
application/json
{
  • "code": "DEFRA",
  • "name": "Frankfurt",
  • "codeSource": "IATA"
}
Response samples
application/json
{
  • "responseStatus": {
    },
  • "data": null
}