Page tree
Skip to end of metadata
Go to start of metadata

Zmiany od wersji 1.7.0:

  1. Wprowadzenie twardej walidacji dla wszystkich parametrów typu Integer, Double, List<Integer>: w przypadku nieprawidłowego formatu bądź nieprawidłowej wartości parametru API zwróci błąd; dotychczas: parametr był ignorowany.
  2. Usunięcie polskich tłumaczeń - w zapytaniu o możliwe funkcję lub możliwej metodzie płatności.
  3. Wprowadzenie maksymalnej wartości parametru per_page wynoszącej 500; dotychczas: bez limitu

Zasób Points reprezentuje lokalizacje, w których dostępne są usługi operatorów logistycznych. Punktami mogą być maszyny samoobsługowe (Paczkomat, Pralniomat) lub oddziały, punkty obsługi klienta. Każda z lokalizacji oferuje określone usługi - lista tych usług zwracana jest w odpowiedzi pod atrybutem functions.

Lokalizacja zasobu:

https://api-shipx-pl.easypack24.net/v1/points

Środowisko testowe
 

Istnieje możliwość przetestowania swojej implementacji na środowisku testowym wystawionym w tym celu pod adresem:

https://sandbox-api-pl-points.easypack24.net/v1/points
Na tej stronie

 

Struktura

Elementy zasobu Points posiadają następujące atrybuty:

AtrybutTypOpis
hrefStringAdres URI do zasobu określonego punktu
nameStringID punktu. Jest to jego unikalna nazwa, np. KRA007 (Dla Paczkomatu)
typeArray

Tablica określająca jakie rodzaje punktów mieszczą się w danej lokalizacji.

Możliwe typy punktów:

  • parcel_locker - Fizyczne paczkomaty i punkty obsługi przesyłek do których można nadać przesyłkę paczkomatową.
  • pop - Punkty obsługi przesyłek.
  • parcel_locker_only - Tylko fizyczne paczkomaty.
  • parcel_locker_superpop - Punkty obsługi przesyłek do których można nadać przesyłkę paczkomatową.
status
StringStatus punktu.
locationObject

Obiekt Location zawierający informacje o położeniu geograficznym: latitude (szerokość) i longitude (długość).

Przykład obiektu Location w formacie JSON:

"latitude": 50.03988,
"longitude": 19.92485
location_type
StringTyp lokalizacji.
location_descriptionStringInformacje dodatkowe o lokalizacji punktu, które mogą ułatwić dotarcie do niego.
location_description_1
StringDodatkowy opis.
location_description_2
StringDodatkowy opis.
distance
IntegerOdległość od punktu relatywnego podanego w wyszukiwaniu. Jeśli punkt relatywny nie został podany, wtedy przyjmuje wartość  null .
opening_hours
StringGodziny otwarcia punktu
addressObject

Obiekt Address zawierający informacje adresowe o punkcie, takie jak: ulica, kod pocztowy, miasto.

Przykład obiektu Address w formacie JSON:

"line1": "Kapelanka 14",
"line2": null
address_details
Object

Dokładne dane adresowe punktu

"city": "Bartoszyce",
"province": "Warmińsko-Mazurskie",
"post_code": "11-200",
"street": null,
"building_number": null,
"flat_number": null
phone_number
StringNumer telefonu punktu
payment_point_descr
StringInformacje dodatkowe o punkcie
functionsArray

Tablica określające jakie fukcje posiada punkt.
Możliwe funkcje:

