Sign in



nShift Help Center

How can we help you? Search for a topic or a question...

APIConnect - Shipments

Avatar
Malene Tidemann
Updated

Create, print and follow-up shipments.

 

Go to

 

Create a shipment

POST /shipments

Creates and prints a shipment.

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.

Compression of print job 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 avoid 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

returnFile

boolean

'true' if the PDF/ZPL file should be returned inline.

Optional

 

Body example

{
    "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"
            }
        ]
    }
}

 

Response example

[
    {
        "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": []
    }
]

For description of properties, please refer to the Property reference guide.

For schema and testing, please refer to https://api.unifaun.com/rs-docs/ and navigate to /shipments POST.

 

 

Fetch shipments

GET /shipments

Fetch printed shipments.

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

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

 

Response example

{
    "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
            ]
        }
    ]
}

For a description of properties, please refer to the Property reference guide.

For schema and testing, please refer to https://api.unifaun.com/rs-docs/ and navigate to /shipments GET.

 

 

Delete a shipment

DELETE /shipments/{shipmentId}

Deletes a printed shipment.

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

Shipment ID

string

Identifies the shipment

Required


For a description of properties, please refer to the Property reference guide.

For schema and testing, please refer to https://api.unifaun.com/rs-docs/ and navigate to /shipments/{shipmentId} DELETE.

 

 

Fetch a list of shipment documents

GET /shipments/{shipmentId}/prints

Fetch a list of all PDF or ZPL documents for a shipment.

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

Shipment ID

string

Identifies the shipment

Required

 

Query parameters

returnFile

boolean

'true' if the PDF/ZPL file should be returned inline.

Optional

 

Response example

[
    {
        "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"
    }
]

For a description of properties, please refer to the Property reference guide.

For schema and testing, please refer to https://api.unifaun.com/rs-docs/ and navigate to /shipments/{shipmentId}/prints GET.

 

 

Fetch a shipment document

GET /shipments/{shipmentId}/prints/{printId}

Fetches a PDF or ZPL document for a shipment.

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

Shipment ID

string

Identifies the shipment

Required

Print ID

string

Identifies the PDF or ZPL document

Required


For a description of properties, please refer to the Property reference guide.

For schema and testing, please refer to https://api.unifaun.com/rs-docs/ and navigate to /shipments/{shipmentId}/prints/{printId} GET.

Related articles