mvdnbrk/myparcel-php-api

MyParcel API client for PHP

MyParcel API client for PHP

![Latest Version on Packagist][ico-version] [![Tests][ico-tests]][link-tests] ![StyleCI][ico-code-style] , _(*1)

MyParcel makes sending packages easy., _(*2)

MyParcel API documentation, _(*3)

Requirements

To use the MyParcel API client, the following things are required:, _(*4)

• 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:, _(*5)

``` bash composer require mvdnbrk/myparcel-php-api, <sub>(*6)</sub>

## Getting started

Initialize the MyParcel client and set your API key:

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

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

Create a parcel

``` php $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', ] ]);, <sub>(*7)</sub>

### Create a shipment

``` php
$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!, <sub>(*8)</sub>

Retrieve a label

A label can be retrieved by using $shipment->id. This will return a label in A6 format as a string., <sub>(*9)</sub>

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

Or you may pass the Shipment instance directly to this method:, <sub>(*10)</sub>

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

The label format is A6 by default, you may change this by calling the setFormatA4 method:, <sub>(*11)</sub>

$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:, <sub>(*12)</sub>

``` php $parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([ ... 'recipient' => [ ... ], 'options' => [ 'description' => 'Description on the label', 'signature' => true, ... ], ]);, <sub>(*13)</sub>

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

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

Mailbox package, <sub>(*14)</sub>

This package type is only available for shipments in the Netherlands that fit in a standard mailbox., <sub>(*15)</sub>

``` php $parcel->mailboxpackage();, <sub>(*16)</sub>

### 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:

``` php
$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:, <sub>(*17)</sub>

$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., <sub>(*18)</sub>

``` php $shipment = $myparcel->shipments->get($id);, <sub>(*19)</sub>

$shipment = $myparcel->shipments->getByReference('your own reference');, <sub>(*20)</sub>

// Get the barcode for the shipment: $shipment->barcode;, <sub>(*21)</sub>

// Get the current status: $shipment->status;, <sub>(*22)</sub>

### Track a shipment

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

``` php
$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., <sub>(*23)</sub>

Changelog

Please see CHANGELOG for more information what has changed recently., <sub>(*24)</sub>

Testing

bash $ composer test, <sub>(*25)</sub>

Contributing

Please see CONTRIBUTING for details., <sub>(*26)</sub>

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities., <sub>(*27)</sub>

Credits

• Mark van den Broek
• All Contributors

License

The MIT License (MIT). Please see License File for more information., <sub>(*28)</sub>