Retrieving resources
====================

Most of the resources available in the API can be accessed using the SDK. All resources will be mapped to classes implementing their specific interface. These interfaces are all defined in the
``\MyParcelCom\ApiSdk\Resources\Interfaces`` namespace.

Shops
_____
All the shops or the default shop for the currently authenticated user can be retrieved. The shops will be mapped to objects implementing ``\MyParcelCom\ApiSdk\Resources\Interfaces\ShopInterface``.

.. code-block:: php

    // Get all shops.
    $shops = $api->getShops();

    // Get the default shop.
    $shop = $api->getDefaultShop();

Carriers
________
Services for different carriers are available through the API. The SDK can retrieve all the carriers the currently authenticated user can access. All carriers will be mapped to objects implementing ``MyParcelCom\ApiSdk\Resources\Interfaces\CarrierInterface``.

.. code-block:: php

    // Get the carriers.
    $carriers = $api->getCarriers();

Pick-up/drop-off locations
--------------------------
Most carriers allow the recipient to define a pick-up location and a sender to define a drop-off location.

Most carriers only need a postal code in a specific country, but some carriers also require a street name and number. It is therefore recommended to always supply all this information to the SDK.

Including the (optional) ``specificCarrier`` parameter will return an array of the pick-up/drop-off locations for only that carrier.

When no specific carrier is defined, the pick-up/drop-off locations of all available carriers will be returned as an array of the carrier ids as keys and an array of their locations as the values. When requesting the locations from one of the carriers fails, the array of locations for that carrier is replaced with ``null``.

Note that when you do specify a specific carrier a ``GuzzleHttp\Exception\RequestException`` will be thrown when the request fails.

.. code-block:: php

    // Get all pick-up/drop-off locations near the area with postal code 'NW1 6XE'
    // in the United Kingdom for all carriers.
    $locations = $api->getPickUpDropOffLocations('GB', 'NW1 6XE', 'Baker Street', 221);

    // Same as above, but for specified carrier.
    $locations = $api->getPickUpDropOffLocations('GB', 'NW1 6XE', 'Baker Street', 221, $carrier);

To only retrieve pick-up/drop-off locations for carriers for which the authenticated user has an active contract, the optional ``onlyActiveContracts`` parameter should be set to ``true`` in the method call.

.. code-block:: php

    // The last parameter in the method call indicates whether to only retrieve pick-up/drop-off locations for carriers with an active contract or not.
    $locations = $api->getPickUpDropOffLocations('GB', 'NW1 6XE', 'Baker Street', 221, null, true);

Services
________
The services (eg 'DPD next day') available in the API can be retrieved using the SDK. There are three ways to retrieve them. Either get all available services, the services available for a specific shipment, or all available services from a specific carrier. Services will be mapped to the ``\MyParcelCom\ApiSdk\Resources\Interfaces\ServiceInterface``.

.. code-block:: php

    // Get all services.
    $services = $api->getServices();

    // Get all services that can handle the shipment.
    $services = $api->getServices($shipment);

    // Get all services for specific carrier.
    $services = $api->getServicesForCarrier($carrier);

Service rates
-------------
The price of a service is detailed in a related service rate resource. A service resource can have multiple related service rate resources, each with different attributes like weight range or relationships like :doc:`contract </api/resources/contracts>` or :doc:`service options </api/resources/service-options>`. Learn more about service rates on the :doc:`service rates resource page </api/resources/service-rates>`.

There are currently three ways to retrieve service rates. Either get all available service rates, the service rates available for a shipment, or all available service rates belonging to a specific service. Service rates will be mapped to the ``\MyParcelCom\ApiSdk\Resources\Interfaces\ServiceRateInterface``.

.. code-block:: php

    // Get all available service rates.
    $api->getServiceRates();

    // Get all available service rates for a shipment.
    $api->getServiceRatesForShipment($shipment);

    // Get all available service rates for a service.
    $service->getServiceRates();

Note that service rates cannot be linked to a shipment directly. A service rate has a relation to a service resource, a contract resource and service option resources, and should only be used to determine which service, contract and service options to use when creating a shipment.

Service options
---------------
Service options add extra's to a service, often against a higher price. Retrieving service options is done by requesting them from a service rate. Service options will be mapped to the ``\MyParcelCom\ApiSdk\Resources\Interfaces\ServiceOptionInterface``.