parcel=Send and collect standard parcel
parcel_send=Standard parcel send
parcel_collect=Standard parcel collect
parcel_reverse_return_send=Standard parcel reverse return to sender
standard_letter_collect=Standard letter collect
standard_letter_send=Standard letter send
allegro_parcel_collect=Allegro parcel collect
allegro_parcel_send=Allegro parcel send
allegro_parcel_reverse_return_send=Allegro parcel return to sender
allegro_letter_collect=Allegro letter collect
allegro_letter_send=Allegro letter send
allegro_letter_reverse_return_send=Allegro letter return to sender
allegro_courier_collect=Allegro courier parcel collect
allegro_courier_send=Allegro courier parcel send
allegro_courier_reverse_return_send=Allegro courier parcel return to sender
standard_courier_collect=Courier parcel collect
standard_courier_send=Courier parcel send
standard_courier_reverse_return_send=Courier parcel return to sender
air_on_airport=Send and collect baggage from machine on airport
air_outside_airport=Send and collect baggage from machine outside of airport
cool_parcel_collect=Reservation collect from cooling machine
laundry=Send and collect laundry
avizo=Avizo collect
partner_idInteger

ID partnera.

is_next
BooleanCzy jest to paczkomat typu NEXT
payment_available
Boolean

Dostępność płatności w danym punkcie.

Istnieje możliwość wystąpienia payment_available=true razem z payment_type=0, oznacza to, że płatność jest dostępna.

payment_typeStringvirtual
virtualIntegerWirtualność punktu
recommended_low_interest_box_machines_listArrayRekomendowane inne punkty w pobliżu


Przykład zasobu Point w formacie JSON:

{  
   "href":"http://api-pl-points.easypack24.net/v1/points/KRA011",
   "name":"KRA011",
   "type":[  
      "parcel_locker"
   ],
   "status":"Operating",
   "location":{  
      "latitude":50.09103,
      "longitude":19.9299
   },
   "location_type":null,
   "location_description":"Stacja paliw Lukoil",
   "location_description_1":"",
   "location_description_2":"LUKOIL",
   "distance":null,
   "opening_hours":null,
   "address":{  
      "line1":"Opolska 9",
      "line2":"31-274 Kraków"
   },
   "address_details":{  
      "city":"Kraków",
      "province":"małopolskie",
      "post_code":"31-274",
      "street":"Opolska",
      "building_number":"9",
      "flat_number":null
   },
   "phone_number":null,
   "payment_point_descr":"Płatność internetowa PayByLink",
   "functions":[  
      "allegro_courier_collect",
      "allegro_courier_reverse_return_send",
      "allegro_courier_send",
      "allegro_letter_send",
      "allegro_parcel_collect",
      "allegro_parcel_reverse_return_send",
      "allegro_parcel_send",
      "parcel",
      "parcel_collect",
      "parcel_reverse_return_send",
      "parcel_send",
      "standard_courier_reverse_return_send",
      "standard_courier_send"
   ],
   "partner_id":0,
   "is_next":false,
   "payment_available":true,
   "payment_type":{  
      "0":"Brak obsługi płatności"
   },
   "virtual":"0",
   "recommended_low_interest_box_machines_list":null
}


Uwierzytelnianie

Dostęp do zasobu nie wymaga uwierzytelnienia. 


Lista punktów

Pobieranie listy punktów.

GET /v1/points

W odpowiedzi serwer zwróci kolekcję z listą punktów.
Kolekcja wspiera stronicowanie, które opisane jest na stronie API Informacje ogólne.

Przykład zapytania

GET https://api-shipx-pl.easypack24.net/v1/points HTTP/1.1
Host: api-shipx-pl.easypack24.net

Odpowiedź

HTTP/1.1 200 OK
Content-Type: application/json

