README

Wymagania
Instalacja
Użycie
Modele
- Request
- Response
  - Service
  - DropoffPoint
  - PickupDate
  - Event
Słownik

Wymagania

PHP 5.4.0 lub wyższy;
ext-json;
ext-curl;

Instalacja

Composer:

composer require allekurier/api_v1

Zip:

require __DIR__ . '/my_path/allekurier/api_v1/AutoLoader.php';

allekurier\api_v1\AutoLoader::init(__DIR__ . '/my_path');

Użycie

Przygotowanie API

$credentials = new allekurier\api_v1\Credentials('login', 'hasło');
$api = new allekurier\api_v1\AKAPI($credentials);

Utworzenie zamówienia

Funkcja zwraca HID zlecenia, numer listu przewozowego, aktualny status, koszt przesyłki.

Poprawnym wyjściem jest status ready. W sytuacji gdy zwrócony status będzie równał się processing należy zapisać HID zlecenia i w określonym interwale czasowym sprawdzać (funkcja getStatus) czy zlecenie zostało już przetworzone, aby kontynuować przetwarzanie (pobranie i wydruk dokumentów). Przyczyną stanu processing może np. być awaria systemu przewoźnika.

$order = new allekurier\api_v1\model\Order(
    'nazwa usługi',
    'typ opakowania',
    'opis przesyłki',
    'metoda odbioru',
    'kwota pobrania',
    'kwota ubezpieczenia',
    'numer referencyjny',
    'wartość towaru',
    'voucher'
);

$sender = new allekurier\api_v1\model\Sender(
    'nazwa nadawcy',
    'osoba kontaktowa',
    'kod pocztowy',
    'adres',
    'miasto',
    'telefon',
    'email',
    'kod państwa',
    'punkt przewoźnika',
    'numer konta bankowego'
);

$recipient = new allekurier\api_v1\model\Recipient(
    'nazwa odbiorcy',
    'osoba kontaktowa',
    'kod pocztowy',
    'adres',
    'miasto',
    'telefon',
    'email',
    'kod państwa',
    'punkt przewoźnika',
    'kod stanu'
);

// Wymagany gdy Order - metoda odbioru = register
$pickup = new allekurier\api_v1\model\Pickup(
    'data odbioru',
    'od godz',
    'do godz'
);

$packages = new allekurier\api_v1\model\Packages([
    new allekurier\api_v1\model\Package('waga', 'szerokość', 'wysokość', 'długość', 'czy standardowa')
]);

$additionalServices = [
    'sms',
    'email_notif_delivered'
];

$action = new allekurier\api_v1\action\CreateOrderAction(
    $order,
    $sender,
    $recipient,
    $packages,
    $pickup,
    $additionalServices
);

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    echo $response->number();
    echo $response->hid();
    echo $response->cost();
    echo $response->status();
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/order_create \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &Order%5Bpackage%5D=*typ_opakowania*
      &Order%5Bcod%5D=*kwota_pobrania*
      &Order%5Binsurance%5D=*kwota_ubezpieczenia*
      &Order%5Bdelivery%5D=*metoda_odbioru*
      &Order%5Bservice%5D=*nazwa_uslugi*
      &Order%5Bdescription%5D=*opis_przesylki*
      &Order%5Bvalue%5D=*wartosc_towaru*
      &Sender%5Bcountry%5D=*kod_kraju*
      &Sender%5Bphone%5D=*telefon*
      &Sender%5Baddress%5D=*adres*
      &Sender%5Bpostal_code%5D=*kod_pocztowy*
      &Sender%5Bperson%5D=*osoba_kontaktowa*
      &Sender%5Bcity%5D=*miasto*
      &Sender%5Bemail%5D=*email*
      &Sender%5Bname%5D=*nadawca*
      &Sender%5Bbank_account%5D=*numer_banku_do_zwrotu_pobrania*
      &Sender%5Bdropoff_point%5D=*kod_punktu_przewoznika*
      &Recipient%5Bcountry%5D=*kod_kraju*
      &Recipient%5Bpostal_code%5D=*kod_pocztowy*
      &Recipient%5Bphone%5D=*telefon*
      &Recipient%5Bcity%5D=*miasto*
      &Recipient%5Bname%5D=*odbiorca*
      &Recipient%5Bperson%5D=*osoba_kontaktowa*
      &Recipient%5Baddress%5D=*adres*
      &Recipient%5Bemail%5D=*email*
      &Packages%5B0%5D%5Bweight%5D=*waga_paczki*
      &Packages%5B0%5D%5Bheight%5D=*wysokosc_paczki*
      &Packages%5B0%5D%5Bwidth%5D=*szerokosc_paczki*
      &Packages%5B0%5D%5Blength%5D=*dlugosc_paczki*
      &Packages%5B0%5D%5Bcustom%5D=*czy_standardowa*
      &Pickup%5Bdate%5D=*data*
      &Pickup%5Bfrom%5D=*od_godz*
      &Pickup%5Bto%5D=*do_godz*
      &Services%5B0%5D=*nazwa_uslugi*'