.. code-block:: php

    // Get the service options for a service rate.
    $serviceOptions = $serviceRate->getServiceOptions();

Shipments
_________
Shipments are the resources that you will interact with the most. Creating and retrieving shipments can be done through the SDK. As well as retrieving the shipment status and any files associated with the shipment.

Creating shipments
------------------
To create a shipment, an object implementing ``\MyParcelCom\ApiSdk\Resources\Interfaces\ShipmentInterface`` should be created. A class implementing this interface has been provided in ``\MyParcelCom\ApiSdk\Resources\Shipment``. At least a recipient address and a weight should be provided in the shipment. All other fields are optional or will be filled with defaults by the SDK.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Address;
    use MyParcelCom\ApiSdk\Resources\Shipment;
    use MyParcelCom\ApiSdk\Resources\Interfaces\PhysicalPropertiesInterface;

    // Define the recipient address.
    $recipient = new Address();
    $recipient
        ->setStreet1('Baker Street')
        ->setStreetNumber(221)
        ->setCity('London')
        ->setPostalCode('NW1 6XE')
        ->setFirstName('Sherlock')
        ->setLastName('Holmes')
        ->setCountryCode('GB')
        ->setEmail('s.holmes@holmesinvestigations.com');

    // Create the shipment and set required parameters.
    $shipment = new Shipment();
    $shipment
        ->setRecipientAddress($recipient)
        ->setWeight(500, PhysicalPropertiesInterface::WEIGHT_GRAM);

    // Have the SDK determine the cheapest service and post the shipment to the MyParcel.com API.
    $createdShipment = $api->createShipment($shipment);

If the shipment being created is invalid or there is no valid service available, a ``MyParcelCom\ApiSdk\Exceptions\InvalidResourceException`` will be thrown.

If you wish to specify which service to use with your shipment, you should assign it to the shipment before creating it.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Shipment;
    use MyParcelCom\ApiSdk\Resources\Interfaces\PhysicalPropertiesInterface;

    $shipment = new Shipment();
    $shipment
        ->setRecipientAddress($recipient)
        ->setWeight(500, PhysicalPropertiesInterface::WEIGHT_GRAM)
        ->setService($service);

    // Post the shipment to the API.
    $createdShipment = $api->createShipment($shipment);

If you wish to add service options to a shipment before creating it in the API, you can do this in two ways. Either by setting all service options at once, or adding them one by one.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Shipment;

    $shipment = new Shipment();

    // Setting a service option one by one.
    $shipment->addServiceOption($serviceOption);

    // Setting all service options at once.
    $shipment->setServiceOptions($serviceOptions);

Retrieving shipments
--------------------
After the shipment has been created, it will be updated with an id and a price. Using the id, the shipment can be retrieved from the API to check the status and retrieve any associated files.

.. code-block:: php

    // Post your newly created shipment to the API.
    $createdShipment = $api->createShipment($newShipment);

    // Get the updated shipment from the API based on its id.
    $updatedShipment = $api->getShipment($createdShipment->getId());

    // Get the current status of the shipment.
    $status = $updatedShipment->getShipmentStatus();

    // Get the files associated with the shipment, eg label.
    $files = $updatedShipment->getFiles();

It is also possible to retrieve all shipments. There are currently two ways to retrieve them. Either retrieve all available shipments or retrieve the shipments that were created using a specific shop.

.. code-block:: php

    // Retrieve all available shipments.
    $shipments = $api->getShipments();

    // Retrieve all shipments created using a certain shop.
    $shipments = $api->getShipments($shop);

Shipment files
--------------
When a shipment has been successfully registered with a carrier, a shipping label will be available for the shipment. In some cases the shipping label is accompanied by one of more additional files. (eg when creating an international shipment, a customs form may be made available). These files can be requested from a shipment.

.. code-block:: php

    // Get the shipment based on its id.
    $shipment = $api->getShipment('31a5657d-d845-4266-83ac-50b72ccb195f');

    // Get all the files associated with the shipment.
    $files = $shipment->getFiles();

    // Get the shipment label(s).
    $labels = $shipment->getFiles(FileInterface::DOCUMENT_TYPE_LABEL);

A file can be available in multiple formats (although the most common one is PDF). The formats are available in the file resource.

.. code-block:: php

    // Get an array with all the formats this file is available in.
    $file->getFormats();

