2017 © Pedro Peláez
 

library swipbox

Client Library for Swipbox API integration

image

repox/swipbox

Client Library for Swipbox API integration

  • Tuesday, November 5, 2013
  • by Repox
  • Repository
  • 1 Watchers
  • 0 Stars
  • 3 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 0 Open issues
  • 2 Versions
  • 0 % Grown

The README.md

API Client Library for SwipBox

Introduction

A PHP Client library for easy SwipBox integration, which allows you fast implementation., (*1)

You need an account with SwipBox to use the API., (*2)

Index

, (*3)

, (*4)

Requirements

, (*5)

License

This library is licensed under the MIT License., (*6)

Copyright (C) , (*7)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:, (*8)

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software., (*9)

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE., (*10)

, (*11)

Installation

, (*12)

Composer

For installation with Composer (recommended), add the repox/swipbox package to your composer.json., (*13)

{
    "require": {
        "repox/swipbox": "1.1.*"
    }
}

And enable autoloading by including vendor/autoload.php., (*14)

, (*15)

Manual installation

Download the latest stable tag and unpack src/ into a folder and include the files for use., (*16)

<?php
include 'Swipbox/Client.php';
include 'Swipbox/Exception.php';

When you do a manual install, you will also need to download Guzzle.
I recommend downloading the Guzzle Phar and including it., (*17)

include 'guzzle.phar';

, (*18)

Getting started

When you have acquired the GUID for SwipBox account, you start by instantiating a SwipBox client., (*19)

<?php
use \Swipbox\Client;

$swipbox = new Client('YOUR-GUID-GOES-HERE');

If you are testing your implemenation, you can add a second parameter with the boolean true to the constructor., (*20)

<?php
use \Swipbox\Client;

$swipbox = new Client('YOUR-GUID-GOES-HERE', true);

, (*21)

Parcels

, (*22)

Creating a parcel

Using the create method we can quickly create a package, by passing an array of parameters as first argument. The following parameters are REQUIRED., (*23)

Parameter Description Format
first_name Indicates the first name of the customer alphanumeric(100)
address_1 Indicates the address 1 of the customer alphanumeric(100)
city Indicates the city of the customer alphanumeric(100)
zip Indicates the zip code of the customer alphanumeric(6)
country Indicates country of the customer alphanumeric(100)
email Indicates the email address of the customer alphanumeric(100)
mobile_number Indicates the mobile number of the customer alphanumeric(8, 11 or 12) Allowed formats: 12345678, +4512345678, 004512345678
parcel_size Indicates the size of the parcel 1 for small, 2 for medium or 3 for large parcel
test_parcel Indicates a test parcel 1 (indicates a test parcel), 0 (indicates a real parcel)
return_parcel Indicates if a return parcel is required with the original parcel 1 (indicates a return parcel is requried), 0 (indicates a return parcel is not requried)

The following parameters are OPTIONAL., (*24)

Parameter Description Format
webshop_order_id Indicates the webshop order id alphanumeric(100)
address_2 Indicates the address 2 of the customer alphanumeric(100)
last_name Indicates the last name of the customer alphanumeric(100)
pick_up_id Indicates the desired pick up point for the customer integer(11)

Example

