[1.16.5] Zasób Points

Drogi Kliencie,

Z myślą o Tobie oraz Twoich Klientach przygotowaliśmy dedykowany materiał wspierający, dotyczący poprawnej implementacji usług InPost. Syntetyzuje on informacje w zakresie aktualnego brandingu InPost, wytyczne odnośnie implementacji przyjaznego wyszukiwania Paczkomatów i PaczkoPunktów oraz dobre praktyki, warte stosowania przy budowaniu pozytywnego user experience wśród Kupujących online.

  • Aż 70% Kupujących w sieci[1] deklaruje, że nie boi się powierzyć InPost żadnej przesyłki, a 71%[2] twierdzi, że jesteśmy marką idącą z duchem czasu – stosując aktualny branding, który Kupujący znają już również z innych kanałów, pozwalasz im szybko zorientować się, że dokonując zakupu za pośrednictwem Państwa platformy mogą jednocześnie skorzystać z dostarczenia zamówienia przez firmę, której usług poszukują i do której mają zaufanie, co bezpośrednio przyczynia się do decyzji zakupowych Klientów.
  • Dzięki prawidłowemu zastosowaniu mapy i listy Paczkomatów – Geowidget – pomagasz swoim Klientom szybko wyszukać pożądane przez nich miejsce dostawy zamówienia, skupiając ich uwagę na tym zadaniu, unikając rozproszeń i zagubienia się w procesie zakupowym. Zapewni to też Twoim Klientom dostęp do aktualnych informacji dotyczących punktu odbioru takich jak: możliwe formy płatności, opis oraz zdjęcie lokalizacji, czy godziny jej dostępności. Jednocześnie zdejmie to z Ciebie obowiązek bieżącego aktualizowania specyfiki każdego z punktów – bazowanie na rozwiązaniu Geowidget daje bieżący dostęp do tych informacji.


Zachęcamy Cię do zapoznania się z „Poradnikiem implementacji dostaw InPost w koszyku e-commerce” znajduje się na stronie Poradnik skutecznej implementacji dostaw InPost w koszyku e-commerce



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


Na tej stronie

 

Struktura

Zasób Point posiada następujące atrybuty:

AtrybutTypOpis

name 

StringID 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 funkcje posiada punkt. Możliwe funkcje:

IdentyfikatorOpis funkcji
parcelSend and collect standard parcel 
parcel_sendStandard parcel send 
parcel_collectStandard parcel collect 
parcel_reverse_return_sendStandard parcel reverse return to sender 
standard_letter_collectStandard letter collect 
standard_letter_sendStandard letter send 
allegro_parcel_collectAllegro parcel collect 
allegro_parcel_sendAllegro parcel send 
allegro_parcel_reverse_return_sendAllegro parcel return to sender 
allegro_letter_collectAllegro letter collect 
allegro_letter_sendAllegro letter send 
allegro_letter_reverse_return_sendAllegro letter return to sender 
allegro_courier_collectAllegro courier parcel collect 
allegro_courier_sendAllegro courier parcel send 
allegro_courier_reverse_return_sendAllegro courier parcel return to sender 
standard_courier_collectCourier parcel collect 
standard_courier_sendCourier parcel send 
standard_courier_reverse_return_sendCourier parcel return to sender 
air_on_airportSend and collect baggage from machine on airport 
air_outside_airportSend and collect baggage from machine outside of airport 
cool_parcel_collectReservation collect from cooling machine 
laundrySend and collect laundry 
avizoAvizo 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_type Stringvirtual
virtual IntegerWirtualność punktu
recommended_low_interest_box_machines_list ArrayRekomendowane inne punkty w pobliżu
location_247 BooleanCzy paczkomat dostępny jest 24/7
easy_access_zoneBooleanCzy paczkomat posiada strefę ułatwionego dostępu

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,
   "easy_access_zone": true
}

Uwierzytelnianie

Dostęp do zasobu nie wymaga uwierzytelnienia. 

Lista punktów

Pobieranie listy punktów. Kolekcja wspiera stronicowanie, które opisane jest na stronie Informacje ogólne.

GET /v1/points

Przykład zapytania

curl -X GET https://api-shipx-pl.easypack24.net/v1/points -H 'Content-Type: application/json'

Odpowiedź

{ 
  "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",
		"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,
      "easy_access_zone": true
    },
    {...},
    {...},
  ]
}



Szczegóły punktu

Pobieranie szczegółów punktu.

GET /v1/points/:point_name

Przykład zapytania

curl -X GET https://api-shipx-pl.easypack24.net/v1/points/AAB001 -H 'Content-Type: application/json'

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,
   "easy_access_zone": true
}

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_point StringWyszukuje punkty położone najbliżej podanych współrzędnych geograficznych.?relative_point=52.123,19.321
relative_post_code StringWyszukuje punkty położone najbliżej podanego kodu pocztowego.?relative_post_code=11-111
max_distance Double

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
limit Integer

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

?limit=10

Sortowanie wyników

name Sortowanie po nazwie punktów.?sort_by=name

distance_to_relative_point

Sortowanie 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. Domyślnie wyniki sortowane są rosnąco (asc) wg nazwy punktów(name).

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

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 listę atrybutów punktu, która ma zostać wyświetlona na stronie.?fields=name,type