MyParcel SDK

This SDK connects to the MyParcel API using PHP.

Contents

• Contents
• Installation
  • Requirements
  • Installation with Composer
  • Installation without Composer
• Quick start and examples
  • Create a consignment
  • Create multiple consignments
  • Label format and position
  • Package type and options
  • Retrieve data from a consignment
  • Create and download label(s)
• List of classes and their methods
  • Models
  • Helpers
• Tips
• Contribute

Installation

Requirements

The MyParcel SDK works with PHP version >= 7.1.0.

If you have a php version lower than 7.1.0 then we would like to advise you to update your PHP version to a supported versions. For support for PHP version 5.6 you can use release 2.x..

Installation with Composer

This SDK uses Composer. Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. For more information on how to use/install composer, please visit https://getcomposer.org/

To install the MyParcel SDK into your project, simply use

$ composer require myparcelnl/sdk

Installation without Composer

It's also possible to use the SDK without installing it with Composer.

You can download the zip on the project's releases page.

1. Download the package (SDKvx.x.x.zip).
2. Extract the downloaded .zip file and upload the vendor directory to your server.
3. Require src/AutoLoader.php
4. You can now use the SDK in your project!

Quick start and examples

Add the following lines to your project to import the SDK classes for creating shipments.

use MyParcelNL\Sdk\src\Helper\MyParcelCollection;
use MyParcelNL\Sdk\src\Model\MyParcelConsignment;

Create a consignment

This example uses only the required methods to create a shipment and download its label.

$consignment = (new MyParcelConsignment())
    ->setApiKey('api_key_from_MyParcel_backoffice')
    ->setReferenceId('Order 146')
    ->setCountry('NL')
    ->setPerson('Piet Hier')
    ->setFullStreet('Plein 1945 55b')
    ->setPostalCode('2231JE')
    ->setCity('Amsterdam')
    ->setEmail('piet.hier@test.nl');
    
$myParcelCollection = (new MyParcelCollection())
    ->addConsignment($consignment)
    ->setPdfOfLabels()
    ->downloadPdfOfLabels();

Create multiple consignments

This example creates multiple consignments by adding them to one MyParcelCollection() and then creates and downloads one PDF with all labels.

// Create the collection before the loop
$myParcelCollection = (new MyParcelCollection())
    ->setUserAgent('name_of_cms', '1.0'); 

// Loop through your shipments, adding each to the same MyParcelCollection()
foreach ($yourShipments as $yourShipment) {

    $consignment = (new MyParcelConsignment())
        ->setApiKey('api_key_from_MyParcel_backoffice')
        ->setReferenceId($yourShipment['reference_id'])
        ->setPerson($yourShipment['name'])
        ->setPostalCode($yourShipment['postal_code'])
        ->setFullStreet($yourShipment['full_street']) 
        ->setCity($yourShipment['city']);
        
    // Add each consignment to the collection created before
    $myParcelCollection
        ->addConsignment($consignment);
}

Label format and position

Choose to output the label as either A4 or A6 when creating a pdf or download link with the argument $positions of setPdfOfLabels($positions) and setLinkOfLabels($positions).

Example values for $positions:

A4:            A6:
┏━━━━━┳━━━━━┓  ┏━━━━━┓
┃  1  ┃  2  ┃  ┃  x  ┃
┣━━━━━╋━━━━━┫  ┗━━━━━┛
┃  3  ┃  4  ┃
┗━━━━━┻━━━━━┛  

1. 1: Default value. Outputs A4, starting at top left position.
2. false: Outputs at A6 format
3. [1,4]: Defines the position of labels on an A4 sheet. Only applies to the first page, subsequent pages will use the default positioning (1,2,3,4)

More information: https://myparcelnl.github.io/api/#6_F

Package type and options

Set package type with setPackageType($type). Retrieve it after with getPackageType(). For more details on the different types of packages: https://myparcelnl.github.io/api/#6_A_1

1: Package

This is the default package type. It must be explicitly set to allow enabling of further shipment options. It's available for NL, EU and global shipments.

2: Mailbox package

This package type is only available for NL shipments that fit into a mailbox. It does not support additional options. Note: If you still make the request with additional options, bear in mind that you need to pay more than is necessary!

3: Letter

This package type is available for NL, EU and global shipments. The label for this shipment is unpaid meaning that you will need to pay the postal office/courier to send this letter/package. Therefore, it does not support additional options.

4: Digital stamp

This package type is only available for NL shipments and does not support any additional options. Its price is calculated using the package weight, which is set using setPhysicalProperties().

    ->setPackageType(4)
    ->setPhysicalProperties(['weight' => 300]); // weight in grams (required)

Note: This shipment will appear on your invoice on shipment_status 2 (pending - registered) instead of all other shipment types, which don't appear until shipment status 3. Read more: https://myparcelnl.github.io/api/#6_A_1

Package options

These options are only available for package type 1 (package).

Available options:

• only_recipient: Deliver the package only at address of the intended recipient. This option is required for Morning and Evening delivery types.
  • Set: setOnlyRecipient(true)
  • Get: isOnlyRecipient()
• signature: Recipient must sign for the package. This option is required for Pickup and Pickup express delivery types.
  • Set: setSignature(true)
  • Get: isSignature()
• return: Return the package to the sender when the recipient is not home.
  • Set: setReturn(true)
  • Get: isReturn()
• large_format: This option must be specified if the dimensions of the package are between 100 x 70 x 50 and 175 x 78 x 58 cm. If the scanned dimensions from the carrier indicate that this package is large format and it has not been specified then it will be added to the shipment in the billing process. This option is also available for EU shipments.
  • Set: setLargeFormat(true)
  • Get: isLargeFormat()
• age_check: The Customer/Consumer must sign for the package and only receive it when he is at least 18 years.
  • Set: setAgeCheck(true)
  • Get: hasAgeCheck()
• insurance: This option allows a shipment to be insured up to certain amount. NL shipments can be insured for 5000,- euros. EU shipments must be insured for 500,- euros. Global shipments must be insured for 200,- euros. The following shipment options are mandatory when insuring an NL shipment: only_recipient and signature.
  • Set: setInsurance(250) (amount in EUR)
  • Get: getInsurance()

More information: https://myparcelnl.github.io/api/#6_A_3

Retrieve data from a consignment

Most attributes that have a set...() method also have a get...() method to retrieve the data. View all methods for consignments here.

$consignment = new MyParcelConsignment();

echo $consignment->getFullStreet();
echo $consignment->getPerson();
echo $consignment->getPhone();
echo $consignment->getStreet();
// etc...

Get status

After setPdfOfLabels(), setLinkOfLabels() and createConcepts() you can get the status.

$status = $consignment->getStatus();

Get barcode

The barcode is available after setPdfOfLabels() and setLinkOfLabels()

$barcode = $consignment->getBarcode();

Create and download label(s)

Create and directly download PDF with setPdfOfLabels($position) where $positions is the label position value.

$myParcelCollection
    ->setPdfOfLabels()
    ->downloadPdfOfLabels(false); // Opens pdf "inline" by default, pass false as argument to download file  

Create and echo download link to PDF with setLinkOfLabels($position) where $positions is the label position value.

echo $myParcelCollection 
    ->setLinkOfLabels($positions)
    ->getLinkOfLabels();

More information: https://myparcelnl.github.io/api/#6_F

List of classes and their methods

This is a list of all the classes in this SDK and their available methods.

Models

MyParcelNL/Sdk/src/Model

MyParcelConsignment