try
{

    $parcel = $swipbox->create( array(
        'first_name' => 'Niels',
        'last_name' => 'Nielsen',
        'address_1' => 'Fantastisk vej 12',
        'city' => 'København N',
        'zip' => 2200,
        'country' => 'DK',
        'email' => 'niels@example.com',
        'mobile_number' => '12345678',
        'parcel_size' => 1,
        'test_parcel' => 0,
        'return_parcel' => 0,
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$parcel now contains a multidimensional array of Parcel ID's and Parcel type ID's., (*25)

echo $parcel['parcels'][0]['parcel_id']; // Integer identifying the Parcel
echo $parcel['parcels'][0]['parcel_type']; // Integer identifying the Parcel type (1 for normal Parcel, 2 for return Parcel)

Provided you wanted to create a return parcel by passing 1 to the return_parcel parameter, you can retrieve the information in index 1 of the multidimensional array., (*26)

// The normal parcel
echo $parcel['parcels'][0]['parcel_id'];
echo $parcel['parcels'][0]['parcel_type'];

// The return parcel
echo $parcel['parcels'][1]['parcel_id'];
echo $parcel['parcels'][1]['parcel_type'];

, (*27)

Activating a parcel

A parcel needs to be activated within 7 days. Otherwise the parcel expires., (*28)

To activate the parcel, you can you the activate method by passing an array of parameters as first argument., (*29)

The following parameters are REQUIRED., (*30)

Parameter Description Format
parcel_id Indicates the id of the created parcel numeric(20)
format Indicates the format of the response 0 for PDF format, 1 for XML format, 2 for JSON format
output Indicated the output of the parcel label 0 for HTTP, 1 for FTP (usage is unknow, just pass 0)

When activating a parcel, the recipient will recieve mail and text notifications., (*31)

Example

try {

    $pdf_label = $swipbox->activate( array(
        'parcel_id' => 27181,
        'format' => 0,
        'output' => 0,

    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$pdf_label will now contain binary data (as we passed 0 in the format which indicates a PDF format) which is the parcel label.
You could view the label in browser for printing simply by echoing the data with the appriate headers, (*32)

header('Content-Type: application/pdf');
echo $pdf_label;

, (*33)

Labels for activated parcels

It's useful to get the parcel data or label when you need them., (*34)

To get the parcel label or information, you can you the get_label method by passing an array of parameters as first argument., (*35)

The following parameters are REQUIRED., (*36)

Parameter Description Format
parcel_id Indicates the id of the created parcel numeric(20)
format Indicates the format of the response 0 for PDF format, 1 for XML format, 2 for JSON format
output Indicated the output of the parcel label 0 for HTTP, 1 for FTP (usage is unknow, just pass 0)

When activating a parcel, the recipient will recieve mail and text notifications., (*37)

Example

try {

    $pdf_label = $swipbox->get_label( array(
        'parcel_id' => 27181,
        'format' => 0,
        'output' => 0,

    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$pdf_label will now contain binary data (as we passed 0 in the format which indicates a PDF format) which is the parcel label.
You could view the label in browser for printing simply by echoing the data with the appriate headers, (*38)

header('Content-Type: application/pdf');
echo $pdf_label;

, (*39)

Cancel parcel

Use this to cancel a parcel with the atatus 'Created' or 'Activated'.
NB: Currently, you cannot get the barcode needed for cancelling a parcel from a parcel that hasn't been activated yet!, (*40)

The following parameters are REQUIRED., (*41)

Parameter Description Format
barcode Indicates the barcode of the parcel alphanumeric(45)

The barcode can be retrieved by getting the label of a parcel (eg. with the JSON format).
A complete example would look something similar to the following example, (*42)

Example

try {

    $json_label = $swipbox->get_label( array(
        'parcel_id' => 27181,
        'format' => 2,
        'output' => 0,

    ));

    $result = $swipbox->cancel(array(
        'barcode' => $json_label['label']['barcode'],
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

This should successfully cancel a parcel., (*43)

, (*44)

Stations

Stations are pick up destinations for the parcel.
When creating a parcel, you can provide a pick_up_id as an optional parameter, specifying the desired pickup destination for the customer., (*45)

The following methods are for locating stations., (*46)

, (*47)

Find nearest station

To get stations that are nearest to a specific address, you can you the find_nearest method by passing an array of parameters as first argument., (*48)

The following parameters are REQUIRED., (*49)

Parameter Description Format
address_1 Indicates the address_1 alphanumeric(100)
city Indicates the city alphanumeric(100)
zip Indicates the zip code alphanumeric(6)
country Indicates the country alphanumeric(100)
parcel_size Indicates the size of the parcel 1 for small, 2 for medium or 3 for large parcel

The following parameters are OPTIONAL., (*50)

Parameter Description Format
address_2 Indicates the address_2 alphanumeric(100)
no_of_stations Indicates the number of stations to find integer (defaults to 3)

Example

try {

    $result = $swipbox->find_nearest(array(
        'address_1' => 'Rosenvangs Alle 12',
        'city' => 'Aarhus',
        'zip' => '8000',
        'country' => 'DK',
        'parcel_size' => 1,
        'no_of_stations' => 5,
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$result will now contain a multidimensional array with 5 stations sorted by the nearest to the address specified., (*51)

, (*52)

Find Active Favorites

To get stations that are active favorite stations for a specific customer, you can you the find_active_favorites method by passing an array of parameters as first argument., (*53)

The following parameters are REQUIRED., (*54)

Parameter Description Format
email Indicates the email address for the customer alphanumeric(100)

Example

try {

    $result = $swipbox->find_active_favorites(array(
        'email' => 'niels@example.com',
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$result will now contain a multidimensional array with 5 stations., (*55)

, (*56)

Find stations near to favorite

To get stations that are near the first active favorite station for a specific customer, you can you the find_near_to_favorite method by passing an array of parameters as first argument., (*57)

The following parameters are REQUIRED., (*58)

Parameter Description Format
email Indicates the email address for the customer alphanumeric(100)

The following parameters are OPTIONAL., (*59)

Parameter Description Format
no_of_stations Indicates the number of stations to find integer (defaults to 3)

Example

try {

    $result = $swipbox->find_near_to_favorite(array(
        'email' => 'niels@example.com',
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$result will now contain a multidimensional array with 3 stations., (*60)

, (*61)

Find stations by zip

To get stations specific for a zip code, you can use the find_by_zip method by passing an array of parameters as first argument., (*62)

The following parameters are REQUIRED., (*63)

Parameter Description Format
zip Indicates the zip code alphanumeric(6)

Example

try {

    $result = $swipbox->find_by_zip(array(
        'zip' => '8000',
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$result will now contain a multidimensional array with all stations within the specified zip code., (*64)

, (*65)

Get station by its pick ip ID

To get details for a specific station, you can use the get_station_by_id method by passing an array of parameters as first argument., (*66)

The following parameters are REQUIRED., (*67)

Parameter Description Format
pick_up_id Indicates the id of the pick up point integer(11)

Example

try {

    $result = $swipbox->get_station_by_id(array(
        'pick_up_id' => '1259',
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$result will now contain a multidimensional array with details on the station you specified by it pick up ID., (*68)

, (*69)

Tracking parcels

The track and trace function which can identify the events for a parcel.
you can use the track method by passing an array of parameters as first argument., (*70)

The following parameters are REQUIRED., (*71)

Parameter Description Format
barcode Indicates the barcode number of the parcel alphanumeric(45)

Example

try {

    $json_label = $swipbox->get_label( array(
        'parcel_id' => 27181,
        'format' => 2,
        'output' => 0.
    )); 

    $track = $swipbox->track(array(
            'barcode' => $json_label['label']['barcode'],
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

$track will now contain a multidimensional array with details alle events the parcel tracking has recorded., (*72)

, (*73)

Errors - Handling exceptions

By echoing the exception message you will get the message return from SwipBox., (*74)

Example

try {

    $result = $swipbox->find_by_zip(array(
        'non_existing_parameter' => '8000',
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getMessage();
}

This will cause the SwipBox client to thrown an Exception - by handling it like in the example, the result will be echoing the error message (which in this case would be "Zip is missing")., (*75)

, (*76)

Error codes

It is also possible to handle the error code, as these are linked to the error message.
, (*77)

Example

try {

    $result = $swipbox->find_by_zip(array(
        'non_existing_parameter' => '8000',
    ));

}
catch( \Swipbox\Exception $e)
{
    echo $e->getCode();
}

Same error as before, but you are getting the error code 14, which corresponds to the same message as before., (*78)

The following table show possible error codes and messages., (*79)

Error code Description
1 First name is missing
2 Invalid first name
3 Invalid last name
4 Address 1 is missing
5 No stations found
6 Parcel activation failed
7 Parcel creation failed
8 Communication error
9 No track & trace information found
10 Invalid Address 1
11 Invalid Address 2
12 City is missing
13 Invalid city
14 Zip is missing
15 Invalid zip
16 Country is missing
17 Invalid country
18 Email is missing
19 Invalid email
20 Mobile number is missing
21 Invalid mobile number
22 Parcel size missing
23 Invalid parcel size value
24 Test parcel is missing
25 Invalid test parcel value
26 Return parcel is missing
27 Invalid return parcel is missing
28 Invalid webshop id
29 Invalid pick up id
30 Invalid parcel id
31 Parcel ID is missing
32 Invalid format value
33 Parcel format is missing
34 Invalid output value
35 Parcel output missing
36 Invalid barcode
37 Barcode missing
38 Invalid GUID
39 Parcel cancellation failed
40 File delivery failed
41 No free pickup stations found
42 Parcel is already activated
42 Some problem occurred

The Versions

05/11 2013

dev-master

9999999-dev

Client Library for Swipbox API integration

  Sources   Download

MIT

The Requires

 

by Dan Storm

05/11 2013

1.1.2

1.1.2.0

Client Library for Swipbox API integration

  Sources   Download

MIT

The Requires

 

by Dan Storm