Files
=====

A file resource can represent all kinds of files like shipment labels, available in different file formats.

.. seealso::
    https://api-specification.myparcel.com/#tag/Files

File
----

=============  ===========
Attribute      Description
=============  ===========
document_type  Category the file belongs to, for example label or invoice.
formats        List of :ref:`file-format` objects holding the extension and mime type in which the file is available.
=============  ===========

.. _file-format:

Format
______
If you request a file using the default ``Accept`` header ``application/vnd.api+json``, you will get a list of the supported formats of that file. This list can contain the following mime types:

- ``application/pdf``
- ``application/zpl``
- ``image/png``
- ``text/csv``

.. warning::
    The shipment label file will become available in the format you have specified, by default this will be the first label format defined on the :doc:`carrier </api/resources/carriers>` resource, most likely ``application/pdf``.
    If you use a Zebra printer and want the label file in ``application/zpl``, you need to specify this in the `request meta </api/create-a-shipment.html#label-format>`_ when creating the shipment.

Retrieve a file in a specific format
------------------------------------
Use one of the available formats in the ``Accept`` header to retrieve the actual file as binary data. For example:

.. code-block:: http

    GET /files/a9e3852c-b8b2-4066-a32a-651ea661ba30 HTTP/1.1
    Accept: application/pdf

The response will be of the same mime type and contain the raw file data.

.. code-block:: http

    HTTP/1.1 200 OK
    Content-Type: application/pdf

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

.. seealso::
    `<https://api-specification.myparcel.com/#tag/Files/paths/~1files~1{file_id}/get>`_