[1.3.0] API Informacje ogólne
Środowisko produkcyjne
Adres środowiska produkcyjnego https://api-shipx-pl.easypack24.net
Generowanie dostępu
Pobierz poradnik wyjaśniający jak szybko we własnym zakresie utworzyć dostęp do API ShipX, Instrukcja konfiguracji konta API.
Środowisko testowe
Adres środowiska testowego: https://sandbox-api-shipx-pl.easypack24.net
Adres środowiska testowego Managera Paczek: https://sandbox-manager.paczkomaty.pl/
Generowanie dostępu
https://sandbox-manager.paczkomaty.pl/ > zakładka Moje konto > API.
Aby wygenerować Token i ID organizacji należy uzupełnić wszystkie dane, łącznie z danymi do faktury w zakładce Moje konto > Dane. Do utworzenia przesyłki Paczkomat® niezbędne są środki na koncie, konto doładujesz wirtualnie w zakładce Płatności.
Kolekcja zapytań oraz profile środowisk
Poniżej udostępniamy przykładową kolekcję oraz profile środowisk dla aplikacji Postman. W celu uruchomienia należy pobrać pliki i zaimportować je.
Kolekcja zapytań |
|
Środowisko produkcyjne |
|
Środowisko sandbox |
|
Nagłówki zapytania
Podczas wykonywania zapytania można określić następujące nagłówki
Nagłowek | Opis |
---|---|
| Nagłówek autoryzacji, w którym należy przesyłać wszelkie dane związane z autoryzacją. Szczegóły zostały opisane w rozdziale Autoryzacja. |
| Nagłówek ten pozwala na określenie nazwy klienta/platformy i/lub innych informacji z nim związanych. |
| Nagłówek ten pozwala na określenie wersji klienta/platformy, który wykonuje zapytania. Jego zawartość nie wpływa na funkcjonowanie API. |
| Nagłówek ten pozwala na określenie identyfikator zapytania. Jest on przydatny przy debugowaniu błędów i problemów, które mogą zdarzyć się przy integracji z API. Jego podanie nie wpływa na funkcjonowanie API. |
| Nagłówek pozwala na zmianę formatu komunikatów błędów. Dostępne:
|
Nagłówki odpowiedzi
W odpowiedzi serwer zwraca następujące nagłówki
Nagłówek | Opis |
---|---|
| Identyfikator zapytania. Przydatny podczas debugowania problemów z API. |
Kolekcje
Atrybuty kolekcji
Atrybut | Typ | Opis |
---|---|---|
| String | Absolutny adres URL do kolekcji. |
| Integer | Łączna ilość elementów kolekcji. |
| Integer | Aktualna strona wyników kolekcji. |
| Integer | Ilość wyników (na stronę) zwracanych w odpowiedzi. |
| Array | Elementy kolekcji. |
Przykład kolekcji w formacie JSON:
{
"href": "https://api-pl-shipx.easypack24.net/v1/points",
"count": 1024,
"page": 10,
"per_page": 100,
"items": [
{
"href": "https://api-shipx-pl.easypack24.net/v1/points/KRA010",
"id": "KRA010",
... other resource's params ...
}
]
}
Stronicowanie
Kolekcje wspierają stronicowanie (chyba że zostało zaznaczone inaczej w dokumentacji właściwej dla zasobu).
Przewijanie po kolejnych stronach kolekcji obywa się poprzez przekazanie w zapytaniu parametrów (page
) i/lub (page_page
). Przykład zapytania:
GET /v1/points?page=10 HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Autoryzacja
Wszystkie zapytania wysyłane do serwera wymagają podania prawidłowego i ważnego access tokenu, który należy do określonego właściciela (owner) organizacji.
Access token należy przekazać w nagłówku Authorization
.
ID organizacji należy przekazać w parametrze zapytania:
GET /v1/organizations/:id
Przykład zapytania
GET /v1/organizations/1 HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer W-TYM-MIEJSCU-NALEZY-UMIESCIC-TOKEN
Odpowiedź
HTTP/1.1 200 OK
Content-Type: application/json
{
"href": "https://api.shipx.pl.easypack24.net/v1/organizations/34",
"id": 34,
"owner_id": 1,
"tax_id": "3973902075",
"name": "Random org name39739020755741",
"created_at": "2016-10-04T10:36:49.631+02:00",
"updated_at": "2016-10-04T10:36:49.631+02:00",
"services": [
"inpost_locker_standard",
"inpost_courier_standard"
],
"address": {
"id": 808,
"line1": null,
"line2": null,
"street": "Ulica jakaś39739020755741",
"building_number": "Budynek39739020755741",
"city": "Szczecin39739020755741",
"post_code": "22-100",
"country_code": "PL"
}
} |
Błędy
Przykład błędu
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"status": 400,
"error": "invalid_parameter",
"description": "Passed unsupported value (value of the parameter here) to parameter (parameter name)",
"details": null
}
Poniżej znajduje się lista kluczy błędów, które mogą wystąpić.
Klucz | Opis |
---|---|
| Szukany zasób nie został odnaleziony. |
| Dostęp do określonego zasobu jest zabroniony. |
| Przekazano niepoprawną wartość dla określonego parametru w URI. Szczegóły dostępne pod kluczem |
| Błąd walidacji. Dane przesłane w ciele zapytania metodą |
| Zakupienie oferty jest niemożliwe, ponieważ upłynął termin jej ważności. |
Przykład błędu validation_failed
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"status": 400,
"error": "validation_failed",
"description": "Some of data sent in payload are invalid. Check details for more information.",
"details": {
"email": ["invalid"]
}
}
Obiekt details
zawiera w tym przypadku kolekcję, w której klucze odpowiadają nazwom przesłanych w ciele zapytania parametrów, natomiast wartości to tablica z kluczami określającymi jakie błędy walidacji wystąpiły dla określonego parametru.
Możliwe błędy walidacji to:
Błąd walidacji | Opis |
---|---|
| Wartość dla określonego parametru jest wymagana. |
| Ilość znaków zbyt mała. Sprawdź szczegóły w dokumentacji określonego zasobu. |
| Ilość znaków zbyt duża. Sprawdź szczegóły w dokumentacji określonego zasobu. |
| Wprowadzona wartość powinna być liczbą. |
| Wprowadzona wartość powinna być liczbą całkowitą. |
| Wprowadzona wartość jest niepoprawna. Sprawdź szczegóły w dokumentacji określonego zasobu. |