Response:

{
    "Error":[],
    "Response":{
        "hid":"",
        "number":null,
        "cost":"12.76",
        "status":"processing"
    }
}

Pobranie aktualnego statusu przesyłki

Zwraca podstawowe informacja o zleceniu na podstawie jego numeru. Służy do pobierania ostatniego zdarzenia z historii zlecenia (statusu), numeru przesyłki i śledzenia, oraz dat (utworzenie, nadanie, doręczenie).

$action = new allekurier\api_v1\action\GetOrderStatusAction('hid przesyłki');

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    echo $response->hid();
    echo $response->number();
    echo $response->traceNumber();
    echo $response->created();
    echo $response->sent();
    echo $response->delivered();
    echo $response->date();
    echo $response->name();
    echo $response->status();
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/order_status \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &hid=*hid*'

Response:

{
    "Error": [],
    "Response": {
        "Order": {
            "hid": "",
            "number": null,
            "trace_number": null,
            "created": "2017-11-16 13:39:58",
            "sent": null,
            "delivered": null,
            "status": "canceled"
        },
        "Event": {
            "date": "2017-11-16 13:41:06",
            "status": "canceled",
            "name": "Anulowane"
        }
    }
}

Pobranie listu przewozowego

Pobieranie dokumentów do wydruku. Funkcja zwraca zakodowany (base64) pdf z listami przewozowymi. W przypadku DPD domyślnie zwracany jest protokół przekazania towaru. Dokumenty można drukować tylko gdy status zlecenia ustawiony jest na ready.

$action = new allekurier\api_v1\action\GetOrderLabelAction(
    'numer przesyłki', 
    'czy pobierać małe etykiety?' // true/false (parametr opcjonalny)
);

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    file_put_contents('my_path/label.pdf', $response->label());
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/order_label \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &number=*numer_przesylki*'

Response:

{
    "Error":[],
    "Response":{
        "Order":{
            "hid":"",
            "number":"",
            "status":"ready"
        },
        "label":""
    }
}

Pobranie historii przesyłki

Śledzenie przesyłki. Zwracana jest data każdego zdarzenia, kod oraz opis. Dodatkowo podawane są HID zlecenia, data utworzenia, faktycznego nadania oraz doręczenia (lub zwrotu do nadawcy). Zwraca tablicę zdarzeń Event

$action = new allekurier\api_v1\action\GetOrderHistoryAction('numer przesyłki');

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    foreach ($response->history() as $event) {
        echo $event->date();
        echo $event->name();
        echo $event->status();
    }
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/order_history \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &number=*numer_przesylki*'

Response:

{
    "Error": [],
    "Response": {
        "Order": {
            "hid": "",
            "number": "",
            "created": "2017-11-14 11:49:11",
            "sent": null,
            "delivered": null
        },
        "Event": [
            {
                "date": "2017-11-14 11:49:11",
                "status": "created",
                "name": "Zlecenie utworzone"
            },
            ...
        ]
    }
}

Anulowanie zamówienia

Anulowanie zlecenia na podstawie numeru. Listy przewozowe UPS należy bezwzględnie anulować, nawet w sytuacji gdy kurier nie odbierze przesyłki (mimo to naliczana jest opłata za transport!). Przyjmujemy że bez względu na przewoźnika list przewozowy należy anulować. Anulowanie listu powoduje anulowanie zlecenia odbioru z danej lokalizacji.

$action = new allekurier\api_v1\action\CancelOrderAction('numer przesyłki');

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    if ($response->isCanceled()) {
        echo 'Anulowane';
    }
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/order_cancel \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &number=*numer_przesylki*'

Response:

{
    "Error": [],
    "Response": {
        "status": 1
    }
}

Pobranie usług

Metoda zwraca dostępne usługi wraz z kwotami dla podanych danych. Zwraca tablicę usług Service

$order = allekurier\api_v1\model\Order::createForPricing(
    'typ opakowania',
    'kwota pobrania',
    'kwota ubezpieczenia'
);

$sender = allekurier\api_v1\model\Sender::createForPricing(
    'kod państwa',
    'kod pocztowy tylko dla palet'
);

$recipient = allekurier\api_v1\model\Recipient::createForPricing(
    'kod państwa',
    'kod pocztowy tylko dla palet'
);

$packages = new allekurier\api_v1\model\Packages([
    new allekurier\api_v1\model\Package('waga', 'szerokość', 'wysokość', 'długość', 'czy standardowa')
]);

