Dokumentacja API SHIPX

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.

Kody odpowiedzi HTTP

Kody odpowiedzi HTTP, które mogą wystąpić w odpowiedzi od serwera:

Błędy

W przypadku wystąpienia błędu, API zwraca obiekt błędu, który zawiera następujące atrybuty:

Przykładowa odpowiedź:

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:

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:

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: