Atom REST API

Atom REST API to narzędzie pozwalające komunikować się ze sklepem AtomStore poprzez żądania HTTP, z wykorzystaniem danych w formacie JSON. Przy użyciu ustalonych i na bieżąco rozwijanych metod można wykonywać operacje odczytu i zapisu wybranych danych bez potrzeby logowania się do panelu administracyjnego.

Narzędzie jest przeznaczone dla programistów, zostało stworzone z myślą o budowie integracji z systemami magazynowo-księgowymi, ze sklepami partnerskimi, z systemami klasy ERP etc.

W razie niejasności prosimy naszych klientów o zgłoszenie w BOK w panelu administracyjnym, a inne zainteresowane osoby o bezpośredni kontakt.

• Adres i autoryzacja
• Przykładowe wywołanie (PHP)
• Metody
• Filtrowanie danych
• Zamówienia – dane szczegółowe

Adres i autoryzacja

Narzędzie wymaga włączenia modułu w konfiguracji sklepu:

Do poprawnej autoryzacji potrzebne są login i hasło administratora uzyskane w panelu administracyjnym AtomStore → USTAWIENIA → ADMINISTRATORZY, ewentualnie skorzystać można z tego samego loginu i hasła, które służą do logowania do panelu. W parametrach konta administratora należy zaznaczyć dostęp do API (wówczas wyświetli się konfiguracja dostępu do konretnych metod):

Adres do wywołań Atom REST API:
{domena sklepu wraz z „https://”}/api/{zasób}/{metoda}
np.:

Autoryzacja w wywołaniach poszczególnych metod API odbywa się poprzez token, który należy uzyskać wywołując endpoint:
{domena sklepu wraz z „https://”}/api/users/authorize
wraz z loginem i hasłem administratora. Token jest ważny w czasie 60 minut od dowolnego, skutecznego wywołania API.

Przykładowe wywołanie (PHP)

$post = [
    'login'    => 'admin',
    'password' => 'admin'
];

$headers = [
    'Content-Type: application/json'
];

$curl = curl_init('https://demo.atomstore.pl/api/users/authorize');

curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($post));

$token = json_decode(curl_exec($curl));

curl_close($curl);

if ($token->token){
    $headers = [
        'X-API-TOKEN: '.$token->token,
        'Content-Type: application/json'
    ];

    $url = 'https://demo.atomstore.pl/api/categories/index';

    $curl = curl_init();

    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');

    $result = json_decode(curl_exec($curl));

    curl_close($curl);
}

$post = [
    'login'    => 'admin',
    'password' => 'admin'
];

$headers = [
    'Content-Type: application/json'
];

$curl = curl_init('https://demo.atomstore.pl/api/users/authorize');

curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($post));

$token = json_decode(curl_exec($curl));

curl_close($curl);

if ($token->token){
    $headers = [
        'X-API-TOKEN: '.$token->token,
        'Content-Type: application/json'
    ];

    $url = 'https://demo.atomstore.pl/api/categories/index';

    $curl = curl_init();

    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');

    $result = json_decode(curl_exec($curl));

    curl_close($curl);
}

Metody

Metody/endpointy Atom REST API, a także struktury danych wejściowych i wyjściowych, zostały opisane tutaj:
https://docs.atomstore.pl/api_documentation/index

Filtrowanie danych

STRONICOWANIE – w wybranych metodach udostępniono parametry:

• page
• limit

które pozwalają na pobieranie dużej liczby rekordów partiami. Metadane w odpowiedzi JSON zawierają wtedy pole 'total’ informujące o łącznej liczbie pakietów danych, którą należy pobrać zwiększając w kolejnych wywołaniach wartość parametru 'page’.

FILTROWANIE – API pozwala zawężać odczytywane dane wg wybranych parametrów poprzez podanie w parametrach GET operatora oraz klucza (pola), np.:

Obsługiwane operatory:

• eq : dokładne dopasowanie
• like : podana fraza zawiera się w zwracanych danych
• in : podane frazy po przecinku dokładnie dopasowane (Tylko dla orders/index)
• notin : podane frazy po przecinku dokładnie nie dopasowane (Tylko dla orders/index)

i dodatkowo dla pól liczbowych oraz dat:

• gt : większe niż
• gte : większe lub równe od
• lt : mniejsze niż
• lte : mniejsze lub równe od

RÓŻNICOWANIE – zalecane jest cykliczne pobieranie danych nowych/zmienionych od poprzednio zakończonego cyklu. W tym celu oprogramowano parametry created/modified, np.:

Ustawienie:

pozwala dodatkowo odróżnić w systemie daty modyfikacji w różnych obszarach danych towaru:

• quantity_modified – zmiany stanów magazynowych, stanów u dostawców, statusów dostępności,
• price_modified – zmiany w zakresie cen, promocji,
• media_modified – zmiany w galerii zdjęć towaru,
• modified – pozostałe zmiany w kartotece produktu.

Prawidłowo zaimplementowana integracja powinna korzystać z takiej konfiguracji i różnicować odczyt powyższych danych niezależnie wg wskazanych parametrów.

Zamówienia – dane szczegółowe

Parametry wejściowe: