...
API jest interfejsem stateless.
Dostępne środowiska
Środowisko | Endpoint | Konfiguracja |
---|---|---|
TEST | http://test.api.shipx.pl.easypack24.net | Agent: test1agent.inpost.pl |
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.
| ||
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: {} } |
...
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"] } } |
Kluczami obiektu details
są nazwy atrybutów przesłanych metodą POST
lub PUT
, dla których wystąpiły błędy walidacji. Natomiast ich wartości to tablica kluczy błędów, które są prawdziwe dla przesłanej wartości. Poniżej opisana jest lista generycznych kluczy błędów walidacji.
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. |
Info |
---|
Oprócz powyższych błędów walidacji mogą wystąpić inne, które są specyficzne dla określonych zasobów. Szczegółów należy szukać w rozdziałach właściwych dla tych zasobów. |
...