Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
API platformy Ship X jest głównym interfejsem wymiany danych z systemem centralnym. Przy jego użyciu można odczytywać i modyfikować dane.
Dostęp do danych jest chroniony. Mechanizm autoryzacji oparty jest o standard OAuth 2.0.
Zapytania podpisywane są przy użyciu access tokena, na tzw. okaziciela (ang. Bearer Token), tzn. że ktokolwiek użyje prawidłowego tokenu, uzyska dostęp do określonych zasobów przez API.
API jest interfejsem stateless.
Na tej stronie
Table of Contents |
---|
Kody odpowiedzi HTTP
Kody odpowiedzi HTTP, które mogą wystąpić w odpowiedzi od serwera:
Kod HTTP
Opis
200 OK
Odpowiedź prawidłowa.
201 CREATED
Zasób został utworzony.
204 NO CONTENT
Odpowiedź prawidłowa, żadna wartość nie została zwrócona. Spotykane np. podczas usuwania zasobów.
400 BAD REQUEST
Dane przesłane metodą POST
lub PUT
są niepoprawne. W odpowiedzi z serwera znajduje się więcej szczegółów.
401 UNAUTHORIZED
Dostęp do zasobu wymaga autoryzacji.
403 FORBIDDEN
Brak lub zestaw uprawnień jest niewystarczający, aby uzyskać dostęp do określonego zasobu.
404 NOT FOUND
Zasób nie został odnaleziony.
500 SERVER ERROR
Wystąpił błąd po stronie serwera.
Błędy
W przypadku wystąpienia błędu API zwraca obiekt błędu, który zawiera następujące atrybuty:
Atrybut
Typ
Opis
status
Integer
Kod odpowiedzi HTTP. Zobacz tabelę powyżej.
error
String
Klucz błędu, jednoznacznie identyfikujący problem.
message
String
Prosty, łatwy do zrozumienia opis błędu.
Note |
---|
Opis błędu może ulegać zmianie i nie należy opierać na nim warunków w kodzie. |
details
Object
Szczegóły dotyczące błędu, który wystąpił, np. lista błędów walidacji. Może być puste w przypadku błędów, których nie dotyczy.
Przykładowa odpowiedź:
Code Block | ||
---|---|---|
| ||
HTTP/1.1 404 Not Found
{
"status": 404,
"error": "resource_not_found",
"message": "Resource you are looking for are not found",
"details: {}
} |
W przypadku zapytania przesłanego metodą POST
lub PUT
mogą wystąpić błędy walidacji. Szczegóły na ich temat umieszczane są pod atrybutem details
w odpowiedzi:
Code Block | ||
---|---|---|
| ||
HTTP/1.1 400 Bad Request
{
"status": 400,
"error": "validation_failed",
"message": "Data sent by POST or PUT request are not valid. Check details for more info",
"details: {
"name": ["required", "too_short"],
"post_code": ["invalid_format"]
}
} |
Note |
---|
Kluczami obiektu |
Klucze błędów
Poniższa tabela przedstawia klucze błędów, które mogą zostać zwrócone przez serwer, wraz z możliwymi kodami HTTP:
Klucz błędu
Kod HTTP
Opis
resource_not_found
404
Szukany zasób nie został odnaleziony, np. adres URL jest niepoprawny lub zasób nie istnieje.
validation_failed
400
Przy przesyłaniu danych metodą POST
lub PUT
wystąpiły błędy w walidacji. Szczegółowe błędy walidacji zawarte są pod atrybutem details
.
unauthorized
401
Dostęp do zasobu jest niemożliwy, ponieważ zapytanie nie zostało podpisane kluczem access token.
access_forbidden
403
Dostęp do określone zasobu jest zabroniony dla tego zapytania (np. z powodu braku lub niewłaściwego zakresu uprawnień).
Klucze błędów walidacji
Poniższa tabela przedstawia generyczne klucze błędów walidacji, które zwracane są pod atrybutem details
dla odpowiedzi błędu validation_failed
:
Klucz błędu
Opis
required
Podanie wartości jest wymagane.
invalid
Podana wartość jest nieprawidłowa. Szczegóły w dokumentacji opisującej zasób.
too_short
Podana wartość jest zbyt krótka. Szczegóły w dokumentacji opisującej zasób.
too_long
Podana wartość jest zbyt długa. Szczegóły w dokumentacji opisującej zasób.
too_small
Podana wartość jest zbyt mała. Dotyczy głównie wartości liczbowych. Szczegóły w dokumentacji opisującej zasób.
too_big
Podana wartość jest zbyt duża. Dotyczy głównie wartości liczbowych. Szczegóły w dokumentacji opisującej zasób.
invalid_format
Podana wartość ma niepoprawny format, np. gdy w pole numer telefonu zostały wpisane cyfry.
Szczegóły w dokumentacji opisującej zasób.
Skorzystaj z integracji przez API, które:
umożliwia generowanie etykiet, tworzenie wysyłek i zarządzanie rozliczeniami
dostarcza informację o usługach w czasie rzeczywistym, np.: wykaz dostępnych urządzeń Paczkomat, cenniki, statusy przesyłek, informacje o preferowanym przez Klienta automacie Paczkomat
pozwala na nadawanie indywidualnych numerów paczek i tworzenie własnych etykiet.
Właściwe wdrożenie usług InPost na stronie internetowej
Zadbaj o poprawną ekspozycję usług InPost, dzięki czemu:
Kupujący szybko rozpoznają, że dokonując zakupu w Twoim sklepie mogą 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.
Przy prawidłowym zastosowaniu mapy i listy urządzeń Paczkomat – 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.
Poradnik skutecznej implementacji dostaw InPost w koszyku e-commerce
Image AddedZapoznaj się z dedykowanym materiałem wspierającym, dotyczącym poprawnej implementacji usług InPost. Gromadzi on w jednym miejscu informacje w zakresie aktualnego brandingu InPost, wytyczne odnośnie implementacji przyjaznego wyszukiwania automatów Paczkomat i PaczkoPunktów oraz dobre praktyki, warte stosowania przy budowaniu pozytywnego user experience wśród Kupujących online.