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.

// 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.

// 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.

// 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.

// 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.

// 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 contract or service options. Learn more about service rates on the service rates resource page.

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.

// 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.

// 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.

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.

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.

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.

// 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.

// 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.

// 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.

// 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.

// 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.

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.

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.

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”.

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.

$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.

// 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.

$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 collections resource and create a collection pages.

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.

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!

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.

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.

$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.

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.

$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.

// 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.

$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.

$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.

$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.

$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.

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

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