MyParcelNL/Sdk/src/Model/MyParcelConsignment.php

    $consignment = (new \MyParcelNL\Sdk\src\Model\MyParcelConsignment())
    ->setApiKey('api_key_from_MyParcel_backoffice')
    ->setReferenceId('Order 1203')
    
    // Recipient/address: https://myparcelnl.github.io/api/#7_B
    ->setPerson('Piet Hier')    // Name
    ->setEmail('test@test.nl')  // E-mail address
    ->setPhone('+31 612345678') // Phone number
    ->setCompany('Piet BV')     // Company
    
    ->setFullStreet('Plein 1945 55b') // Street, number and suffix in one line
    // OR send the street data separately:
    ->setStreet('Plein 1945') / Street
    ->setNumber((string)55)   // Number
    ->setNumberSuffix('b')    // Suffix
    
    ->setCity('Amsterdam')    // City
    ->setPostalCode('2231JE') // Postal code
    ->setCountry('NL')        // Country                
            
    // Available package types:
    // 1: Package (default)
    // 2: Mailbox package
    // 3: Letter
    // 4: Digital stamp
    ->setPackageType(1)

    // Options (https://myparcelnl.github.io/api/#6_A_3)
    ->setOnlyRecipient(false)   // Deliver the package only at address of the intended recipient. This option is required for Morning and Evening delivery types.
    ->setSignature(true)        // Recipient must sign for the package. This option is required for Pickup and Pickup express delivery types. 
    ->setReturn(true)           // Return the package to the sender when the recipient is not home.
    ->setLargeFormat(false)     // Must be specified if the dimensions of the package are between 100x70x50 and 175x78x58 cm. 
    ->setInsurance(250)         // Allows a shipment to be insured up to certain amount. Only packages (package type 1) can be insured. 
    
    ->setLabelDescription('Order 10034') // This description will appear on the shipment label for non-return shipments. 
        
    // Delivery: https://myparcelnl.github.io/api/#8
    ->setDeliveryType()
    ->setDeliveryDate()
    ->setDeliveryRemark()    
    
    // Set pickup location
    ->setPickupLocationName('Supermarkt')
    ->setPickupStreet('Straatnaam')
    ->setPickupNumber('32')
    ->setPickupPostalCode('1234 AB')
    ->setPickupCity('Hoofddorp')
      
    // Physical properties
    ->setPhysicalProperties(['weight' => 73]) // Array with physical properties of the shipment. Currently only used to set the weight in grams for digital stamps (which is required)
    
    // Non-EU shipment attributes: see https://myparcelnl.github.io/api/#7_E
    ->setInvoice()
    ->setContents()
    ->addItem();

    // Convert pickup data from checkout
    // You can use these if you use the following code in your checkout: https://github.com/myparcelnl/checkout
    ->setDeliveryDateFromCheckout()
    ->setPickupAddressFromCheckout()

// Get attributes from consignment
$consignment
    ->getApiKey()
    ->getReferenceId()
    ->getBarcode() // Barcode is available after using setLinkOfLabels() or setPdfOfLabels() on the MyParcelCollection the consignment has been added to
    
    ->getLabelDescription()
    ->getMyParcelConsignmentId()
    ->getShopId()
    ->getStatus()
    
    // Recipient info
    ->getPerson()
    ->getEmail()    
    ->getPhone()
    ->getCompany()

    // It doesn't matter whether you used setFullStreet() or set all parts separately
    ->getStreet()
    ->getStreetAdditionalInfo()
    ->getNumber()
    ->getNumberSuffix()
    ->getFullStreet()
    ->getPostalCode()
    ->getCity()
    ->getCountry()
    ->isCdCountry()
    ->isCorrectAddress()
    ->isEuCountry()
        
    // Package type
    ->getPackageType()
    
    // Get value of options
    ->isOnlyRecipient()
    ->isSignature()
    ->isReturn()
    ->isLargeFormat()
    ->getInsurance()
        
    // Get pickup location info
    ->getPickupLocationName()
    ->getPickupStreet()
    ->getPickupNumber()
    ->getPickupPostalCode()
    ->getPickupCity()
    
    // Delivery
    ->getDeliveryDate()
    ->getDeliveryType()
    
    // Physical properties (digital stamps or non-EU shipments)
    ->getPhysicalProperties()

    // Non-EU attributes
    ->getInvoice()
    ->getContents()
    ->getItems()
    ->getTotalWeight()

MyParcelCustomsItem

This object is embedded in the MyParcelConsignment object for global shipments and is mandatory for non-EU shipments.