The actual file can be retrieved in different ways, depending on your use case.

.. code-block:: php

    // Get a stream for the file in pdf format. This is useful for when you want to
    // send the file to a user in a stream.
    // Note that this won't work if the file is not available in pdf format,
    // check `getFormats()` before doing this request.
    $stream = $file->getStream('application/pdf');

    // Get the file data as a base64 encoded string. This is useful for when you want
    // to embed the file in an email.
    $data = $file->getBase64Data('application/pdf');

    // Get the path to the temporary file stored on the system.
    $path = $file->getTemporaryFilePath('application/pdf');

Manifests
_________
Creating and retrieving manifests can be done through the SDK. As well as retrieving the files associated with the manifest.

Creating manifests
------------------
To create a manifest, an object implementing ``\MyParcelCom\ApiSdk\Resources\Interfaces\ManifestInterface`` should be created.
A class implementing this interface has been provided in ``\MyParcelCom\ApiSdk\Resources\Manifest``. A
manifest should at least have: a name, an address (``street1``, ``city``, ``countryCode``), an owner and a shipment.
A manifest owner can be a shop, organization, or broker.
All other fields are optional.
If the manifest being created is invalid, a ``MyParcelCom\ApiSdk\Exceptions\InvalidResourceException`` will be thrown.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Address;
    use MyParcelCom\ApiSdk\Resources\Manifest;
    use MyParcelCom\ApiSdk\Resources\Organization;

    // Define the address.
    $address = new Address();
    $address
        ->setStreet1('Baker Street')
        ->setCity('London')
        ->setCountryCode('GB')
        ->setStreetNumber(221)
        ->setPostalCode('NW1 6XE')
        ->setFirstName('Sherlock')
        ->setLastName('Holmes')
        ->setEmail('s.holmes@holmesinvestigations.com');

    $owner = new Organization();
    $owner->setId('your-organization-uuid');

    $shipments = $api->getShipments();
    // filter shipments that you wish to attach to the manifest
    $shipmentsForManifest = ...;

    // Create the manifest and set required parameters.
    $manifest = new Manifest();
    $manifest
        ->setName('The Manifest name')
        ->setAddress($address)
        ->setOwner($owner)
        ->setShipments($shipmentsForManifest);

    // Post the manifest to the MyParcel.com API.
    $createdManifest = $api->createManifest($manifest);

If the owner is a ``\MyParcelCom\ApiSdk\Resources\Shop`` and no address is provided, we attempt to set the shop's sender address (or return address as fallback) on the manifest.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Manifest;

    // retrieve your shops and select the correct one
    $shops = $api->getShops();

    // or use your default shop (the shop you created first)
    $defaultShop = $api->getDefaultShop();

    $owner = $defaultShop;

    // Create the manifest and set required parameters.
    $manifest = new Manifest();
    $manifest
        ->setName('The Manifest name')
        ->setOwner($owner)
        ->setShipments($shipmentsForManifest);

    // Post the manifest to the MyParcel.com API.
    $createdManifest = $api->createManifest($manifest);

If you wish to specify which contract to use with your manifest, you should assign it to the manifest before creating it. If the contracted carrier supports generating manifests, we let them generate the manifest file instead of doing it ourselves. Only shipments that are created with this contract can be attached to the manifest.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Manifest;

    $shipments = $api->getShipments();
    // filter shipments that you wish to attach to the manifest
    $shipmentsForManifest = ...;

    $manifest = new Manifest();
    $manifest
        ->setShipments($shipmentsForManifest)
        ->setContract($contract);

By setting ``updates_shipment_statuses`` to ``true``, each shipment on the manifest that has status "shipment registered" will have its status updated to "received by carrier".

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Manifest;

    $shipments = $api->getShipments();
    // filter shipments that you wish to attach to the manifest
    $shipmentsForManifest = ...;

    $manifest = new Manifest();
    $manifest
        ->setShipments($shipmentsForManifest)
        ->setUpdatesShipmentStatuses(true);

Retrieving manifests
--------------------
After the manifest has been created, it will be updated with an id and manifest files. Using the id, the manifest can be retrieved from the API to retrieve any associated files.

.. code-block:: php

    $manifestId = 'your-manifest-uuid';
    // Get the updated manifest from the API based on its id.
    $manifest = $api->getManifest($manifestId);

