Dokumentacja Web API ver. 2

Wprowadzenie

Web API jest interfejsem programistycznym do serwisu apaczka.pl. Umożliwia integrację zewnętrznych systemów w celu wysyłania przesyłek za pośrednictwem operatora logistycznego apaczka.pl, bez konieczności logowania się na stronie www serwisu.

Zachęcamy również do zapoznania się z dokumentacją do integracji mapy punków odbioru na własnej stronie internetowej: Dokumentacja API v2 Mapa.

Włączenie Web API

Do korzystania z apaczka Web API klient musi mieć podpisaną umowę z apaczka.pl oraz posiadać konto w serwisie. W celu włączenia Web API należy skontaktować się z Centrum Wsparcia i Edukacji Klienta lub skontaktować się w opiekunem handlowym. Aktualne dane kontaktowe znajdują się w zakładce kontakt.

Jeśli mają Państwo włączone Web API to w menu po lewej stronie serwisu znajduje się zakładka Web API. Następnie należy w niej dodać aplikację podając jej nazwę. System wygeneruje unikalne App ID oraz App Secret, które należy podać w swojej integracji. Możliwe jest dodanie wielu aplikacji do obsługi różnych integracji.

Request

Wszystkie dane należy kierować na odpowiedni endpoint na adres Web API:

https://www.apaczka.pl/api/v2/

Lista endpoint`ów znajduje się w dokumentacji niżej. Każdy request powinien zawierać zestaw danych przesyłanych jako POST. Request powinien wyglądać w następujący sposób:

$requestData = [ 'app_id' => $appId, 'request' => $data, 'expires' => $expires, 'signature' => $signature ];

• app_id - identyfikator uzyskany po założeniu aplikacji w zakładce Web Api.
• request - zestaw wymaganych danych zapisanych w strukturze JSON. Dane są opisane przy każdym endpoint.
• expires - timestamp do kiedy ważny jest request. Timestamp musi być większy niż obecny. Maksymalna ważność request`u to 30 minut.
• signature - podpis zestawu danych. Sposób generowania tego klucza została opisana poniżej.

Po wysłaniu danych otrzymuje się informacje zwrotną - Response.

Autoryzacja - Signature

Wszystkie przesyłane dane muszą zawierać signature wygenerowany na podstawie przesyłanych danych. Signature musi być wygenerowana na podstawie App ID, nazwy endpoint`u, danych w request oraz daty wygaśnięcia ważności request`u używając metody HMAC, z wykorzystaniem algorytmu SHA256, podając jako klucz App Secret. Przykładowy kod do generowania signature w PHP:

function getSignature( $string, $key ) { return hash_hmac( 'sha256', $string, $key ); } function stringToSign( $appId, $route, $data, $expires ) { return sprintf( "%s:%s:%s:%s", $appId, $route, $data, $expires ); } $signature = getSignature( stringToSign( $appId, $route, $data, $expires ), $appSecret );

Response

Każdy Request zwraca response w strukturze JSON. Przykładowy response wygląda tak:

{ "status":200, "message":"", "response":{} }

• status - w tej chwili Web Api zwraca dwa statusy: 200 w momencie kiedy odpowiedź jest poprawna oraz 400 w momencie wystąpienia błędu.
• message - informacja dot. request`u. Najczęściej występuje w przypadku błędu.
• response - zwracane dane. Opis zwracanych danych został opisany dla każdego endpoint`u.

Endpoints

