REST API has two objects on the root level:
Please refer to the Property reference guide for guidance regarding properties and values.
The printConfig object
The printConfig object defines the format and type of shipping documents. It supports up to four targets. This can be useful if several services are used supporting multiple label formats, for example:
- Letter services supporting letter label format
- Parcel services requiring full-size label format
- Other documents, such as waybills, customs declarations, etc. requiring A4 format
The most common scenario is to have one output target for labels and another for other documents, such as waybills, customs declaration documents, etc. The smallest label format should come first, followed by the larger format, and then A4 at the end. The system iterates through the object searching for a suitable target format.
Example: Two targets
"printConfig": {
"target1Media": "thermo-190",
"target1Type": "zpl",
"target1Options": [
{
"key": "mode",
"value": "DT"
}
],
"target2Media": "laser-a4",
"target2Type": "pdf"
},
The shipment object
A shipment object contains all the information about the shipment and usually consists of at least two address party objects (sender and receiver), a service object and a parcels object. Depending on the use case, other objects are included in the shipment object, such as developerId, favorite, profileGroup and mergeId.
Example: Shipment object without nested objects
"shipment": {
"termsCode": "0017",
"orderNo": "ORD-001",
"senderReference": "REF-001",
},
Address party objects
There are a number of address parties available and their usage depends on the service's requirements.
sender
Sender information (mandatory)
senderPartners
Carrier-related information (for example, customer number) for the sender object.
receiver
Receiver information (mandatory)
dispatch
Alternative pickup address
receiverPartners
Carrier-related information (for example, customer number) for the receiver object.
delivery
Alternative pickup address
agent
Pickup point for B2C services
returnPart
Alternative return address
freightPayer
Alternative freightPayer party (not to be mistaken for the Receiver pays or the Other payer additional services)
freightPayerPartners
Carrier information
taxPayer
Tax payer information
taxPayerPartners
Carrier information
customsPayer
Customs payer information
customsPayerPartners
Carrier information
Example: Sender and receiver objects
{
"sender": {
"quickId": "SE",
"name": "nShift AB",
"address1": "Skeppsbron 5-6",
"zipcode": "41121",
"city": "GÖTEBORG",
"country": "SE",
"phone": "+46317253500",
"contact": "Contact person",
"mobile": "+46700000000",
"email": "contact.person@unifaun.com"
},
"receiver": {
"quickId": "41",
"name": "Norway",
"address1": "Lagerveien 100",
"address2": "Adress2",
"zipcode": "9520",
"city": "GAMLE FREDRIKSTAD",
"country": "NO",
"phone": "031-7253501",
"contact": "Receiver contact person",
"mobile": "99896887",
"email": "test@test.com"
}
}
The service object
The service object contains information about the carrier service. For additional services, the addons object is included in the service object.
Example: Service object without additional services
"service": {
"id": "FREEG",
"normalShipment": true
},
The parcels object
The parcels object contains information about the parcels included in the shipment, such as weight, contents and dangerous goods information. It can also contain the articles object which is used for the Item directory add-on.
Example: Parcel object with one parcel
"parcels": [
{
"copies":1,
"weight":1,
"volume":0.1,
"valuePerParcel":true,
"contents":"Stuff",
"packageCode":"SH"
}
]
The customs declaration object
The customsdeclaration object contains customs information, such as invoice type and currency, for shipments outside the EU. By default, all necessary shipment documents are printed. You do not have to state them unless you want to override the default settings.
Shipping documents
label
Parcel labels
dngdecl
Dangerous goods declaration
sis
SIS/SFS/CMR waybill. Type depends on sender and receiver country.
*
None
The printSet array is used to specify customs declaration documents.
Customs declaration documents
proforma
Commercial/proforma invoice
proformaplabedi
Proforma invoice incl. EDI (PostNord only)
plt
Customs information via EDI only
edoc
ED document
cn22
CN22 declaration
cn23
CN23 declaration
proformaups
Commercial invoice - UPS
upschild
UPS World Ease Child shipment
proformatnt
Proforma for TNT
notetnt
TNT Note
pnlwaybilledi
Separate custom documents for PNL are sent via EDI, not from this system
fedexp
Commercial invoice for FedEx
tradeinvoicepdk
Commercial invoice for PostNord DK
datatransferpdk ()
Customs information via EDI only for PostNord DK
cn22depostpt
CN22 for Deutsche Post Packet Tracked
Example: Customs declaration object containing a nested lines object describing the contents and value.
"customsDeclaration": {
"destinationCountryCode": "NO",
"exportCountryCode": "SE",
"importExportType": "OTHER",
"printSet": [ "PROFORMA", "EDOC" ],
"parcelCount": 1,
"sourceCountryCode": "SE",
"edocNormal": true,
"invoiceType": "STANDARD",
"shippingCodeBorder": "ROAD",
"invoiceNo": "12345678",
"lines": [
{
"netWeight": 1,
"grossWeight": 1,
"sourceCountryCode": "SE",
"valuesPerItem": false,
"copies": 1,
"contents": "Books",
"statNo": "12345678",
"value": 1
}
],
"currencyCode": "SEK",
"shippingCodeDomestic": "ROAD"
},
The options object
The options object contains information about nShift add-ons, such as Email pre-notification, Link to print and Consolidated shipment.
Example: Options object with email pre-notification
"options": [
{
"from": "contact.person@unifaun.com",
"id": "enot",
"to": "test@test.com”,
"message": "Your stuff is on the way!"
}
],
A complete shipment object including the examples above
Example: Shipment object including the examples above
{
"printConfig": {
"target1Media": "thermo-190",
"target1Type": "zpl",
"target1Options": [
{
"key": "mode",
"value": "DT"
}
],
"target2Media": "laser-a4",
"target2Type": "pdf"
},
"shipment": {
"sender": {
"quickId": "SE",
"name": "nShift AB",
"address1": "Skeppsbron 5-6",
"zipcode": "41121",
"city": "GÖTEBORG",
"country": "SE",
"phone": "+46317253500",
"contact": "Contact person",
"mobile": "+46700000000",
"email": "contact.person@unifaun.com"
},
"receiver": {
"quickId": "41",
"name": "Norway",
"address1": "Lagerveien 100",
"address2": "Adress2",
"zipcode": "9520",
"city": "GAMLE FREDRIKSTAD",
"country": "NO",
"phone": "031-7253501",
"contact": "Receiver contact person",
"mobile": "99896887",
"email": "test@test.com"
},
"service": {
"addons": [],
"id": "FREEG",
"normalShipment": true
},
"termsCode": "0017",
"orderNo": "ORD-001",
"senderReference": "REF-001",
"options": [
{
"from": "alen.ramic@unifaun.com",
"id": "enot",
"to": "test@test.com",
"message": "Your stuff is on the way!"
}
],
"customsDeclaration": {
"destinationCountryCode": "NO",
"exportCountryCode": "SE",
"importExportType": "OTHER",
"printSet": [
"PROFORMA",
"EDOC"
],
"parcelCount": 1,
"sourceCountryCode": "SE",
"edocNormal": true,
"invoiceType": "STANDARD",
"shippingCodeBorder": "ROAD",
"invoiceNo": "12345678",
"lines": [
{
"netWeight": 1,
"grossWeight": 1,
"sourceCountryCode": "SE",
"valuesPerItem": false,
"copies": 1,
"contents": "Books",
"statNo": "12345678",
"value": 1
}
],
"currencyCode": "SEK",
"shippingCodeDomestic": "ROAD"
},
"parcels": [
{
"volume": 0.1,
"copies": 1,
"weight": 1,
"valuePerParcel": true,
"contents": "Stuff",
"packageCode": "SH"
}
]
}
}