Przejdź do treści głównej

Informacje podstawowe

cairo.API

System cairo.ERP udostępnia klientom funkcjonalności API w oparciu o komunikację JSON poprzez metodę HTTP POST. W odróżnieniu od klasycznej architektury REST, dostęp do funkcji odbywa się poprzez wywoływanie nazwanych operacji, przekazywanych w ciele żądania. Wszystkie dane — zarówno wejściowe, jak i odpowiedzi — przekazywane są w formacie JSON. API umożliwia przesyłanie parametrów (np. identyfikatora sesji) w treści żądania, co eliminuje konieczność ich przekazywania w URL-u lub nagłówkach.

Komunikacja odbywa się z wykorzystaniem jednego punktu końcowego:

POST https://api.example.com/ws/<nazwa metody>

Przykładowe pobranie wersji systemu:

POST /ws/getVersion HTTP/1.1
Host: api.example.com
Content-Type: application/json; charset=utf-8
SOAPAction: "getVersion"

{
  "getVersion": {}
}

Odpowiedź:

{
  "getVersionResponse": {
    "ownum": "123",
    "verFull": "5.645.15127 2024-09-27",
    "version": "dbfd2 5.645.15127 2024-09-27 JSON"
  }
}

Struktura zapytań

Każde zapytanie powinno mieć jednolitą strukturę:

{
  "<nazwaOperacji>": {
    <parametryWejściowe>
  }
}

Np.:

{
  "getProductsInfo": {
    "sessionId": "abc123",
    "productList": {
      "product": [{
          "id": "0006VI"
        }, {
          "reference": "144 666"
      }]
    }
  }
}

Struktura odpowiedzi

Poprawna odpowiedź:

{
  "<nazwa_operacji>Response": {
    <dane_wyjściowe>
  }
}

Np.:

{
  "getVersionResponse": {
    "ownum": "123",
    "verFull": "5.645.15127 2024-09-27",
    "version": "dbfd2 5.645.15127 2024-09-27 JSON"
  }
}

Błędy

W przypadku wystąpienia błędu serwer zwraca odpowiedź HTTP 500 z obiektem error w formacie JSON:

{
  "error": {
    "code": "ERR_SESSION",
    "msg": "Nieprawidłowy identyfikator sesji"
  }
}

Protokół komunikacyjny

Dostęp do API odbywa się poprzez połączenie HTTP(S) do serwera. Wszystkie żądania muszą być wysyłane z nagłówkiem Content-Type: application/json; charset=utf-8. Komunikacja jest bezstanowa — sesje są identyfikowane przez parametry przesyłane w ciele zapytań.

Dostęp do API

Aby uzyskać dostęp, potrzebujesz znać host, z którym będziesz się łączył oraz uzyskać dane dostępowe do API. W tym celu skontaktuj się ze swoim opiekunem.

Wersja językowa

Domyślnie wszystkie komunikaty zwracane są w języku systemu cairo.ERP. Jeśli chcesz, aby odpowiedź przychodziła w konkretnym języku, wyślij właściwy kod języka w polu languageId podczas logowania metodą doLogin.

Zasady pracy z sesjami

Dostęp do metod udostępnianych przez API wymaga przejścia procesu logowania. Logowanie realizowane jest poprzez wywołanie metody doLogin, w której należy podać login i hasło. Metoda doLogin zwraca unikalny identyfikator sesji (sessionId), który należy dołączać do każdego kolejnego wywołania API jako parametr w ciele żądania.

Przykład: logowanie i użycie sesji

Zapytanie logujące:

POST /ws/doLogin HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "doLogin": {
    "userLogin": "test",
    "userPassword": "289dff07669d7a23de0ef88d2f7129e7"
  }
}

Odpowiedź:

{
  "doLoginResponse": {
    "sessionId": "eP3cFozcI3pnyq9wO3Fa7vWg0H7CthI0029736_D"
  }
}

Kolejne zapytanie z użyciem sesji:

{
  "getProductsInfo": {
    "sessionId": "eP3cFozcI3pnyq9wO3Fa7vWg0H7CthI0029736_D",
    "productList": {
      "product": [
        { "id": "0006VI" },
        { "reference": "144 666" }
      ]
    }
  }
}

Cykl życia sesji

  • Sesja pozostaje aktywna przez 10 minut od ostatniej aktywności.
  • Maksymalny czas życia sesji wynosi 3 godziny od momentu zalogowania, niezależnie od aktywności.
  • Po wygaśnięciu sesji serwer zwraca błąd z kodem ERR_SESSION. W takiej sytuacji należy ponownie wywołać metodę doLogin, aby uzyskać nowy identyfikator sesji.
  • Webservice nie wymaga jawnego wylogowania.

Limity i ograniczenia

Korzystanie z API objęte jest następującymi limitami i zasadami:

  • Limit jednoczesnych sesji: domyślnie jedna aplikacja może posiadać maksymalnie 30 aktywnych sesji. Próba utworzenia kolejnej sesji po przekroczeniu limitu zakończy się błędem.
  • Czas życia sesji:
    • 10 minut bezczynności (brak żądań),
    • 3 godziny od momentu zalogowania.
  • Limit połączeń jednoczesnych: każda instalacja systemu posiada określoną liczbę dostępnych jednoczesnych połączeń do API. Wartość tego limitu zależy od konfiguracji środowiska i może być ustalana indywidualnie.
  • Przekroczenie dostępnych połączeń może skutkować odrzuceniem kolejnych żądań do czasu zwolnienia zasobów.
Powrót na górę