Poniżej znajduje się lista endpoint`ów do wykorzystania w request`ach do Web Api apaczka.pl. To co jest opisane jako Request w endpoint`ach to przykładowe dane, które należy wysłać w polu "request".

Lista zamówień

https://www.apaczka.pl/api/v2/orders/

Endpoint wykorzystywany do pobierania listy ostatnich zamówień. Należy podać limit oraz stronę, którą chce się pobrać. Domyślnie jest zwracana pierwsza strona z 10 wynikami. Maksymalny limit zamówień na stronę jest równy 25.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [ 'page' => $page, 'limit' => $limit ] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "orders":[ { "id":"", "service_id":"", "service_name":"", "waybill_number":"", "tracking_url":"", "status":"NEW", "shipments_count":1, "content":"", "comment":"", "receiver":{ "name":"", "contact_person":"", "email":"", "phone":"", "line1":"", "line2":"", "postal_code":"", "city":"", "country_code":"", "foreign_address_id":"" }, "created":"", "delivered":"" } ] } }

W przypadku braku zamówień response zwróci również status 200.

Szczegóły zamówienia

https://www.apaczka.pl/api/v2/order/:order_id/

Endpoint wykorzystywany do pobierania szczegółów zamówienia. Należy podać numer zamówienia :order_id powiązany ze swoim kontem. :order_id jest numerem zamówienia a nie numerem listu przewozowego.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "order":{ "id":"", "supplier":"", "service_id":"", "service_name":"", "waybill_number":"", "pickup":{ "type":"", "date":"", "hours_from":"", "hours_to":"" }, "pickup_number":"", "tracking_url":"", "status":"", "shipments_count":1, "shipments":[ { "shipment_type_code":"", "weight":"", "weight_billable":"", "length":"", "width":"", "height":"", "content":"", "comment":"", "waybill_number":"", "is_nstd":false, "price":"", "price_vat":, "price_gross":"" } ], "content":"", "comment":"", "sender":{ "name":"", "contact_person":"", "email":"", "phone":"", "line1":"", "line2":"", "postal_code":"", "city":"", "country_code":"", "foreign_address_id":"" }, "receiver":{ "name":"", "contact_person":"", "email":"", "phone":"", "line1":"", "line2":"", "postal_code":"", "city":"", "country_code":"", "foreign_address_id":"" }, "created":"", "delivered":"", "price":"", "price_var":, "price_gross":"", "cod":false, "declaration_value":false } } }

List przewozowy

https://www.apaczka.pl/api/v2/waybill/:order_id/

Endpoint wykorzystywany do pobierania etykiety do zamówienia. Należy podać numer zamówienia :order_id powiązany ze swoim kontem. :order_id jest numerem zamówienia a nie numerem listu przewozowego. List przewozowy jest zakodowany w base64.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "waybill":"base64 file", "type":"pdf" } }

Zbiorcze potwierdzenie nadań

https://www.apaczka.pl/api/v2/turn_in/

Endpoint wykorzystywany do pobierania Zbiorczego Potwierdzenia Nadań. Należy podać tablicę :order_id powiązany ze swoim kontem. :order_id jest numerem zamówienia a nie numerem listu przewozowego. Zbiorczego Potwierdzenia Nadań jest zwracane w formacie pdf zakodowany w base64.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( ['order_ids' => [1,2,3]] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "turn_in":"base64 pdf" } }

Godziny odbioru

https://www.apaczka.pl/api/v2/pickup_hours/

Endpoint służący do pobierania godzin odbioru przesyłek przez przewoźników. Należy podać kod pocztowy. Opcjonalne jest podanie id serwisu przez który chcemy nadać przesyłkę. Zwracane są dane na dzień pobierania godzin i następne trzy dni robocze oraz usunięcie indeksu z daty przy podawaniu godzinek.

Prosimy o niepobieranie tych informacji częściej niż raz na 30m.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [ 'postal_code' => $postal_code, 'service_id' => $service_id, 'remove_index' => false ] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "postal_code":"00-001", "hours":{ "2018-09-28":{ "date":"2018-09-28", "services":[ { "service":"", "timefrom":"", "timeto":"" } ] }, "2018-10-01":{ "date":"2018-10-01", "services":[ { "service":"", "timefrom":"", "timeto":"" } ] }, "2018-10-02":{ "date":"2018-10-02", "services":[ { "service":"", "timefrom":"", "timeto":"" } ] }, "2018-10-03":{ "date":"2018-10-03", "services":[ { "service":"", "timefrom":"", "timeto":"" } ] } } } }

Wycena zamówienia

https://www.apaczka.pl/api/v2/order_valuation/

Wycena zamówienia na podstawie przesłanych danych w strukturze order. Endpoint zwraca wycenę dla wszystkich zamówień, które są wstanie zrealizować przesyłkę o zadanych parametrach. Jeśli zostanie podany serwis id to zostanie zwrócona wycena dla tego serwisu. Kwoty są podane w groszach.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [ 'order' => $order // wynikający ze struktury order ] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "price_table":{ "1":{ // id serwisu "price": "", "price_gross": "" } } } }

Wysłanie zamówienia

https://www.apaczka.pl/api/v2/order_send/

Złożenie zamówienia na podstawie przesłanych danych w strukturze order. Parametr is_zebra jest opcjonalny. W przypadku jego nie podania etykieta będzie wygenerowana zgodnie z ustawieniami konta. W przypadku sukcesu endpoint zwraca informacje podstawowe zamówienia.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [ 'order' => $order // wynikający ze struktury order ] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "order":{ "id":"", "service_id":"", "service_name":"", "waybill_number":"", "tracking_url":"", "status":"", "shipments_count":1, "content":"", "comment":"", "receiver":{ "name":"", "contact_person":"", "email":"", "phone":"", "line1":"", "line2":"", "postal_code":"", "city":"", "country_code":"", "foreign_address_id":"" }, "created":"", "delivered":"" } } }

Anulowanie zamówienia

https://www.apaczka.pl/api/v2/cancel_order/:order_id/

Endpoint wykorzystywany do anulowania zamówienia. Należy podać numer zamówienia ':order_id' powiązany ze swoim kontem. ':order_id' nie jest numerem listu przewozowego.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":[ ] }

Struktura serwisów

https://www.apaczka.pl/api/v2/service_structure/

Informacje na temat struktury serwisu.

Prosimy o niepobieranie tych informacji częściej niż raz na 24h.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "services":[ // serwisy { "service_id":"", "name":"", "delivery_time":"", "supplier":"", "domestic":"0", // serwis: 1 - krajowy, 0 - zagraniczny "pickup_courier":"0",// zamówienie kurier: 0 - niedostępne, 1 - dostępne, 2 - wymagane "door_to_door":"1", // serwis drzwi-drzwi: 0 - nie, 1 - tak "door_to_point":"0", // serwis drzwi-punkt "point_to_point":"0",// serwis punkt-drzwi "point_to_door":"1" // serwis punkt-punkt } ], "options":{ // usługi dodatkowe do zamówienia "11":{ "type":"bool", "name":"ROD", "desc":"Zwrot dokumentów" } }, "package_type":{ // typy przesyłek "PACZKA":{ "type":"PACZKA", "desc":"" } }, "points_type":[ // typy punktu odbioru "INPOST", "UPS", "POCZTA" ] } }

Lista punktów nadań

https://www.apaczka.pl/api/v2/points/:type

Endpoint zwraca informacje na temat punktów nadań dla :type podany w service_structure w points_type.

Prosimy o niepobieranie tych informacji częściej niż raz na 24h.

$requestData = [ 'app_id' => $appId, 'request' => json_encode( [] ), 'expires' => $expires, 'signature' => $signature ];

{ "status":200, "message":"", "response":{ "points":{ "1999":{ "type":"", "name":"", "address":{ "line1":"", "line2":"", "state_code":"", "postal_code":"", "country_code":"", "city":"", "longitude":"", "latitude":"" }, "image_url":"", "open_hours":"", "option_cod":false, // dostępna usługa COD "option_send":true, // dostępne nadanie "option_deliver":true, // dostępne doręczenie "additional_info":"", "distance":0, "foreign_address_id":"" } } } }

Struktury

Poniżej znajduje się lista struktury wykorzystywanych w request`ach do Web Api apaczka.pl.

