README

La Poste Suivi API

The best way to track your La Poste, Colissimo and Chronopost packages.

What does it do ?

This framework-agnostic package is an implementation of the tracking API version 2 from La Poste.
This API allows you to track your shipments in real time. "Suivi v2" allows you to harmonize the delivery status of tracked parcels, Colissimo parcels and Chronopost shipments.

More information on the developer page.

Installation

It is recommended to use composer to install the package :

$ composer require debuss-a/lapostesuivi:^2 

PHP 5.6 or newer is required.

Usage

First of all you need an X-Okapi-Key to use the API.
Subscribe to a new Tracking API to get one (it is free), here, then you can instantiate the app :

require_once __DIR__.'/vendor/autoload.php';

$app = new LaPoste\Suivi\App('YOUR_X-OKAPI-KEY_HERE');

You need to create an object Request for every tracking number :

$request = new \LaPoste\Suivi\Request('6M17554710224');

You can pass 2 more parameters to define the lang and ip_address you wish to set up. By default, lang is set to fr_FR and ip_address to $_SERVER['REMOTE_ADDR'] (or 123.123.123.123 if REMOTE_ADDR is not defined).

To track only 1 parcel, you can use the LaPoste\Suivi\App::call method :

require_once __DIR__.'/vendor/autoload.php';

$app = new LaPoste\Suivi\App('YOUR_X-OKAPI-KEY_HERE');
$request = new \LaPoste\Suivi\Request('6M17554710224');
$response = $app->call($request);

To track more than 1 parcel, use the LaPoste\Suivi\App::callMultiple method :

require_once __DIR__.'/vendor/autoload.php';

$app = new LaPoste\Suivi\App('YOUR_X-OKAPI-KEY_HERE');
$requests = [
    new \LaPoste\Suivi\Request('6M17554710224'),
    new \LaPoste\Suivi\Request('EY604176344FR', LaPoste\Suivi\App::LANG_EN),
    new \LaPoste\Suivi\Request('6M17554710224'),
];
$responses = $app->callMultiple($requests);

LaPoste\Suivi\App::call and LaPoste\Suivi\App::callMultiple return instances of LaPoste\Suivi\Response.

Note: in the case of LaPoste\Suivi\App::callMultiple, this package uses curl_multi* functions therefore all tracking numbers are tracked asynchronously.
This means the tracking of multiple packages is done at the same time instead of one by one, and it is much MUCH! faster.

Decorator

The package is included with an AppV1Decorator decorator class that you can use to format the output of the v2 API to the v1 API.

$app = new \LaPoste\Suivi\AppV1Decorator(
    new LaPoste\Suivi\App('YOUR_X-OKAPI-KEY_HERE')
);

$single_response = $app->call(new \LaPoste\Suivi\Request('6A18987970674'));

$multiple_response = $app->callMultiple([
    new \LaPoste\Suivi\Request('6A18987970674'),
    new \LaPoste\Suivi\Request('6A18987970674'),
    new \LaPoste\Suivi\Request('6A18987970674')
]);

Result of call :

array (
  'code' => '6A18987970674',
  'date' => '06/07/2020',
  'status' => 'LIVRE',
  'message' => 'Votre colis est livré à votre gardien.',
  'link' => 'https://www.laposte.fr/particulier/outils/suivre-vos-envois?code=6A18987970674',
  'type' => 'Colissimo',
)

Result of callMultiple :

array (
  0 => array (
    'data' => array (
      'code' => '6A18987970674',
      'date' => '06/07/2020',
      'status' => 'LIVRE',
      'message' => 'Votre colis est livré à votre gardien.',
      'link' => 'https://www.laposte.fr/particulier/outils/suivre-vos-envois?code=6A18987970674',
      'type' => 'Colissimo',
    ),
  ),
  1 => array (
    'data' => array (
      'code' => '6A18987970674',
      'date' => '06/07/2020',
      'status' => 'LIVRE',
      'message' => 'Votre colis est livré à votre gardien.',
      'link' => 'https://www.laposte.fr/particulier/outils/suivre-vos-envois?code=6A18987970674',
      'type' => 'Colissimo',
    ),
  ),
  2 => array (
    'data' => array (
      'code' => '6A18987970674',
      'date' => '06/07/2020',
      'status' => 'LIVRE',
      'message' => 'Votre colis est livré à votre gardien.',
      'link' => 'https://www.laposte.fr/particulier/outils/suivre-vos-envois?code=6A18987970674',
      'type' => 'Colissimo',
    ),
  ),
)

Useful if you do not want to refactor all your code to the different v2 API !

License

The package is licensed under the MIT license. See License File for more information.