README

MyParcel makes sending packages easy.

MyParcel API documentation

Requirements

To use the MyParcel API client, the following things are required:

• Get a free MyParcel account
• Generate your API Key
• Now you're ready to use the MyParcel API client

Installation

You can install the package via composer:

composer require mvdnbrk/myparcel-php-api

Getting started

Initialize the MyParcel client and set your API key:

$myparcel = new \Mvdnbrk\MyParcel\Client();

$myparcel->setApiKey('your-api-key');

Create a parcel

$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([
    'reference' => 'your own reference for the parcel',
    'recipient' => [
        'first_name' => 'John',
        'last_name' => 'Doe'
        'street' => 'Poststraat',
        'number' => '1',
        'number_suffix' => 'A',
        'postal_code' => '1234AA',
        'city' => 'Amsterdam',
        'cc' => 'NL',
    ]
]);

Create a shipment

$shipment = $myparcel->shipments->create($parcel);

// Get the `id` of the shipment. You may save this value for later reference.
$shipment->id;

You have created your first shipment!

Retrieve a label

A label can be retrieved by using $shipment->id. This will return a label in A6 format as a string.

$myparcel->labels->get($shipment->id);

Or you may pass the Shipment instance directly to this method:

$myparcel->labels->get($shipment);

The label format is A6 by default, you may change this by calling the setFormatA4 method:

$myparcel->labels->setFormatA4()->get($shipment);

Setting delivery options for a parcel

You can set delivery options for a parcel by passing in the options directly when you create a parcel:

$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([
    ...
    'recipient' => [
        ...
    ],
    'options' => [
        'description' => 'Description on the label',
        'signature' => true,
        ...
    ],
]);

Or you may use a method like signature, onlyRecipient, returnToSender, ageCheck and labelDescription. You may call any of these methods after constructing the parcel:

$parcel->labelDescription('Your description.')
       ->ageCheck()
       ->onlyRecipient()
       ->returnToSender()
       ->signature();

Mailbox package

This package type is only available for shipments in the Netherlands that fit in a standard mailbox.

$parcel->mailboxpackage();

Send a parcel to a service point

You may send a parcel to a PostNL service point where a customer can pick up the parcel:

$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([
    'recipient' => [
        ...
    ],
    'pickup' => [
        'name' => 'Name of the location',
        'street' => 'Poststraat',
        'number' => '1',
        'postal_code' => '1234AA',
        'city' => 'Amsterdam',
        'cc' => 'NL,
    ]
]);

Retrieve service points

$servicepoints = $myparcel->servicePoints->setPostalcode('1234AA')->setHousenumber('1')->get();

This will return a collection of ServicePoint objects:

$servicepoints->each(function ($item) {
    $item->id;
    $item->name;
    $item->latitude;
    $item->longitude;
    $item->distance;
    $item->distanceForHumans();
    $item->opening_hours;
});

Get a shipment

You can get a shipment by id or your own reference.

$shipment = $myparcel->shipments->get($id);

$shipment = $myparcel->shipments->getByReference('your own reference');

// Get the barcode for the shipment:
$shipment->barcode;

// Get the current status:
$shipment->status;

Track a shipment

You can get detailed track and trace information for a shipment.

$tracktrace = $myparcel->tracktrace->get($id);

// Links:
$tracktrace->link;
$tracktrace->link_portal;

// Check if the shipment is delivered:
$tracktrace->isDelivered;

// Get current state of the shipment:
$tracktrace->code;
$tracktrace->description;
$tracktrace->datetime;

// Get all traces for the shipment, this will return a collection with
// all traces in descending order, including the current state:
$tracktrace->items;

// Convert all items to an array:
$tracktrace->items->all()

Usage with Laravel

You may incorporate this package in your Laravel application by using this package.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mark van den Broek
• All Contributors

License

The MIT License (MIT). Please see License File for more information.