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.

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ść 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:

 

    function getSignature( $string, getSignature, $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:

    function getSignature( $string, getSignature, $key ) {
    return hash_hmac( 'sha256', $string, $key );
}

{
   "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. 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

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

Response

{
   "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.

Request

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

Response

{
   "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 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

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

Request

   {
   "status":200,
   "message": "",
   "response":{
      "waybill":"base64 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.

Request

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

Request

   {
   "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 indexu z daty przy podawaniu godzinek.

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

Request

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

Request

{
   "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.

 

Request

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

Request

{
   "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.

Request

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

Request

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

Request

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

Request

{
   "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.

Request

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

Request

{
   "status": 200,
   "message":"",
   "response":{
   "services":[  // serwisy
         {
             "service_id": "",
             "name": "",
             "delivery_time": "",
             "supplier": ""
         }
      ],
      "options":{ // usługi dodatkowe do zamówienia
         "11":{
            "type":"bool",
            "name":"ROD",
            "desc":"Zwrot dokument\u00f3w"
         }
      },
     "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.

 

Request

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

Request

{
   "status": 200,
   "message":"",
   "response":{
    "points":{
         "1999":{
            "type":"",
            "name":"",
            "address":{
               "line1":"",
               "line2":"",
               "state_code":"",
               "postal_code":"",
               "country_code":"",
               "city":"",
               "longitude":"",
               "latitude":""
            },
            "image_url":"",
            "open_hours":"",
            "additional_info":"",
            "distance": 0,
            "foreign_address_id":""
         }
      }
   }
}		

 Struktury

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

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

order

Struktura jaka powina 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
				'name'               => 	'',
				'line1'              => 	'',
				'line2'              => 	'',
				'postal_code'        => 	'',
				'city'               => 	'',
				'is_residential'     => 	0, 	// 0 / 1
				'contact_person'     => 	'',
				'email'              => 	'',
				'phone'              => 	'',
				'foreign_address_id' => 	'' 	// enpoint: points
		],
		'receiver' => [
			'country_code'        => '' , // Kod ISO 3166 
			'name'                => '' ,
			'line1'               => '' ,
			'line2'               => '' ,
			'postal_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 
        ],
        'exception' => [ // Powiadomienia o wyjątku
	        'isReceiverEmail'  => 0 // 0 / 1 
	        'isReceiverSms'    => 0 // 0 / 1
	        'isSenderEmail'    => 0 // 0 / 1 
        ],
         'delivered' => [  // Powiadomienia o doręczeniu
	        'isReceiverEmail'  => 0 // 0 / 1 
	        'isReceiverSms'    => 0 // 0 / 1
	        'isSenderEmail'    => 0 // 0 / 1 
        ]
    ],
	'shipment_value'      =>  0, // wartość w groszach 
        ]
		'cod'         => [
		'amount'      => 0, >, // // wartość w groszach
		'bankaccount' => ''
	],
		'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, // cm
				'dimension2'         => 20, // cm
				'dimension3'         => 30, // cm
				'weight'             => 1, // kg
			    	'is_nstd'            => 0, // 0 / 1
				'shipment_type_code' => 	'PACZKA' // endpoint: service_structure
		]
	],
		'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

1.0.0 – 2019-09-25

  • Dodanie notyfikacji dla przesyłki
  • Poprawki dot. obsługi etykiet

Adres kontaktowy

Informujemy, że Administratorem danych osobowych jest R2G Polska Sp. z o.o. z siedzibą w Warszawie (02-797), ul. Klimczaka 1. Dane będą przetwarzane w celu wykonania postanowień regulaminu oraz marketingu własnego. Każdy ma prawo wglądu do treści danych oraz ich poprawiania. Dane są podane dobrowolnie, lecz są warunkiem świadczenia usługi.

Copyright @ 2020 apaczka.pl

Adres kontaktowy

Informujemy, że Administratorem danych osobowych jest R2G Polska Sp. z o.o. z siedzibą w Warszawie (02-797), ul. Klimczaka 1. Dane będą przetwarzane w celu wykonania postanowień regulaminu oraz marketingu własnego. Każdy ma prawo wglądu do treści danych oraz ich poprawiania. Dane są podane dobrowolnie, lecz są warunkiem świadczenia usługi.

Copyright @ 2020 apaczka.pl.

Adres kontaktowy

Informujemy, że Administratorem danych osobowych jest R2G Polska Sp. z o.o. z siedzibą w Warszawie (02-797), ul. Klimczaka 1. Dane będą przetwarzane w celu wykonania postanowień regulaminu oraz marketingu własnego. Każdy ma prawo wglądu do treści danych oraz ich poprawiania. Dane są podane dobrowolnie, lecz są warunkiem świadczenia usługi.

Copyright @ 2020 apaczka.pl.