EDI Engine API for Developers (1.0.0)

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.

Securitytoken

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 (MappingItemDTO)

Array that has all mapping data

Responses

200

Success

400

Invalid data

default

Error

post/EventMapping/ImportEventMapping

Request samples

Payload

application/json

{"mapping": [{"code": "1",
"name": "Receive item from customer",
"mailUnitType": "MI",
"ediEvent": "EMA",
"mailFlow": "O",
"valid": true,
"preferredReverseMapping": true
}
]
}

Response samples

200
400
default

application/json

{"responseStatus": {"statusCode": 0,
"statusMessage": "string"
},
"data": [ ]
}

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.

Securitytoken

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

default

Error

get/MailItem/ExportMailItems

Response samples

200
400
default

application/json

{"responseStatus": {"statusCode": 0,
"statusMessage": "string"
},
"data": {"mailItems": [{"itemIdentifier": "EA063523423CH",
"originCountry": "CH",
"itemOriginOperator": "CHA",
"itemDestinationOperator": "NZA",
"destinationCountry": "NZ",
"mailClass": "E",
"productType": null,
"customerAccountNumber": null,
"originPostcode": "3005",
"collectionPostcode": "3015",
"networkEntryLocationType": 1,
"itemLodgmentMode": 3,
"itemCategory": null,
"itemSubclass": "UA",
"itemHandlingClass": null,
"dutiableIndicator": "100",
"customerChargingArrangement": null,
"addressSection": {"placeOfOrigin": "Bern",
"postcode": "0600",
"placeOfDestination": "Auckland",
"deliveryLocationType": "DS1",
"houseIdentifier": "100a",
"line1": "Wellington street",
"line2": null,
"consumerRegistrationNumber": null,
"pickUpPointId": "Z Waiuku",
"deliveryServiceType": null
},
"senderInformation": {"telephone": "+41 123 45 56",
"email": "sender@email.ch"
},
"addresseeInformation": {"telephone": "+64 987 65 43",
"email": "addressee@email.co.nz",
"name": "John Doe",
"language": "ENG"
},
"measureInformation": {"grossWeight": 15.34,
"netWeight": 12.45,
"volume": 8.55
},
"postagePaidInformation": {"amount": 25.65,
"currency": "CHF"
},
"cashOnDelivery": {"amount": null,
"currency": null,
"bic": null,
"iban": null
},
"alternativeAddress": {"cityTown": null,
"houseIdentifier": null,
"line1": null,
"line2": null,
"postcode": null
},
"itemEvents": [{"operationalEventCode": "A",
"eventTimeStamp": "2019-08-24T14:15:22Z",
"eventOfficeOfExchange": null,
"eventLocalOffice": "Burgernziel",
"customsData": {"customsFacilityType": null,
"customsRetentionReason": null,
"customsOfficeID": null,
"customsReleaseStatus": null
},
"signatureName": null,
"deliveryLocation": null,
"itemArrivalStatus": null,
"itemArrivalDirection": null,
"processingPoint": {"processingPointID": "CHBRNA",
"processingPointType": "SOR",
"processingPointPostcode": null
},
"exportFlow": null,
"despatchOffice": null,
"despatchId": null,
"receptacleId": null,
"reasonForReturn": null,
"mailSource": null,
"itemDeliveryType": null,
"actionTaken": null,
"actionReason": null
}
]
}
]
}
}

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.

Securitytoken

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

default

Error

post/MailItem/ImportMailItems

Request samples

Payload

application/json

