API dla Twojej aplikacji web-systems.pro

Dostęp do interfejsu API >Web Systems Pro< i zainstalowanych w nim aplikacji odbywa się za pośrednictwem pliku api.php.

Autoryzacja oparta jest na protokole OAuth 2.0:

1. Otrzymujemy Token autoryzacji - klucz dostępu. W żądaniu otrzymania tokena wyświetlamy identyfikatory aplikacji, do których API chcesz uzyskać dostęp.
2. Korzystając z otrzymanego tokena, uzyskujemy dostęp do metod API tych aplikacji. Podczas pracy z metodami API uwzględniane są uprawnienia użytkownika, dla którego token został wydany.

Teraz więcej na ten temat.

1. Uzyskanie tokena autoryzacji

Używana jest nieco zmodyfikowana i uproszczona wersja protokołu OAuth 2.0.

Żądanie otrzymania tokena wysyła użytkownika na specjalną stronę autoryzacji >Web Systems Pro<. Na tej stronie użytkownik loguje się za pomocą swojego loginu i hasła, które są używane do logowania się do backendu >Web Systems Pro<. Login i hasło użytkownik wprowadza dokładnie na stronie z zainstalowanym frameworkiem, a nie w aplikacji klienckiej, która próbuje uzyskać token.

Po przejściu autoryzacji użytkownik zezwala lub odmawia dostępu do interfejsu API we własnym imieniu. Jeśli dostęp jest dozwolony, Token jest wydawany. 

Przykład tokena: b936356100e3883cabf59abed991d03d.

Czas życia tokena jest nieograniczony.

Token jest wydawany tylko wtedy, gdy zezwolisz na dostęp do interfejsu API. Schemat żądania dostępu z aplikacji jest następujący:

A. Aplikacje serwerowe

Przekierowanie użytkowników w celu potwierdzenia praw dostępu do

http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=code&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

Jeśli użytkownik potwierdzi dostęp, przekierować z powrotem na adres
REDIRECT_URL?code=CODE

w przeciwnym razie - na
REDIRECT_URL?error=access_denied

Serwer wykonuje POST-żądanie z polami

— code: CODE,
— client_id: CLIENT_ID,
— grant_type: 'authorization_code'

pod adresem

https://ACCOUNT_URL/api.php/token?redirect_uri=REDIRECT_URI&format=FORMAT

Odpowiedź może być w formacie JSON (domyślnie) lub XML (&format=XML).

{"access_token": ACCESS_TOKEN}

lub

<response>
    <access_token>ACCESS_TOKEN</access_token>
</response>

B. Aplikacje klienckie

Przekierowanie użytkowników w celu potwierdzenia praw dostępu do

https://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=token&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

Jeśli użytkownik potwierdzi dostęp, przekierować z powrotem na adres

REDIRECT_URL#access_token=ACCESS_TOKEN

w przeciwnym razie - na

REDIRECT_URL#error=access_denied

Objaśnienia do zmiennych

ACCOUNT_URL — Adres URL folderu głównego instalacji frameworka >Web Systems Pro<

CLIENT_ID — unikalny identyfikator aplikacji, na przykład, XYZCompanyShopImportApp; w przypadku aplikacji internetowych zaleca się określenie domeny, aby uniknąć potencjalnych konfliktów; identyfikator aplikacji programista wymyśla według własnego uznania

CLIENT_NAME — nazwa aplikacji, która zostanie wyświetlona na stronie żądania dostępu

SCOPE — aplikacje, do których potrzebny jest dostęp, wymienione przecinkami, na przykład, scope=shop,photos,blog

REDIRECT_URI — Adres URL, na który użytkownik zostanie przekierowany po zaakceptowaniu lub odmowie przyjęcia przyznania dostępu do danych aplikacji

CODE — jednorazowy kod wymagany do otrzymania tokena; ważny przez 3 minuty

FORMAT — opcjonalny parametr wskazujący format wymiany informacji; możliwe opcje wartości to xml lub json; jeśli parametr nie jest określony, domyślnie jest używany json

2. Żądania do API

Format URL

https://ACCOUNT_URL/api.php/<strong>APP_ID.METHOD</strong>?<strong>PARAMS</strong>&access_token=<strong>ACCESS_TOKEN</strong>&format=<strong>FORMAT</strong>

Przykład

https://mydomain.com/api.php/<strong>shop.product.getInfo</strong>?<strong>id=4</strong>&access_token=<strong>ACCESS_TOKEN</strong>&format=<strong>xml</strong>

Alternatywny format

https://ACCOUNT_URL/api.php?app=<strong>APP_ID</strong>&method=<strong>METHOD</strong>&<strong>PARAMS</strong>&access_token=<strong>ACCESS_TOKEN</strong>&format=<strong>FORMAT</strong>

Przykład

https://mydomain.com/api.php?app=<strong>shop</strong>&method=<strong>product.getInfo</strong>&<strong>id=4</strong>&access_token=<strong>ACCESS_TOKEN</strong>&format=<strong>xml</strong>

Bezpieczny sposób przesyłania tokena autoryzacji

Aby wykluczyć śledzenie tokena przez adres URL żądań, przekaż go na jeden z następujących sposobów, w zależności od zastosowanej metody API:

• w ramach żądania POST w polu access_token; w takim przypadku utwórz adres URL żądania bez użycia tej wartości, na przykład:

  https://mydomain.ru/api.php/<strong>shop.product.getInfo</strong>?<strong>id=4</strong>

  ;
• w nagłówku HTTP AUTHORIZATION w formacie «Bearer <strong>ACCESS_TOKEN</strong>».

  Przykłady

      /**
      * waNet
      */
      
      $net = new waNet([
          'authorization' => true,
          'auth_type' => 'Bearer',
          'auth_key' => '1d1863e4afd0fd818a74adbb56e9c2a6',
          'format' => waNet::FORMAT_JSON,
      ]);
      $response = $net->query('https://mydomain.ru/api.php/shop.product.getInfo', [
          'id' => 4,
      ], waNet::METHOD_GET);
      
      /**
      * PHP curl
      */
      
      $curl_h = curl_init('https://mydomain.ru/api.php/shop.product.getInfo/?id=4');
      
      curl_setopt($curl_h, CURLOPT_HTTPHEADER, [
          'Authorization: Bearer 1d1863e4afd0fd818a74adbb56e9c2a6',
      ]);
      
      # do not output, but store to variable
      curl_setopt($curl_h, CURLOPT_RETURNTRANSFER, true);
      
      $response = curl_exec($curl_h);
      $response = json_decode($response, true);
      
      /**
      * jQuery
      */
      
      $.ajax({
          url: 'https://mydomain.ru/api.php/shop.product.getInfo/?id=4',
          headers: {
              'Authorization': 'Bearer 1d1863e4afd0fd818a74adbb56e9c2a6'
          }
      }).then(function(response) {
          console.log(response);
      });

W przypadku błędu w odpowiedzi zawsze będzie dostępne pole error:

JSON

{"error": "invalid_request"}

XML

<response>
    <error>invalid_request</error>
</response>

Kody błędów (element error)