/shipments
Shipments is how you create shipments and print shipment documents as PDF or ZPL files. The resource also has methods and endpoints for history follow-up and shipment deletion, that is, preventing sending EDI message to carrier.
Note
The REST API endpoints are only accessible via HTTPS and are located at api.unifaun.com.
https://api.unifaun.com/rs-extapi/v1 |
Before getting started you need to know your developer ID and create an API key.
Create a shipment
POST |
Creates and prints a shipment.
Note
The shipment data in the request body must fulfill the specific requirements of the shipment's service.
PDF or ZPL documents will be created according to the provided print configuration.
Tip
Compression of printjob data based on ZPL supported features will reduce the size of the file that is transferred between Delivery and the physical printer. It results in faster printouts and helps avoiding memory overflow problems in printers. Use the key-value pair setting in the target1Options field.
By default the documents are returned as a URL. As an option the documents can be inline in the print.data object in the result. The print.data object is encoded in base64.
The generated documents will only be available for one (1) hour.
Query parameters
Parameter | Type | Description | Category |
|---|---|---|---|
returnFile | boolean | 'true' if the PDF/ZPL file should be returned inline. | Optional |
{
"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": "RECV1",
"name": "Receiver One",
"address1": "Tegnérgatan 39",
"zipcode": "11359",
"city": "STOCKHOLM",
"country": "SE",
"phone": "031-7253501",
"contact": "Receiver contact person",
"mobile": "+46733000011",
"email": "test@test.com"
},
"service": {
"addons": [],
"id": "FREEG",
"normalShipment": true
},
"orderNo": "ORD-001",
"senderReference": "REF-001",
"options": [
{
"from": "contact.person@unifaun.com",
"id": "enot",
"to": "test@test.com",
"message": "Your stuff is on the way!"
}
],
"parcels": [
{
"volume": 0.1,
"copies": 1,
"weight": 1,
"valuePerParcel": true,
"contents": "Stuff",
"packageCode": "SH"
}
]
}
}[
{
"href": "https://api.unifaun.com/rs-extapi/v1/shipments/10252317",
"id": "10252317",
"status": "PRINTED",
"shipmentNo": "4381670977",
"orderNo": "ORD-001",
"route": null,
"routingCode": null,
"reference": "REF-001",
"serviceId": "FREEG",
"parcelCount": 1,
"sndName": "nShift AB",
"sndZipcode": "41121",
"sndCity": "GÖTEBORG",
"sndCountry": "SE",
"sndQuickId": "SE",
"rcvName": "Receiver One",
"rcvZipcode": "11359",
"rcvCity": "STOCKHOLM",
"rcvCountry": "SE",
"rcvQuickId": "RECV1",
"created": "2021-02-03T15:07:32.427+0000",
"changed": "2021-02-03T15:07:32.427+0000",
"shipDate": "2021-02-03T15:07:32.000+0000",
"returnShipment": false,
"normalShipment": true,
"consolidated": false,
"deliveryCode": null,
"profileGroup": "Grundprofilgrupp",
"parcels": [
{
"parcelNo": "373325382775662012",
"returnParcelNo": null,
"reference": null,
"partOrderNo": null
}
],
"pdfs": [],
"previousPdfs": null,
"prints": [
{
"href": "https://api.unifaun.com/rs-extapi/v1/shipments/10252317/prints/192364271",
"id": "192364271",
"description": "Label",
"data": null,
"media": "thermo-190",
"type": "zpl"
},
{
"href": "https://api.unifaun.com/rs-extapi/v1/shipments/10252317/prints/192364272",
"id": "192364272",
"description": "Doc",
"data": null,
"media": "laser-a4",
"type": "pdf"
}
],
"previousPrints": null,
"addons": []
}
]Fetch shipments
GET |
Fetch printed shipments.
Note
Max. 100 shipments are returned per call. If more shipments are available the done value in the result will be "false" and you should make another call to fetch the remaining shipments.
If calls are made too fast the minDelay value in the result will return how many milliseconds you have to wait before calling again. To avoid an uneven call, max.one (1) call per five (5) minutes is recommended.
Query parameters
Parameter | Type | Description | Category |
|---|---|---|---|
fetchId | string | The ID of the next batch of shipments to fetch. Save the fetchId returned by a previous call and use it as parameter value for the next call. If a fetchId is not available, use the value -1 to make a call that will return a fetchId to use in a subsequent call. | Optional |
{
"fetchId": "1",
"done": true,
"minDelay": 100,
"shipments": [
{
"href": "https://api.unifaun.com/rs-extapi/v1/shipments/10252317",
"id": "10252317",
"status": "PRINTED",
"shipmentNo": "4381670977",
"orderNo": "ORD-001",
"route": null,
"routingCode": null,
"reference": "REF-001",
"serviceId": "FREEG",
"parcelCount": 1,
"sndName": "nShift AB",
"sndZipcode": "41121",
"sndCity": "GÖTEBORG",
"sndCountry": "SE",
"sndQuickId": "SE",
"rcvName": "Receiver One",
"rcvZipcode": "11359",
"rcvCity": "STOCKHOLM",
"rcvCountry": "SE",
"rcvQuickId": "RECV1",
"created": "2021-02-03T15:07:32.427+0000",
"changed": "2021-02-03T15:07:32.427+0000",
"shipDate": "2021-02-03T15:07:32.000+0000",
"returnShipment": false,
"normalShipment": true,
"consolidated": false,
"deliveryCode": null,
"profileGroup": "Grundprofilgrupp",
"parcels": [
{
"parcelNo": "373325382775662012",
"returnParcelNo": null,
"reference": "",
"partOrderNo": ""
}
],
"pdfs": null,
"previousPdfs": null,
"prints": null,
"previousPrints": null,
"addons": [
null
]
}
]
}Delete a shipment
DELETE |
Deletes a printed shipment.
Note
No response body is returned when a shipment is successfully deleted.
The shipment will get the status "cancelled". If supported by the carrier they will receive a message about the cancellation.
URI parameters
Parameter | Type | Description | Category |
|---|---|---|---|
Shipment ID | string | Identifies the shipment | Required |
Fetch a list of shipment documents
GET |
Fetch a list of all PDF or ZPL documents for a shipment.
Note
By default the documents are returned as a URL. As an option the documents can be inline in the prints.data object in the result. The prints.data object is encoded in base64.
Charset options are set in the target1Options array in the printConfig object.
Generated documents are only available for one (1) hour.
URI parameters
Parameter | Type | Description | Category |
|---|---|---|---|
Shipment ID | string | Identifies the shipment | Required |
Query parameters
Parameter | Type | Description | Category |
|---|---|---|---|
returnFile | boolean | 'true' if the PDF/ZPL file should be returned inline. | Optional |
[
{
"href": "https://api.unifaun.com/rs-extapi/v1/shipments/10252317/prints/192364271",
"id": "192364271",
"description": "Label",
"data": null,
"media": "thermo-190",
"type": "zpl"
},
{
"href": "https://api.unifaun.com/rs-extapi/v1/shipments/10252317/prints/192364272",
"id": "192364272",
"description": "Doc",
"data": null,
"media": "laser-a4",
"type": "pdf"
}
]Fetch a shipment document
GET |
Fetches a PDF or ZPL document for a shipment.
Note
The document is returned as a raw binary stream from this endpoint. Make sure the request has the Accept header set to application/pdf for PDF documents or application/octet-stream for ZPL documents.
Charset options are set in the target1Options array in the printConfig object.
URI parameters
Parameter | Type | Description | Category |
|---|---|---|---|
Shipment ID | string | Identifies the shipment | Required |
Print ID | string | Identifies the PDF or ZPL document | Required |
Tip
For schema and testing, please refer to https://api.unifaun.com/rs-docs/.
For description of properties, please refer to the Property reference guide.
For information about some crucial objects, please refer to REST API Objects.
Key | Value |
|---|---|
mode | "DT" = Direct thermal printers "TT" = Thermal transfer printers |
rotate | "NONE" "180" = Rotate the printing 180 degrees |
dpi | "203" "300" |
charset | "CP850" (ZPL default) "UTF8" NoteEven when UTF8 is used, the standard font in the printer normally only supports cp850 characters. |
printmode | "T" = Tear-off (default) "P" = Peel-off (not available on S-300) "R" = Rewind (depends on printer model) "A" = Applicator (depends on printer model) "C" = Cutter (depends on printer model) "D" = Delayed cutter "F" = RFID "K" = Kiosk |
speed | (ZPL only) Min. value: 2 Max. value: 8 |
darkness | (ZPL only) Min. value: 0 Max. value: 30 |
compression | (ZPL only) Z64 = Binary compression ascii = ASCII compression CautionSome printers, even though supporting ZPL, may have problems with or not support the compression methods. |