It is also possible to retrieve all manifests.

.. code-block:: php

    // Retrieve all available manifests.
    $manifests = $api->getManifests();

Manifest files
--------------
After the manifest has been created, it will be updated with references to manifest files. Using the file id, the file can be retrieved from the API.

.. code-block:: php

    $manifestId = 'your-manifest-uuid';
    $manifest = $api->getManifest($manifestId);

    foreach ($manifest->getFiles() as $fileReference) {
        $file = $api->getManifestFile($manifest->getId(), $file->getId());

        // access the file's contents as a stream
        $file->getStream();
        // or as a base64 encoded string
        $file->getBase64Data();
    }

Collections
___________
The SDK offers the possibility to manage collections for shipments as well.

Creating collections
--------------------
To create a collection, an object implementing ``\MyParcelCom\ApiSdk\Resources\Interfaces\CollectionInterface`` should be created.
A class implementing this interface has been provided in ``\MyParcelCom\ApiSdk\Resources\Collection``.
If the collection being created is invalid, a ``MyParcelCom\ApiSdk\Exceptions\InvalidResourceException`` will be thrown.

.. note::
    For general information about creating collections, refer to the :doc:`collections resource</api/resources/collections>` and :doc:`create a collection</api/create-a-collection>` pages.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Address;
    use MyParcelCom\ApiSdk\Resources\Collection;
    use MyParcelCom\ApiSdk\Resources\CollectionTime;
    use MyParcelCom\ApiSdk\Resources\Shop;

    // Define the address.
    $address = new Address();
    $address
        ->setStreet1('Baker Street')
        ->setCity('London')
        ->setCountryCode('GB')
        ->setStreetNumber(221)
        ->setPostalCode('NW1 6XE')
        ->setFirstName('Sherlock')
        ->setLastName('Holmes')
        ->setEmail('s.holmes@holmesinvestigations.com');

    $shop = new Shop();
    $shop->setId('your-shop-uuid');

    $collectionTime = new CollectionTime();
    $collectionTime
        ->setFrom(1708438673) // Either unix timestamp
        ->setTo('2024-02-20T20:18:59+00:00'); // Or ISO 8601 date

    // Create the collection and set required parameters.
    $collection = new Collection();
    $collection
        ->setShop($owner)
        ->setAddress($address)
        ->setCollectionTime($collectionTime);

    // Post the collection to the MyParcel.com API.
    $createdCollection = $api->createCollection($collection);

.. tip::

    It is possible to leave out both the Address and the Shop, in which case the default shop (oldest shop that the user has access to) and its sender address will be used.

    .. code-block:: php

        use MyParcelCom\ApiSdk\Resources\Collection;
        use MyParcelCom\ApiSdk\Resources\CollectionTime;

        $collectionTime = new CollectionTime();
        $collectionTime
            ->setFrom(1708438673) // Either unix timestamp
            ->setTo('2024-02-20T20:18:59+00:00'); // Or ISO 8601 date

        // Create the collection and set required parameters.
        $collection = new Collection();
        $collection->setCollectionTime($collectionTime);

        // Post the collection to the MyParcel.com API.
        $createdCollection = $api->createCollection($collection);

If you want to have a specific carrier pick up the collection, you can set the contract to use with the collection.

.. warning::
    This requires all shipments in the collection to have the same contract relationship!

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Collection;
    use MyParcelCom\ApiSdk\Resources\CollectionTime;
    use MyParcelCom\ApiSdk\Resources\Contract;
    use MyParcelCom\ApiSdk\Resources\Shop;

    $contract = new Contract();
    $contract->setId('your-contract-uuid');

    $shop = new Shop();
    $shop->setId('your-shop-uuid');

    $shipments = $api->getShipments();
    // filter shipments that you wish to attach to the collection
    $shipmentsForCollection = ...; // Filter out at least ones with the requested contract.

    $collectionTime = new CollectionTime();
    $collectionTime
        ->setFrom(1708438673)
        ->setTo(1708439673);

    $collection = new Collection();
    $collection
        ->setShop($shop)
        ->setCollectionTime($collectionTime)
        ->setShipments($shipmentsForCollection)
        ->setContract($contract);

Adding shipments to a collection
--------------------------------
There are three ways to add a shipment to a collection.