$action = new allekurier\api_v1\action\GetServicesAction($order, $sender, $recipient, $packages);

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    foreach ($response->services() as $service) {
        echo $service->carrierCode();
        echo $service->carrierName();
        echo $service->code();
        echo $service->name();
        echo $service->net();
        echo $service->gross();
    }
}

Pobranie dodatkowych usług

Metoda zwraca dostępne dodatkowe usługi danej usługi wraz z kwotami dla podanych danych. Zwraca tablicę usług dodatkowych AdditionalService

$action = new allekurier\api_v1\action\GetAdditionalServicesAction('nazwa uslugi', 'typ opakowania');

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    foreach ($response->services() as $service) {
        echo $service->code();
        echo $service->name();
        echo $service->net();
    }
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/additional_services \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &service=*kod_uslugi*
      &package=*typ_opakowania*'

Response:

{
    "Error": [],
    "Response": {
        "cod_instant": {
            "name": "Pobranie Natychmiastowe (1 dzień)",
            "price": "2.00"
        },
        "rod": {
            "name": "Zwrot dokumentów",
            "price": "13.00"
        }
    }
}

Pobranie godzin odbioru

Metoda zwraca możliwe godziny odbioru przesyłki przez danego przewoźnika dla zadanego kodu pocztowego. Tablica „from” określa godziny startowe okienka na odbiór, tablica „to” zawiera możliwe końce okienek, Wartości liczone w sekundach od północy np. godzina 11:00 = 11 * 3600 = 39600. Zwaraca tablicę dat PickupDate

$action = new allekurier\api_v1\action\GetPickupDatesAction('przewoźnik', 'kod pocztowy', 'kod państwa');

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    foreach ($response->dates() as $date) {
        echo $date->date();
        echo $date->description();
        var_dump($date->from());
        var_dump($date->to());
    }
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/pickup_dates \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &carrier=*przewoznik*
      &postal_code=*kod_pocztowy*
      &country=*kod_kraju*'

Response:

{
    "Error": [],
    "Response": [
        {
            "date": "2017-11-16",
            "description": "Dzisiaj",
            "from": {
                "41400": "11:30",
                "43200": "12:00"
            },
            "to": {
                "57600": "16:00"
            },
            "to_minima": {
                "41400": 57600,
                "43200": 57600
            },
            "call_to": 43200,
            "class": "todayPickupDate",
            "call_to_formatted": "12:00"
        },
        ...
    ]
}

Pobranie punktów przewoźnika

Metoda zwraca punkty wybranego przewoźnika w okolicy od podanego kodu pocztowego. Zwraca tablicę punktów DropoffPoint

$action = new allekurier\api_v1\action\GetDropoffPointsAction('przewoźnik', 'kod pocztowy');

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    foreach ($response->points() as $point) {
        echo $point->id();
        echo $point->latitude();
        echo $point->longitude();
        echo $point->name();
        echo $point->code();
        echo $point->address();
        echo $point->postalCode();
        echo $point->image();
        echo $point->openHours();
        echo $point->isSupportCod();
    }
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/access_points \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*
      &carrier=*przewoznik*
      &postal_code=*kod_pocztowy*'

Response:

{
    "Error":[],
    "Response":{
        "Coordinates":{
            "longitude":"",
            "latitude":""
        },
        "AccessPoints":[
            {
                "AccessPoints":{
                    "id":"",
                    "latitude":"",
                    "longitude":"",
                    "code":"",
                    "name":"",
                    "address":"",
                    "address2":null,
                    "postal_code":"",
                    "city":"",
                    "image_url":null,
                    "open_hours":null,
                    "cod":"0"
                },
                "0":{
                    "diff":""
                }
            },
            ...
        ]
    }
}

Pobranie środków użytkownika

Metoda zwraca stan konta użytkownika

$action = new allekurier\api_v1\action\GetUserBalanceAction;

$response = $api->call($action);

if ($response->hasErrors()) {
    var_dump($response->getErrors());
} else {
    echo $response->balance();
}

cURL:

curl -X POST \
  https://allekurier.pl/api_v1/user_balance \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'User%5Bemail%5D=*email*
      &User%5Bpassword%5D=*haslo*'

Response:

{
    "Error": [],
    "Response": [
        {
            "User": {
                "hid": "XXXXXX",
                "balance": "0.00",
                "free": "0.00"
            }
        }
    ]
}

Modele

Request

Order

