Skip to main content

Basic information (EN)

cairo.API

SystemThe cairo.ERP udostępniasystem klientomprovides funkcjonalnościits clients with API wfunctionality oparciubased o komunikacjęon JSON poprzezcommunication metodęover the HTTP POST.method. WUnlike odróżnieniuclassical odREST klasycznejarchitecture, architekturyaccess REST,to dostępfunctions dois funkcjidone odbywaby sięinvoking poprzeznamed wywoływanieoperations nazwanychpassed operacji,in przekazywanychthe wrequest cielebody. żądania.All Wszystkie danedata — zarównoboth wejściowe,input jakand i odpowiedziresponse — przekazywaneis sątransferred win formacieJSON JSON.format.

The API umożliwiaallows przesyłanie parametrówparameters (np.such identyfikatoraas sesji)session widentifiers) treścito żądania,be cosent eliminujein koniecznośćthe ichrequest przekazywaniabody, weliminating URL-uthe lubneed nagłówkach.to pass them in the URL or headers.

KomunikacjaAll odbywacommunication sięis zdone wykorzystaniemthrough jednegoa punktusingle końcowego:endpoint:

POST https://api.example.com/ws/<nazwamethod metodyname>

PrzykładoweExample: pobranieretrieving wersjisystem systemu:version:

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

{
  "getVersion": {}
}

Odpowiedź:Response:

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

StrukturaRequest zapytaństructure

KażdeEvery zapytanierequest powinnoshould miećfollow jednolitąa strukturę:consistent structure:

{
  "<nazwaOperacjioperationName>": {
    <parametryWejścioweinputParameters>
  }
}

Np.:Example:

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

StrukturaResponse odpowiedzistructure

PoprawnaA odpowiedź:valid response:

{
  "<nazwa_operacjioperationName>Response": {
    <dane_wyjścioweoutputData>
  }
}

Np.:Example:

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

BłędyError handling

WIn przypadkucase wystąpieniaof błęduan serwererror, zwracathe odpowiedźserver returns an HTTP 500 zresponse obiektemcontaining an error wobject formaciein JSON:JSON format:

{
  "error": {
    "code": "ERR_SESSION",
    "msg": "NieprawidłowyInvalid identyfikatorsession sesji"identifier"
  }
}

ProtokółCommunication komunikacyjnyprotocol

DostępAccess doto the API odbywais sięprovided poprzezvia połączeniean HTTP(S) doconnection serwera.to Wszystkiethe żądaniaserver. musząAll byćrequests wysyłanemust zinclude nagłówkiemthe header: Content-Type: application/json; charset=utf-8. KomunikacjaCommunication jestis bezstanowastateless — sesjesessions sąare identyfikowaneidentified przezvia parametryparameters przesyłanepassed win cielethe zapytań.request body.

DostępAPI do APIaccess

AbyTo uzyskaćaccess dostęp,the potrzebujeszAPI, znaćyou host,need zto którymknow będzieszthe siętarget łączyłhost orazand uzyskaćobtain daneAPI dostępowecredentials. doPlease API.contact Wyour tymaccount celumanager skontaktujto sięobtain zeaccess swoim opiekunem.data.

WersjaLanguage językowaversion

DomyślnieBy wszystkiedefault, komunikatyall zwracanemessages sąreturned wfrom językuthe systemuAPI are in the language configured in the cairo.ERP.ERP Jeślisystem. chcesz,To abyreceive odpowiedźresponses przychodziłin a wspecific konkretnymlanguage, języku,include wyślijthe właściwy kod języka w poluappropriate languageId podczasduring 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. Metodathe doLogin zwracamethod unikalnycall.

identyfikator

Session sesjihandling

Accessing API methods requires a successful login. Authentication is performed via the doLogin method, which requires a login and an MD5-encoded password. The doLogin method returns a unique session key (sessionId), którywhich należymust dołączaćbe doincluded każdegoin kolejnegoevery wywołaniasubsequent API jako parametr w ciele żądania.request.

Przykład:Example: logowanielogin iand użyciesession sesji
usage

ZapytanieLogin logujące:request:

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

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

Odpowiedź:Response:

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

KolejneSubsequent zapytanierequest zusing użyciem sesji:session:

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

CyklSession życia sesjilifecycle

  • SesjaA pozostajesession aktywnaremains przezactive for 10 minutminutes odof ostatniej aktywnościinactivity.
  • MaksymalnyThe czasmaximum życialifetime sesjiof wynosia session is 3 godzinyhours odfrom momentu zalogowanialogin, niezależnieregardless odof aktywności.activity.
  • PoAfter wygaśnięciuexpiration, sesjithe serwerserver zwracareturns błąderror z kodemcode ERR_SESSION. WIn takiejsuch sytuacjicases, należythe ponowniedoLogin wywołaćmethod metodęmust doLogin,be abycalled uzyskaćagain nowyto identyfikatorobtain sesji.a new session key.
  • WebserviceExplicit nielogout wymagais jawnegonot wylogowania.required.