MyParcelNL/Sdk/src/Model/MyParcelCustomsItem.php

  ->setAmount(3) // Amount of items in the package
  
  // ISIC/IDEP code (https://www.cbs.nl/nl-nl/deelnemers-enquetes/deelnemers-enquetes/bedrijven/onderzoek/lopend/internationale-handel-in-goederen/idep-codelijsten) 
  ->setClassification(0111) // Example: 0111 = "Growing of cereals (except rice), leguminous crops and oil seeds"  
  ->setCountry('NL') // Country of origin
  ->setDescription('Cereal grains')
  ->setItemValue(["amount" => 200, "currency" => "EUR"]) // Must be array with amount and currency like in the example
  ->setWeight() // The total weight for these items in whole grams. Between 0 and 20000 grams.
  
  ->getAmount()
  ->getClassification()
  ->getCountry()
  ->getDescription()
  ->getItemValue()
  ->getWeight()
  
  ->isFullyFilledItem()

Helpers

MyParcelNL/Sdk/src/Helper

MyParcelCollection

Stores all consignments to communicate with the MyParcel API. MyParcelCollection also contains almost all methods from Laravel Collections. If you use Laravel it also extends \Illuminate\Support\Collection.

MyParcelNL/Sdk/src/Helper/MyParcelCollection.php

    ->addConsignment() // Add consignment to collection

    // Get consignments from the collection
    ->getConsignments()
    ->getConsignmentByApiId()
    ->getConsignmentsByReferenceId()

    // Clear the collection
    ->clearConsignmentsCollection()

    // Create or delete concept shipments in the MyParcel Backoffice
    ->createConcepts()
    ->deleteConcepts()
    
    ->getOneConsignment()
    ->getRequestBody()
    
    ->sendReturnLabelMails() // Send return label to customer. The customer can pay and download the label
    ->setLatestData() // Set id and run this function to update all the information about this shipment
    ->setLatestDataWithoutIds() // Receive the last created shipments
    
    ->setLinkOfLabels()
    ->getLinkOfLabels()

    // Refer to 
    ->setPdfOfLabels()
    ->downloadPdfOfLabels()
    
    // To give us insight into which CMS system you're connecting from, you should send a User-Agent. 
    // If you're using a known CMS system it's required. 
    // You must send the name of the CMS system (required) followed by a version number (optional).
    ->setUserAgent('name_of_cms', '1.0')
    ->getUserAgent()

Exceptions

MyParcel uses several types of Exceptions to make the errors clear. It is your responsibility to provide the correct status in a response. These are the Exceptions that we currently use:

AddressException

Exception to be returned when an address is incorrect or not usable.

Class: MyParcelNL\Sdk\src\Exception\AddressException

HTTP status: 412

ApiException

Exception to be returned when a call to MyParcel services has failed.

Class: MyParcelNL\Sdk\src\Exception\ApiException

HTTP status: 502

MissingFieldException

Exception thrown when there is an attempt to dynamically access a field that does not exist.

Class: MyParcelNL\Sdk\src\Exception\MissingFieldException

HTTP status: 500

InvalidArgumentException

Exception thrown if an argument is not the expected type.

Class: \InvalidArgumentException

HTTP status: 500

BadMethodCallException

Exception thrown if a callback refers to an undefined method or if some arguments are missing.

Class: \BadMethodCallException:

HTTP status: 500

Tips

This SDK is not only useful for communicating with MyParcel. This package also contains code that you can take advantage of yourself:

Collections

If you use arrays a lot, Collections are usually better to work with. (documentation) \MyParcelNL\Sdk\src\Support\Collection()

Helpers

\MyParcelNL\Sdk\src\Support\Arr (documentation) \MyParcelNL\Sdk\src\Support\Str (documentation) \MyParcelNL\Sdk\src\Helper\SplitStreet::splitStreet('Plein 1940-45 3b'))

Contribute

1. Check for open issues or open a new issue to start a discussion around a bug or feature.
2. Fork the repository on GitHub to start making your changes.
3. Write one or more tests for the new feature or that expose the bug.
4. Make code changes to implement the feature or fix the bug.
5. Send a pull request to get your changes merged and published.