README

MyParcel makes sending packages easy.

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

License

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

mvdnbrk / myparcel-php-api

Maintainers

Details