Pole	Opis	Wymagane	Typ	Opis
service	Nazwa usługi	tak	string	dpdclassic, dhlstandard, upsexpresssaver, upsstandard, kexstandard, inpostcourier, paczkawruchu
package	Typ opakowania	tak	string	parcel, envelope, europallet, isopallet, bigpallet
description	Opis przesyłki	tak	string
delivery	Metoda odbioru	tak	string	register - Zamawiam kuriera po odbiór przesyłki, none - Dostarczę przesyłkę do punktu przewoźnika.
cod	Kwota pobrania	nie	float
insurance	Kwota ubezpieczenia	nie	float
reference	Numer referencyjny	nie	string	np. numer faktury, zamówienia
value	Wartość towaru	nie	float	Wymagane przy przesyłkach poza Unię Europejską
voucher	Kod vouchera	nie	string

Sender - S / Recipient - R

Pole	Opis	Model	Wymagane	Typ	Opis
name	Odbiorca / Nadawca	S & R	tak	string	imię nazwisko / nazwa firmy
person	Osoba kontaktowa	S & R	tak	string	imię nazwisko osoby kontakowej
postal_code	Kod pocztowy	S & R	tak	string
address	Adres	S & R	tak	string	ulica, numer domu / mieszkania
city	Miasto	S & R	tak	string
phone	Telefon	S & R	tak	string
email	Email	S & R	tak	string
country	Kod kraju	S & R	tak	string	ISO 3166-1 alfa-2
dropoff_point	Kod punktu przewoźnika	S & R	nie	string	Punkty przewoźników
bank_account	Numer konta bankowego	S	nie	string	wymagane gdy podano Order.cod
state	Kod stanu	R	nie	string	wymagane dla USA i Kanady

Pickup

Pole	Opis	Wymagane	Typ	Przykład
date	Data	tak	string	2017-01-20
from	Od godz	tak	string	12:00:00
to	Do godz	tak	string	16:00:00

Package (Typ opakowania)

Pole	Opis	Wymagane	Typ	Opis
weight	Waga	tak	float
width	Szerokość	tak	float
height	Wysokość	tak	float
length	Długość	tak	float
custom	Czy standard	tak	bool	Paczka standardowa / niestandardowa

Response

Service

Pole	Opis	Typ
carrierCode	Kod przewoźnika	string
carrierName	Nazwa przewoźnika	string
code	Kod usługi	string
name	Nazwa usługi	string
net	Koszt netto	float
gross	Koszt brutto	float

AdditionalService

Pole	Opis	Typ
code	Kod usługi	string
name	Nazwa usługi	string
net	Koszt netto	float

DropoffPoint

Pole	Opis	Typ
id	Id punktu	int
latitude		string
longitude		string
name	Nazwa punktu	string
code	Kod punktu	string
address	Adres punktu	string
postalCode	Kod pocztowy	string
image	Zdjęcie punktu	string
openHours	Godziny otwarcia	string
isSupportCod	Czy obsługuje pobrania	bool

PickupDate

Pole	Opis	Typ
date	Data	string
description	Opis	string
from	Tablica godz podjazdu od godz	array
to	Tablica godz podjazdu do godz	array

Event

Pole	Opis	Typ
name	Nazwa zdarzenia	string
date	Data zdarzenia	string
status	Status zdarzenia	string

Słownik

Typ opakowania - package

Kod	Nazwa	Max waga	Szerokość	Długość	Wysokość
parcel	Paczka	70	1 > && < 270	1 > && < 300	1 > && < 270
envelope	List	0,5	-	-	-
europallet	Paleta 120x80 cm	900	-	-	< 180
isopallet	Paleta 120x100 cm	900	-	-	< 180
bigpallet	Paleta 120x120 cm	900	-	-	< 180

Przewoźnicy

Kod	Nazwa	Kod usług
dpd	Dpd	dpdclassic
ups	Ups	upsstandard, upsexpresssaver, upsexpress
dhl	Dhl	dhlstandard
inpostcourier	Inpost Kurier	inpostcourier
ruch	Ruch	paczkawruchu
poczta	Poczta Polska
inpost	Inpost Paczkomaty	paczkomat
fedex	Fedex Polska	fedex
geis	Geis Parcel	kexstandard

allekurier / api_v1

Maintainers

Details

README

Wymagania

Instalacja

Użycie

Przygotowanie API

Utworzenie zamówienia

cURL:

Response:

Pobranie aktualnego statusu przesyłki

cURL:

Response:

Pobranie listu przewozowego

cURL:

Response:

Pobranie historii przesyłki

cURL:

Response:

Anulowanie zamówienia

cURL:

Response:

Pobranie usług

Pobranie dodatkowych usług

cURL:

Response:

Pobranie godzin odbioru

cURL:

Response:

Pobranie punktów przewoźnika

cURL:

Response:

Pobranie środków użytkownika

cURL:

Response:

Modele

Request

Order

Sender - S / Recipient - R

Pickup

Package (Typ opakowania)

Response

Service

AdditionalService

DropoffPoint

PickupDate

Event

Słownik

Typ opakowania - package

Przewoźnicy