LimityLimits iand ograniczeniarestrictions

Korzystanie zThe API objęteis jestsubject następującymito limitamithe ifollowing zasadami:limits and constraints:

  • LimitConcurrent jednoczesnych sesjisessions: domyślnieBy jednadefault, aplikacjaa możesingle posiadaćapplication maksymalniemay have up to 30 aktywnychactive sessions. sesji.Attempts Próbato utworzeniacreate kolejnejadditional sesjisessions pobeyond przekroczeniuthis limitulimit zakończywill sięresult błędem.in an error.
  • CzasSession życia sesjitimeout:
    • 10 minutminutes bezczynnościof (brak żądań),inactivity,
    • 3 godzinyhours odfrom momentulogin zalogowania.(absolute timeout).
  • LimitConcurrent połączeń jednoczesnychconnections: każdaEach instalacjasystem systemuinstallation posiadahas określonąa liczbęlimit dostępnychon jednoczesnychthe połączeńnumber doof API.concurrent WartośćAPI tegoconnections. limituThe zależyvalue odof konfiguracjithis środowiskalimit idepends możeon byćthe ustalanasystem indywidualnie.configuration and may be set individually.
  • PrzekroczenieExceeding dostępnychavailable połączeńconnections możemay skutkowaćresult odrzuceniemin kolejnychrequests żądańbeing dorejected czasuuntil zwolnieniaresources zasobów.
    are released.

PrzykładPHP użycia w języku PHPexample

PoniższyThe przykładfollowing pokazuje,example jakdemonstrates whow prostyto sposóbeasily zintegrowaćintegrate sięwith zcairo.API using PHP. The ws_call()function serves as the main interface for WebService communication. It automatically handles session management, login, and session renewal in the event of an ERR_SESSION error.

Thanks to this, you can call any API platformymethod XYZwithout przymanually użyciumanaging językasession PHP.state Funkcja— just call ws_call() stanowiwith głównythe interfejsmethod doname komunikacjiand z WebService, automatycznie obsługując proces logowania, zarządzanie sesją oraz automatyczne ponowne logowanie w przypadku wygaśnięcia sesji (błąd ERR_SESSION).

Dzięki temu można wywoływać dowolne metody API bez konieczności ręcznego zarządzania cyklem życia sesji – wystarczy jedno wywołanie funkcji ws_call() z nazwą metody oraz parametrami.parameters.

<?php

function ws_call($method, $params = [])
{
    static $sessionId = null;
    static $host = 'http://127.0.0.1:7888/';
    static $credentials = [
        'userLogin'    => 'test',
        'userPassword' => '289dff07669d7a23de0ef88d2f7129e7', // MD5 zhash hasłaof password
    ];

    // WewnętrznaInternal funkcjarequest wykonująca właściwe żądanie HTTPfunction
    $call = function($method, $params) use ($host) {
        $request = [$method => $params];
        $requestStr = json_encode($request);
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL            => $host,
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => $requestStr,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER         => true,
            CURLOPT_HTTPHEADER     => [
                'Content-Type: application/json',
                'Accept: application/json',
            ]
        ]);

        $responseStr = curl_exec($ch);
        $error       = curl_error($ch);
        $headersSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        curl_close($ch);

        if ($error) {
            echo "CURL ERROR: $error\n";
            return null;
        }

        $responseBody = substr($responseStr, $headersSize);
        $response = json_decode($responseBody, true);

        echo "REQUEST:\n$requestStr\n";
        echo "RESPONSE:\n$responseBody\n";

        return $response;
    };

    // LogowanieLogin przyif brakuno aktywnejsession sesjiyet
    if ($sessionId === null && $method !== 'doLogin') {
        $loginResult = ws_call('doLogin', $credentials);
        if (!isset($loginResult['doLoginResponse']['sessionId'])) {
            echo "AutoryzacjaAuthentication nie powiodła się.failed.\n";
            return null;
        }
        $sessionId = $loginResult['doLoginResponse']['sessionId'];
    }

    // DołączenieAdd sesjisessionId doto parametrówparams
    if ($method !== 'doLogin') {
        $params['sessionId'] = $sessionId;
    }

    // WywołaniePerform metodyrequest
    $result = $call($method, $params);

    // ObsługaHandle wygasłejsession sesji i ponowienie logowaniaexpiration
    if (isset($result['error']['code']) && $result['error']['code'] === 'ERR_SESSION') {
        echo "SesjaSession wygasła,expired, ponawiamretrying logowanie.login...\n";
        $sessionId = null;
        return ws_call($method, $params); // ponowneretry wywołanie poafter re-loginielogin
    }

    return $result;
}

// ==========================
// PrzykładExample użycia metodyusage: getProductsInfo
$productList = [
    'product' => [
        ['id' => '0006VI'],
        ['reference' => '144 666']
    ]
];

$response = ws_call('getProductsInfo', ['productList' => $productList]);

if ($response) {
    print_r($response);
} else {
    echo "WywołanieRequest nie powiodło się.failed.\n";
}

 

Back to top