Track external shipment
=======================

The ``POST /track-external-shipment`` endpoint allows you to import an externally registered shipment into the MyParcel.com system.
This allows users to track their shipment status updates via the MyParcel.com API and benefit from features such as webhooks.

.. seealso::
    https://api-specification.myparcel.com/#tag/RPC/paths/~1track-external-shipment/post

Request
-------

**Required Scope:** ``shipments.manage``

Minimum shipment requirements
-----------------------------
In order to successfully track an externally registered shipment through our system, you need to provide the following information:

Attributes
__________
The following attributes should always be included in a shipment request:

===================  ===========
Attribute            Description
===================  ===========
recipient_address    :doc:`Address </api/resources/common-objects/addresses>` object containing information of the shipments recipient address.
sender_address       :doc:`Address </api/resources/common-objects/addresses>` object containing information about where the shipment is sent from.
return_address       :doc:`Address </api/resources/common-objects/addresses>` object containing information about where the shipment can be returned to.
physical_properties  `Physical properties </api/resources/shipments.html#physical-properties>`_ object containing at least the weight of the shipment.
tracking_code        A string containing the carrier's tracking code of the externally registered shipment.
===================  ===========

Relationships
_____________
The shop relationship is always required in any shipment creation request.
The contract relationship is required in order to retrieve tracking information from the carrier.

============  ===========
Relationship  Description
============  ===========
shop          A :doc:`shop </api/resources/shops>` relationship object containing the uuid of the shop that is the owner of this shipment.
contract      A :doc:`contract </api/resources/contracts>` relationship object containing the uuid of the contract with the credentials to track this shipment.
============  ===========

Sandbox environment
___________________
Since our sandbox environment does not provide real shipments, they will never receive a status update from the carrier.
To simulate a status update, you can provide a ``status_id`` in sandbox requests.
This way you can simulate realistic shipment behavior and trigger webhooks to test your implementation. See the :doc:`update-shipment-status </api/rpc-endpoints/update-shipment-statuses>` endpoint for more implementation details and examples.

.. code-block:: http

    POST /track-external-shipment HTTP/1.1
    Content-Type: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/track-external-shipment

    {
      "data": {
        "type": "shipments",
        "attributes": {
          "recipient_address": {
            "first_name": "Sherlock",
            "last_name": "Holmes",
            "street_1": "221B Baker Street",
            "postal_code": "NW1 6XE",
            "city": "London",
            "country_code": "GB"
          },
          "return_address": {
            "first_name": "Sherlock",
            "last_name": "Holmes",
            "street_1": "221B Baker Street",
            "postal_code": "NW1 6XE",
            "city": "London",
            "country_code": "GB"
          },
          "sender_address": {
            "first_name": "Sherlock",
            "last_name": "Holmes",
            "street_1": "221B Baker Street",
            "postal_code": "NW1 6XE",
            "city": "London",
            "country_code": "GB"
          },
          "physical_properties": {
            "weight": 5000
          },
          "tracking_code": "ABCD0123456789"
        },
        "relationships": {
          "contract": {
            "data": {
              "type": "contracts",
              "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
            }
          },
          "shop": {
            "data": {
              "type": "shops",
              "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
            }
          }
        }
      }
    }

Response
--------
The API will respond with status ``204 No Content`` indicating that no content is returned, but the shipment has been imported.