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.


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.

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.

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 use your own contracts with your shipment, you should assign it to the shipment before creating it.

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.


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.

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

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


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.


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.

When creating a shipment either a specific contract can be selected, or the SDK will select a preferred contract.


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. The SDK can retrieve these locations from the API and can easily be displayed using the MyParcel.com Delivery Plugin.

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.


The last (optional) parameter is a specific carrier. Including this 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.


Regions

The API supports sending parcels from one country/state/province to another. These are split up into regions in the API. These are mostly used to define which services are available between what regions. A list of these regions as defined by the API can be retrieved through the SDK.