{  
   "href":"https://api-pl-points.easypack24.net/v1/points",
   "count":5363,
   "page":1,
   "per_page":25,
   "total_pages":215,
   "items":[  
      {  
         "href":"http://api-pl-points.easypack24.net/v1/points/ADA01N",
         "name":"ADA01N",
         "type":[  
            "parcel_locker"
         ],
         "status":"Operating",
         "location":{  
            "latitude":51.74455,
            "longitude":22.25847
         },
         "location_type":null,
         "location_description":"Przy sklepie Groszek",
         "location_description_1":null,
         "location_description_2":"Groszek",
         "distance":null,
         "opening_hours":"24/7",
         "address":{  
            "line1":"Kleeberga 5B",
            "line2":"21-412 Adamów"
         },
         "address_details":{  
            "city":"Adamów",
            "province":"lubelskie",
            "post_code":"21-412",
            "street":"Kleeberga",
            "building_number":"5B",
            "flat_number":null
         },
         "phone_number":null,
         "payment_point_descr":"Płatność internetowa PayByLink. Dostępność 24/7",
         "functions":[  
            "allegro_courier_collect",
            "allegro_courier_reverse_return_send",
            "allegro_courier_send",
            "allegro_letter_reverse_return_send",
            "allegro_letter_send",
            "allegro_parcel_collect",
            "allegro_parcel_reverse_return_send",
            "allegro_parcel_send",
            "parcel",
            "parcel_collect",
            "parcel_reverse_return_send",
            "parcel_send",
            "standard_courier_reverse_return_send",
            "standard_courier_send"
         ],
         "partner_id":0,
         "is_next":true,
         "payment_available":true,
         "payment_type":{  
            "0":"Brak obsługi płatności"
         },
         "virtual":"0",
         "recommended_low_interest_box_machines_list":null
      },
      {  
         "href":"http://api-pl-points.easypack24.net/v1/points/ALK01A",
         "name":"ALK01A",
         "type":[  
            "parcel_locker"
         ],
         "status":"Operating",
         "location":{  
            "latitude":52.8684,
            "longitude":18.7031
         },
         "location_type":null,
         "location_description":"Przy biurze usług ubezpieczeniowych",
         "location_description_1":"",
         "location_description_2":"",
         "distance":null,
         "opening_hours":"24/7",
         "address":{  
            "line1":"Słowackiego 131",
            "line2":"87-700 Aleksandrów Kujawski"
         },
         "address_details":{  
            "city":"Aleksandrów Kujawski",
            "province":"kujawsko-pomorskie",
            "post_code":"87-700",
            "street":"Słowackiego",
            "building_number":"131",
            "flat_number":null
        
   ],
   [...]
}


Szczegóły punktu

Pobieranie szczegółów punktu.

GET /v1/points/:nazwa_punktu

W odpowiedzi serwer zwróci szczegóły punktu.

Przykład zapytania

GET https://api-shipx-pl.easypack24.net/v1/points/AAB001 HTTP/1.1
Host: api-shipx-pl.easypack24.net

Odpowiedź

HTTP/1.1 200 OK
Content-Type: application/json
{  
   "href":"http://api-pl-points.easypack24.net/v1/points/ADA01N",
   "name":"ADA01N",
   "type":[  
      "parcel_locker"
   ],
   "status":"Operating",
   "location":{  
      "latitude":51.74455,
      "longitude":22.25847
   },
   "location_type":null,
   "location_description":"Przy sklepie Groszek",
   "location_description_1":null,
   "location_description_2":"Groszek",
   "distance":null,
   "opening_hours":"24/7",
   "address":{  
      "line1":"Kleeberga 5B",
      "line2":"21-412 Adamów"
   },
   "address_details":{  
      "city":"Adamów",
      "province":"lubelskie",
      "post_code":"21-412",
      "street":"Kleeberga",
      "building_number":"5B",
      "flat_number":null
   },
   "phone_number":null,
   "payment_point_descr":"Płatność internetowa PayByLink. Dostępność 24/7",
   "functions":[  
      "allegro_courier_collect",
      "allegro_courier_reverse_return_send",
      "allegro_courier_send",
      "allegro_letter_reverse_return_send",
      "allegro_letter_send",
      "allegro_parcel_collect",
      "allegro_parcel_reverse_return_send",
      "allegro_parcel_send",
      "parcel",
      "parcel_collect",
      "parcel_reverse_return_send",
      "parcel_send",
      "standard_courier_reverse_return_send",
      "standard_courier_send"
   ],
   "partner_id":0,
   "is_next":true,
   "payment_available":true,
   "payment_type":{  
      "0":"Brak obsługi płatności"
   },
   "virtual":"0",
   "recommended_low_interest_box_machines_list":null
}

Kryteria wyszukiwania

ParametrTypOpisPrzykład
nameString
Array
Wyszukuje punkt o podanej nazwie.
Wyszukuje punkty o podanych nazwach.
?name=KRA010
?name=Kra010,ADA01N
typeString
Array

Wyszukuje punkty o podanym typie
Wyszukuje punkty o podanych typach

?type=parcel_locker
?type=parcel_locker,pop
functionsString
Array

Wyszukuje punkty posiadające podaną funkcję.
Wyszukuje punkty posiadające wszystkie wymienione funkcje.

?functions=parcel
?functions=parcel,parcel_send
partner_id

Integer
Array

Wyszukuje punkty o podanym partner_id.
Wyszukuje punkty o podanych partner_id.
?partner_id=1
?partner_id=1,2
is_nextBooleanWyszukuje punkty, które są typu NEXT?is_next=true
payment_available
BooleanFiltrowanie listy punktów po dostępności płatności dla punktu.?payment_available=true
post_codeString
Array
Wyszukuje punkty, które posiadają podany kod pocztowy.
Wyszukuje punkty, które posiadają podane kody pocztowe.
?post_code=11-111
?post_code=11-111,22-222
cityString
Array
Wyszukuje punkty, które posiadają podane miasto.
Wyszukuje punkty, które posiadają podane miasta.

?city=Kraków

?city=Kraków,Warszawa

provinceString
Array
Wyszukuje punkty, które posiadają podane województwo.
Wyszukuje punkty, które posiadają podane województwa.

?province=Małopolska

?province=Małopolska,Śląsk

virtual

Integer
Array

Wyszukuje punkty o podanej wirtualności.
Wyszukuje punkty o podanych wirtualnościach.
?virtual=0
?virtual=1,6
updated_from
Date

Wyszukiwanie punktów wg daty, po której nastąpiła aktualizacja punktu.

Jeśli parametr updated_to nie został podany data nie może być wcześniejsza, niż 3 dni wstecz licząc od aktualnej daty..

?updated_from=2018-04-24
updated_to
Date

Wyszukiwanie punktów wg daty, do której nastąpiła aktualizacja punktu.

Wymaga podania updated_from.

?updated_to=2018-04-26


Wyszukiwanie wg. lokalizacji

relative_pointStringWyszukuje punkty położone najbliżej podanych współrzędnych geograficznych.?relative_point=52.123,19.321
relative_post_codeStringWyszukuje punkty położone najbliżej podanego kodu pocztowego.?relative_post_code=11-111
max_distanceDouble

Określa odległość w metrach od podanego w relative_point lub relative_post_code punktu.

Użycie parametru wymusza sortowanie wg odległości.

Domyślna wartość: 10000 (10km)
Maksymalna wartość: 50000 (50 km).

?relative_point=52.123,19.321&max_distance=10000
limitInteger

Limit zwracanych punktów w przypadku użycia parametrów w relative_point lub relative_post_code.

?limit=10

Sortowanie wyników

nameSortowanie po nazwie punktów.?sort_by=name
distance_to_relative_pointSortowanie wg. odległości od punktu relatywnego (relative_point lub relative_post_code)?sort_by=distance_to_relative_point
statusSortowanie wg. statusu?sort_by=status

Sortowanie może odbywać się w dwóch kierunkach, poprzez użycie parametru sort_order:

ascSortuje punkty rosnąco?sort_order=asc&sort_by=status
descSortuje punkty malejąco?sort_order=desc&sort_by=status


Domyślnie wyniki sortowane są rosnąco (asc) wg nazwy punktów(name).

Stronicowanie

pageOkreśla stronę wyników, która powinna zostać zwrócona.?page=2
per_page

Określa liczbę wyników wyświetlanych na stronie.

Domyślna wartość: 25
Maksymalna wartość:
500

?per_page=100

Filtrowanie wyświetlanych pól

fieldsOkreśla liste atrybutów punktu, która ma zostać wyświetlona na stronie.?fields=name,type
  • No labels