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. :doc:`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. .. code-block:: http GET /shipments/c41f6c38-d55b-41fb-9f74-096f92e41b13/files HTTP/1.1 Will give a response that looks like: .. code-block:: http 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 ________ - :download:`label_example.pdf (45 kB) ` - :download:`commercial_invoice_example.pdf (2 kB) ` - :download:`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: .. code-block:: http GET https://api.sandbox.myparcel.com/files/dd42199a-4553-4b6c-a40a-55000269998d HTTP/1.1 Accept: application/pdf Which gives the following response: .. code-block:: http 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.