Giter Club home page Giter Club logo

myparcel-php-api's Introduction

MyParcel API client for PHP

PHP version Latest Version on Packagist Software License Tests StyleCI Total Downloads

MyParcel makes sending packages easy.

MyParcel API documentation

Requirements

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

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.

myparcel-php-api's People

Contributors

avido avatar it-can avatar mvdnbrk avatar zenowebdev avatar

Stargazers

 avatar  avatar

Watchers

 avatar  avatar

myparcel-php-api's Issues

Duplicate request headers.

Due to the fact that MyParcel requires a custom request header for creating shipments:

Content-Type: application/vnd.shipment+json; charset=utf-8

The default Content-Type in Mvdnbrk\MyParcel\Client is set to:

Content-Type: application/json

Merging the request headers results in a duplicate Content-Type header:

Content-Type: application/json
Content-Type: application/vnd.shipment+json; charset=utf-8

This may result in an invalid request.

Request multiple labels at once

Is your feature request related to a problem? Please describe.
Request labels for multiple shipments

Describe the solution you'd like
Array of shipments to request shipment for

Describe alternatives you've considered

Multiple Shipments

Is your feature request related to a problem? Please describe.
Request multiple shipment (concept) at once

Describe the solution you'd like
Array of parcels to request shipment for

Describe alternatives you've considered

Missing response attributes e.g. link_tracktrace

Describe the bug
Not all attributes from the api are present in the objects. When getting track and trace information some attributes are missing in the tracktrace object. link_tracktrace for example.

To Reproduce
Request tracktrace information: $myparcel->tracktrace->get('Shipment_id');

Expected behavior
Do not check if property exists in the setAttribute function in the HasAttributes class so all other properties can be used.

Please complete the following information:

  • Version of this package: 2.1.0
  • PHP Version: 7.4.0

Help needed: export labels to pdf

I've a question about the exporting of labels. When user the "$myparcel->labels->get($id)" function it returns apparently the source code of the pdf. I'm really confused about how to convert this to a useable pdf download. Can you give me an example on how to go about this?
Many thanks in advance!

My environment

Laravel 5.7, php 7.1, windows 10

Shipment labels A4

Is there a way to set options for the shipment labels? I want A4, and not A6...

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.