README

Order Tracking API - PHP SDK

A single multifunctional API to track packages worldwide from over 850 courier companies and postal services in the desired language.

Library provides convenient access to business.pkge.net api for applications written in PHP language.

Tracking API documentation are available here: https://business.pkge.net/docs

Requirements

PHP 5.4.0 and later.

Installation

Via Composer (https://getcomposer.org/)

Run the following command:

composer require pkge/php-sdk

To use SDK, use Composer's autoload:

require_once 'vendor/autoload.php';

Getting Started

First, you need initialize api wrapper class with your api key

$api = new \Pkge\API(
    '{API_KEY}', //Your API key
    'en', //API language
    false //Expand related objects
);

Responses Metadata

Metadata for last response, such as requests rate-limiting and pagination information for some API endpoints, available in getLastResponseMetaData() method:

$metadata = $api->getLastResponseMetaData();

//Last response status code
$metadata->responseStatusCode; 

//Requests Rate-Limit information.
$metadata->rateLimit;

//Pagination information
$metadata->pagination;

Entities

All entities used in the SDK and descriptions of their properties, see in /src/Entities

Delivery services endpoints

Access to all delivery services endpoints via couriers property of API object:

$api->couriers;

All available endpoints methods see in \Pkge\Endpoints\Couriers::class

Packages endpoints

Access to all delivery services endpoints via packages property of API object:

$api->packages;

All available endpoints methods see in \Pkge\Endpoints\Packages::class

Webhooks

For handle webhook notifications use \Pkge\Webhook::class. Example:

$webhook = new \Pkge\Webhook('WEBHOOK_SECRET');

try {
    $event = $webhook->handleEvent(
        file_get_contents("php://input"),
        $_SERVER['HTTP_PKGE_WEBHOOK_SIGNATURE']
    );
} catch (\Pkge\Exceptions\WebhookSignatureException $e) {
    die ($e->getMessage());
}

/** @var \Pkge\Entities\Package $updatedPackage */
$updatedPackage = $event->payload;

Exceptions

In some cases, exceptions may occur when making API requests via the SDK. Their description is given below. For more information about what exceptions a particular method can throw, see the PHPDoc comments on this method.

• \Pkge\Exceptions\ApiBadKeyException - Invalid API key specified. How to get API key, see here.
• \Pkge\Exceptions\ApiCouriersNotDetectedException - Failed to automatically identify the delivery service for the given tracking number.
• \Pkge\Exceptions\ApiMaxPackagesAmountUpdatingNowException - Failed to update the package. The maximum number of packages allowed is currently being updated. Wait for the next package to complete the update and repeat the request.
• \Pkge\Exceptions\ApiPackageCannotBeUpdatedException - Failed to update the package. Not enough time has passed since the last update, or the package has already been delivered. Followed by the date of the next possible update in 'payload' if an update is possible.
• \Pkge\Exceptions\ApiPackagesLimitExceededException - You've reached your plan's limit for adding packages for the billing period.
• \Pkge\Exceptions\ApiRequestRateLimitException - Limit for requests per second exceeded.
• \Pkge\Exceptions\ApiTrackNumberExistsException - Tracking number has already been added.
• \Pkge\Exceptions\ApiWrongCourierIdException - Invalid delivery service ID specified.
• \Pkge\Exceptions\ApiWrongTrackNumberException - Invalid or unsupported tracking number format.
• \Pkge\Exceptions\ApiRequestValidationException - Error validating data sent by POST request. See validation errors descriptions in getValidationErrors() method of exception.
• \Pkge\Exceptions\ApiRequestException - General or unknown request error. For a description, see the getMessage()method.

Example

Example demo code see in examples/demo.php. Run:

php ./examples/demo.php