Retrieve shipment files

Before you can hand your shipment over to the carrier, the parcel must be provided with a label. In some cases customs documents should also be provided for passing customs. This section explains how to retrieve the available files and write them to your local file system.

Prerequisites

Warning

Files are only available when a shipment is successfully registered with the carrier. Make sure to verify this before requesting any shipment files.

Shipment registration

Before you can retrieve files for your shipment, it first needs to be registered with the carrier that will ship the parcel. The MyParcel.com API can then retrieve and create the necessary files for you.

Registered or registration failed

Registering a shipment with a carrier happens in a background process in the API and can take a few seconds to complete. After the API process is done registering a shipment, the shipment will be updated with a new status:

• shipment-registered if the carrier accepted the shipment and returned a label. Files and optionally a tracking code are available (provided that the chosen service provides tracking).

• shipment-registration-failed if the carrier did not accept the shipment. No files will be available and the reason for failing registration will be mentioned in the errors attached to the shipment-status.

There are two ways to be informed about this new status:

Method	Description	Documentation
Webhooks (preferred)	Our system will notify your system as soon as the status is changed.	Create a webhook
Polling	Your system should retrieve the shipment statuses from our system and retry this (after waiting 1 second) if the status is not yet updated.	Retrieve current status

Retrieving available files

Before you can download a file, you should check what files are available for the given shipment. To request the files, send a GET request to /shipments/{shipment_id}/files.

Note

To request shipment files, you need the shipments.manage scope.

GET /shipments/c41f6c38-d55b-41fb-9f74-096f92e41b13/files HTTP/1.1

Will give a response that looks like:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "dd42199a-4553-4b6c-a40a-55000269998d",
      "type": "files",
      "attributes": {
        "document_type": "label",
        "formats": [
          {
            "extension": "pdf",
            "mime_type": "application/pdf"
          }
        ]
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/files/dd42199a-4553-4b6c-a40a-55000269998d"
      }
    }
  ]
}

The data of the response contains an array of available files, with each file specifying an array of formats in which the file is available. In this case there is one file with a document_type of label and it is only available in the format pdf.

Available Files

These are the files you can regularly expect on a shipment:

File	Description
label	The shipping label.
customs-declaration-form	A customs declaration form generated based on your shipment information.
commercial-invoice	A commercial invoice required for customs, based on your shipment information.

Examples

• label_example.pdf (45 kB)

• commercial_invoice_example.pdf (2 kB)

• customs_declaration_form_example.pdf (3 kB)

Downloading the file

To download a file, simply send a GET request to the corresponding files endpoint. You can use the self link of the previous request for easy access.

The request should contain an Accept header for the format in which you want to receive the file. To download the above label in pdf, you would do the following request:

GET https://api.sandbox.myparcel.com/files/dd42199a-4553-4b6c-a40a-55000269998d HTTP/1.1
Accept: application/pdf

Which gives the following response:

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="download.pdf"
Content-Type: application/pdf

%PDF-1.4 [...] %%EOF

You can then store the file wherever you want. If you would like to serve the file directly to the user, check out this StackOverflow thread for inspiration.