Podstawowe informacje o API

REST API

SaleBasis umożliwia integrację z użyciem REST API z wykorzystaniem metod GET, POST, PUT, DELETE. Metoda PATCH nie jest wykorzystywana, jednak niektóre zasoby dostępne poprzez metodę PUT umożliwiają pominięcie niektórych pól, by ich nie edytować – oczywiście odpowiednia informacja znajduje się w dokumentacji. Metody GET i DELETE nie przyjmują parametrów w treści zapytania (body) – przyjmują one parametry tylko w adresie zapytania.

Adres API dla wszystkich zapytań HTTP to https://app.salebasis.eu/api/. Format danych dla API to JSON. Pola z pustą wartością (NULL) nie są ukrywane. W odpowiedzi lub zapytaniu zawsze nadrzędnym jest obiekt JSON – nie będzie to na przykład tablica. Kodowanie znaków to zawsze UTF-8.

Nagłówek Content-Type powinien więc mieć wartość:

Content-Type: application/json

Kody odpowiedzi HTTP

Odpowiedzi poprawne:

  • 200 OK – poprawna odpowiedź serwera
  • 201 CREATED – poprawne utworzenie nowego zasobu
  • 204 NO CONTENT – poprawne,  jednak bez treści odpowiedzi (body)

Odpowiedzi błędne:

  • 400 BAD REQUEST – Błędne zapytanie do serwera. Mogą to być niepoprawne dane JSON, brak danych JSON, brak jakiegoś parametru lub inny powód.
  • 401 UNAUTHORIZED – Brak autoryzacji użytkownika. Nie przesłano nagłówna z tokenem, lub token wygasł.
  • 402 PAYMENT REQUIRED – Konto organizacji nie zostało opłacone – koniec ważności abonamentu lub okresu testowego. Należy dokonać płatności.
  • 403 FORBIDDEN – Użytkownik nie ma uprawnień do podanego zasobu lub do wykonania danej operacji.
  • 404 NOT FOUND – Niepoprawny adres URL zasobu REST API, lub nie znaleziono podanej rzeczy (np towaru czy zamówienia).
  • 405 METHOD NOT ALLOWED – Niedozwolona metoda HTTP.
  • 406 NOT ACCEPTABLE – Niepoprawne dane przekazane przez REST API, lub z jakiegoś powodu nie można wykonać danej operacji.
  • 409 CONFLICT – Wystąpił konflikt, np istnieje już taki kod towaru.
  • 500 INTERNAL SERVER ERROR – Wewnętrzny błąd serwera. Może również wystąpić przy przekazaniu niepoprawnych danych lub w innym przypadku.
  • 503 SERVICE UNAVAILABLE – Błąd związany z zewnętrznym serwerem (przykładowo – błąd komunikacji). Może wystąpić podczas komunikacji ze zintegrowanymi usługami jak Allegro, WooCommerce, czy InPost.

Obsługa błędów

W przypadku wystąpienia błędu zwracana jest odpowiedź JSON zawierająca element error. W tym elemencie znajduje się kod błędu (ten sam co kod odpowiedzi HTTP) oraz wiadomość. Przykładowa odpowiedź błędu:

{
	"error": {
		"code": 404,
		"message": "Nie znaleziono towaru o podanym ID"
	}
}

Język

Aby wybrać język należy przesłać nagłówek Accept-Language, a następnie kod języka. Na przykład:

Accept-Language: pl

Data i czas

Gdy w danym polu występuje sama data – jest ona w formacie:
yyyy-MM-dd
Na przykład: 2022-01-01
Format daty i czasu (taki zawsze występuje w odpowiedzi):
yyyy-MM-dd’T’HH:mm:ss.SSS’Z’
Na przykład: 2022-01-01T10:15:44.000Z
W zapytaniu możliwe jest też przekazanie daty bez milisekund, zostaną wtedy one ustawione na 0:
yyyy-MM-dd’T’HH:mm:ss’Z’
Na przykład: 2022-01-01T10:15:44Z

Wszystkie daty i czas są w strefie czasowej UTC +00:00 (czas uniwersalny).