{"mailItems": [{"itemIdentifier": "EA063523423CH",
"originCountry": "CH",
"itemOriginOperator": "CHA",
"itemDestinationOperator": "NZA",
"destinationCountry": "NZ",
"mailClass": "E",
"productType": null,
"customerAccountNumber": null,
"originPostcode": "3005",
"collectionPostcode": "3015",
"networkEntryLocationType": 1,
"itemLodgmentMode": 3,
"itemCategory": null,
"itemSubclass": "UA",
"itemHandlingClass": null,
"dutiableIndicator": "100",
"customerChargingArrangement": null,
"addressSection": {"placeOfOrigin": "Bern",
"postcode": "0600",
"placeOfDestination": "Auckland",
"deliveryLocationType": "DS1",
"houseIdentifier": "100a",
"line1": "Wellington street",
"line2": null,
"consumerRegistrationNumber": null,
"pickUpPointId": "Z Waiuku",
"deliveryServiceType": null
},
"senderInformation": {"telephone": "+41 123 45 56",
"email": "sender@email.ch"
},
"addresseeInformation": {"telephone": "+64 987 65 43",
"email": "addressee@email.co.nz",
"name": "John Doe",
"language": "ENG"
},
"measureInformation": {"grossWeight": 15.34,
"netWeight": 12.45,
"volume": 8.55
},
"postagePaidInformation": {"amount": 25.65,
"currency": "CHF"
},
"cashOnDelivery": {"amount": null,
"currency": null,
"bic": null,
"iban": null
},
"alternativeAddress": {"cityTown": null,
"houseIdentifier": null,
"line1": null,
"line2": null,
"postcode": null
},
"itemEvents": [{"operationalEventCode": "A",
"eventTimeStamp": "2019-08-24T14:15:22Z",
"eventOfficeOfExchange": null,
"eventLocalOffice": "Burgernziel",
"customsData": {"customsFacilityType": null,
"customsRetentionReason": null,
"customsOfficeID": null,
"customsReleaseStatus": null
},
"signatureName": null,
"deliveryLocation": null,
"itemArrivalStatus": null,
"itemArrivalDirection": null,
"processingPoint": {"processingPointID": "CHBRNA",
"processingPointType": "SOR",
"processingPointPostcode": null
},
"exportFlow": null,
"despatchOffice": null,
"despatchId": null,
"receptacleId": null,
"reasonForReturn": null,
"mailSource": null,
"itemDeliveryType": null,
"actionTaken": null,
"actionReason": null
}
]
}
]
}

Response samples

200
400
default

application/json

{"responseStatus": {"statusCode": 0,
"statusMessage": "string"
},
"data": [ ]
}

Customs Declaration Data Services

Imports and retrieves customs declaration 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.

Securitytoken

Request

Request Body schema: application/json

Array of objects (CustomsDeclarationData)

Responses

200

Success

400

Invalid data

default

Error

post/CustomsDeclarations/ImportCustomsDeclarations

Request samples

Payload

application/json

{"customsDeclarations": [{"itemIdentifier": "CP163815968CH",
"destinationOperator": "NLA",
"originOperator": "CHA",
"alternateIdentifiers": null,
"attributeVersionNumber": 2,
"customers": {"sender": {"identification": {"name": "John Smith",
"reference": "1234567890",
"additionalData": ["Office 407"
]
},
"address": {"premises": {"line1": "Weltpoststrasse 4",
"line2": null,
"line3": null,
"line4": null
},
"countryCode": "CH",
"city_town": "Bern",
"postCode": "3015",
"region": "BE"
},
"contactDetails": {"emails": ["test_sender@upu.int"
],
"telephone": ["+41 123 45 67"
],
"fax": ["+41 123 45 68"
]
}
},
"addressee": {"identification": {"name": "Ann Dupont",
"reference": "99567890",
"additionalData": ["HR department"
]
},
"address": {"premises": {"line1": "Agnietenstraat 100a",
"line2": null,
"line3": null,
"line4": null
},
"countryCode": "NL",
"city_town": "Gouda",
"postCode": "2801",
"region": "GZ"
},
"contactDetails": {"emails": ["test_addressee@gmail.com"
],
"telephone": ["+31 765 54 32"
],
"fax": ["+31 765 54 31"
]
}
}
},
"dangerousGood": {"hazardClass": null,
"typeCode": null
},
"declaredGrossWeight": 5.2,
"measuredGrossWeight": 5.2,
"insuredValue": {"currencyCode": "CHF",
"amount": 50.25
},
"postagePaidValue": {"currencyCode": "CHF",
"amount": 16.95
},
"additionalFee": {"currencyCode": "EUR",
"amount": 5.99
},
"customsTaxInformation": {"natureOfTransaction": {"code": "11",
"description": null
},
"customsProcedure": null,
"totalDeclaredValue": {"currencyCode": "CHF",
"amount": 5.2
},
"observations": null,
"associatedDocuments": [{"type": "380",
"name": null,
"identifier": null
}
],
"contentPieces": [{"pieceNumber": 1,
"pieceNumberOfUnits": 3,
"description": "Swiss chocolades",
"declaredValue": {"currencyCode": "CHF",
"amount": 5.2
},
"netWeight": 5,
"originLocationCode": "CH",
"tariffHeading": "9999999999"
}
]
},
"eventData": {"code": "XP",
"dateTime": "2019-08-24T14:15:22Z",
"location": {"code": "CH BRN",
"function": "4"
},
"associatedEntity": {"identifier": "CHZRHBNLHAGIACN50502009000196"
},
"status": null,
"reason": null
}
}
]
}

Response samples

200
400
default

application/json

{"responseStatus": {"statusCode": 0,
"statusMessage": "string"
},
"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.

Securitytoken

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

default

Error

get/CustomsDeclarations/ExportCustomsDeclarations

Response samples

200
400
default

application/json

{"responseStatus": {"statusCode": 0,
"statusMessage": "string"
},
"data": {"customsDeclarations": [{"itemIdentifier": "CP163815968CH",
"destinationOperator": "NLA",
"originOperator": "CHA",
"alternateIdentifiers": null,
"attributeVersionNumber": 2,
"customers": {"sender": {"identification": {"name": "John Smith",
"reference": "1234567890",
"additionalData": [null
]
},
"address": {"premises": {"line1": null,
"line2": null,
"line3": null,
"line4": null
},
"countryCode": "CH",
"city_town": "Bern",
"postCode": "3015",
"region": "BE"
},
"contactDetails": {"emails": [null
],
"telephone": [null
],
"fax": [null
]
}
},
"addressee": {"identification": {"name": "Ann Dupont",
"reference": "99567890",
"additionalData": [null
]
},
"address": {"premises": {"line1": null,
"line2": null,
"line3": null,
"line4": null
},
"countryCode": "NL",
"city_town": "Gouda",
"postCode": "2801",
"region": "GZ"
},
"contactDetails": {"emails": [null
],
"telephone": [null
],
"fax": [null
]
}
}
},
"dangerousGood": {"hazardClass": null,
"typeCode": null
},
"declaredGrossWeight": 5.2,
"measuredGrossWeight": 5.2,
"insuredValue": {"currencyCode": "CHF",
"amount": 50.25
},
"postagePaidValue": {"currencyCode": "CHF",
"amount": 16.95
},
"additionalFee": {"currencyCode": "EUR",
"amount": 5.99
},
"customsTaxInformation": {"natureOfTransaction": {"code": "11",
"description": null
},
"customsProcedure": null,
"totalDeclaredValue": {"currencyCode": "CHF",
"amount": 5.2
},
"observations": null,
"associatedDocuments": [{"type": "380",
"name": null,
"identifier": null
}
],
"contentPieces": [{"pieceNumber": 1,
"pieceNumberOfUnits": 3,
"description": "Swiss chocolades",
"declaredValue": {"currencyCode": null,
"amount": null
},
"netWeight": 5,
"originLocationCode": "CH",
"tariffHeading": "9999999999"
}
]
},
"eventData": {"code": "XP",
"dateTime": "2019-08-24T14:15:22Z",
"location": {"code": "CH BRN",
"function": "4"
},
"associatedEntity": {"identifier": "CHZRHBNLHAGIACN50502009000196"
},
"status": null,
"reason": null
}
}
]
}
}