lang_en lang_pl
Dokumentacja Web API ver. 2

Wprowadzenie

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

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łakł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:

  • 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ść requestu 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 endpointu, danych w request oraz daty wygaśnięcia ważności requestu używając metody HMAC z wykorzystaniem algorytmu SHA256 podając jako klucz App Secret. Przykładowy kod do generowania signature w PHP:

Response

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

  • 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. requestu. Najczęście występuje w przypadku błędu.
  • response - zwracane dane. Opis zwracanych danych został opisany dla każdego endpointu.
Enpoints

Poniżej znajduje się lista enpointów do wykorzystania w requestach do Web Api apaczka.pl. To co jest opisane jako Request w endpointach 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.

Request
Response

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.

Request
Response
List przewozowy

https://www.apaczka.pl/api/v2/waybill/: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. List przewozowy jest zwracany w formacie pdf zakodowany w base64.

Request
Response
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.

Request
Response
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 indexu z daty przy podawaniu godzinek.

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

Request
Response
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.

Request
Response
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.

Request
Response
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 jest numerem zamówienia a nie numerem listu przewozowego.

Request
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.

Request
Response
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.

Request
Response
Struktury

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

order

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

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
1.0.0 - 2019-09-25
  • Dodanie notyfikacji dla przesyłki
  • Poprawki dot. obsługi etykiet