When creating a collection, you can add shipments to it by setting the shipments on the collection.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Collection;
    use MyParcelCom\ApiSdk\Resources\CollectionTime;
    use MyParcelCom\ApiSdk\Resources\Contract;
    use MyParcelCom\ApiSdk\Resources\Shop;

    $contract = new Contract();
    $contract->setId('your-contract-uuid');

    $shop = new Shop();
    $shop->setId('your-shop-uuid');

    // Filter the shipments that you wish to attach to the collection.
    // Shipments have to be of the same shop (and use the same contract as the collection if any).
    $shipments = $api->getShipments($shop);
    $shipmentsForCollection = ...;

    $collectionTime = new CollectionTime();
    $collectionTime
        ->setFrom(1708438673)
        ->setTo(1708439673);

    $collection = new Collection();
    $collection
        ->setShop($shop)
        ->setCollectionTime($collectionTime)
        ->setShipments($shipmentsForCollection)
        ->setContract($contract);

Another option is to use the ``addShipmentsToCollection()`` method on the ``MyParcelComApiInterface``.
This method accepts either an array of shipment ids or an array of ``ShipmentInterface`` objects.

.. code-block:: php

    $collection = new Collection();
    $collection->setId('your-collection-uuid');

    $shipments = $api->getShipments();
    $shipmentsForCollection = ...; // Some filtering

    $api->addShipmentsToCollection($collection, $shipmentsForCollection);

The last option is to use the collection relationship when creating a shipment.
A shipment can be added to an already created collection by using the ``setCollection`` method an object implementing the ``ShipmentInterface``.

.. code-block:: php

    use MyParcelCom\ApiSdk\Resources\Shipment;
    use MyParcelCom\ApiSdk\Resources\Collection;

    $collection = $api->getCollection('your-collection-uuid');

    $shipment = new Shipment();
    $shipment->setCollection($collection);

    // Other shipment information
    $shipment->set...();

    // Post the shipment to the API.
    $createdShipment = $api->createShipment($shipment);

Retrieving collections
----------------------
After the collection has been created, it will be updated with an id and a status.
Using the id, the collection can be retrieved from the API.

.. code-block:: php

    $collectionId = 'your-collection-uuid';
    // Get the updated collection from the API based on its id.
    $collection = $api->getCollection($collectionId);

It is also possible to retrieve all collections.

.. code-block:: php

    // Retrieve all available collections.
    $collections = $api->getCollections();

Updating a collection
---------------------
As long as a collection has not yet been registered, it can be updated using the ``updateCollection()`` method on the ``MyParcelComApiInterface``.
Pay careful attention to which fields are allowed to be updated and which are not, which can be found in the `API specification <https://api-specification.myparcel.com/#tag/Collections/paths/~1collections~1%7Bcollection_id%7D/patch>`_.

.. code-block:: php

    $collection = $api->getCollection('your-collection-uuid');

    // Make changes to the collection object.
    $collection->setDescription('My new description');

    // Update the collection in the API.
    $updatedCollection = $api->updateCollection($collection);

Registering a collection
------------------------
Registration of a collection is done by calling the ``registerCollection()`` method on the ``MyParcelComApiInterface``.

.. code-block:: php

    $collection = $api->getCollection('your-collection-uuid');

    $registeredCollection = $api->registerCollection($collection);

Alternatively, the ``setRegister()`` method can be used on the collection object before posting or patching it to the API.

.. code-block:: php

    $collection = $api->getCollection('your-collection-uuid');
    $collection->setRegister(true);

    $registeredCollection = $api->updateCollection($collection);

Deleting a collection
---------------------
As long as a collection has not yet been registered, it can be deleted using the ``deleteCollection()`` method on the ``MyParcelComApiInterface``.

.. code-block:: php

    $collection = $api->getCollection('your-collection-uuid');

    $api->deleteCollection($collection);

Generate a manifest for a collection
------------------------------------
Sometimes a carrier might request a manifest for a collection, or perhaps you want to generate a manifest for a collection yourself.
This can be done by calling the ``generateManifestForCollection()`` method on the ``MyParcelComApiInterface``.

.. code-block:: php

    $collection = $api->getCollection('your-collection-uuid');

    /** @var \MyParcelCom\ApiSdk\Resources\ManifestInterface $manifest */
    $manifest = $api->generateManifestForCollection($collection);