order

Struktura jaka powinna zostać wysłana do Web Serwisu gdzie wymagane są dane dotyczące zamówienia:

$order = json_encode( [ 'service_id' => 0, // endpoint: service_structure 'address' => [ 'sender' => [ 'country_code' => '', // Kod ISO 3166-1 alpha-2 'name' => '', 'line1' => '', 'line2' => '', 'postal_code' => '', 'state_code' => '', 'city' => '', 'is_residential' => 0, // adres prywatny: 0 / 1 'contact_person' => '', 'email' => '', 'phone' => '', 'foreign_address_id' => '' // endpoint: points ], 'receiver' => [ 'country_code' => '', // Kod ISO 3166-1 alpha-2 'name' => '', 'line1' => '', 'line2' => '', 'postal_code' => '', 'state_code' => '', 'city' => '', 'is_residential' => 0, // 0 / 1 'contact_person' => '', 'email' => '', 'phone' => '', 'foreign_address_id' => '' // endpoint: points ] ], 'option' => [ '31' => 1, // powiadomienie sms, '11' => 1, // rod '19' => 1, // dostawa w sobotę, '25' => 1, // dostawa w godzinach, '58' => 1, // ostrożnie ], 'notification' => [ 'new' => [ // Powiadomienia o utworzeniu przesyłki 'isReceiverEmail' => 0, // 0 / 1 'isReceiverSms' => 0, // 0 / 1 'isSenderEmail' => 0 // 0 / 1 ], 'sent' => [ // Powiadomienia o wysłaniu przesyłki 'isReceiverEmail' => 0, // 0 / 1 'isReceiverSms' => 0, // 0 / 1 'isSenderEmail' => 0, // 0 / 1 'isSenderSms' => 0, // 0 / 1 ], 'exception' => [ // Powiadomienia o wyjątku 'isReceiverEmail' => 0, // 0 / 1 'isReceiverSms' => 0, // 0 / 1 'isSenderEmail' => 0, // 0 / 1 'isSenderSms' => 0, // 0 / 1 ], 'delivered' => [ // Powiadomienia o doręczeniu 'isReceiverEmail' => 0, // 0 / 1 'isReceiverSms' => 0, // 0 / 1 'isSenderEmail' => 0, // 0 / 1 'isSenderSms' => 0, // 0 / 1 ] ], 'shipment_value' => 0, // wartość w groszach 'cod' => [ 'amount' => 0, // wartość w groszach 'bankaccount' => '' // tylko cyfry ], 'pickup' => [ 'type' => 'SELF', // endpoint: service_structure 'date' => '', // Y-m-d 'hours_from' => '', // H:i - pickup_hours 'hours_to' => '' // H:i - pickup_hours ], 'shipment' => [ [ 'dimension1' => 10, // długość (length) cm 'dimension2' => 20, // szerokość (width) cm 'dimension3' => 30, // wysokość (height) cm 'weight' => 1, // kg 'is_nstd' => 0, // 0 / 1 'shipment_type_code' => 'PACZKA' // endpoint: service_structure 'customs_data' => [ // dane odprawy celnej (wymagane w przypadku FedEx International) [ 'name' => 'nazwa towaru', 'description' => 'opis towaru', 'made_in' => 'CN', // kraj produkcji ISO 3166-1 alpha-2 'unit_type' => 'PCS', // jednostka 'PCS' - sztuka / 'PKG' - opakowanie 'unit_price' => 1550, // cena/wartość jednostkowa w groszach 'unit_weight' => 1, // waga jednostki 'quantity' => 3 // ilość opakowań/sztuk (w zależności od unit_type) ], ] ], ], 'comment' => '', 'content' => '', 'is_zebra' => 0, // 0 / 1 (wartość opcjonalna, w przypadku nie podania etykieta będzie zgodna z ustawieniami konta) ] );

API SDK

Ostatnia aktualizacja 14.05.2019

Zachęcamy do skorzystania z naszego SDK w celu przeprowadzenia integracji z serwisem apaczka.pl. SDK można pobrać z tego linku.

Changelog