Automater API v2
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md Update README.md Dec 30, 2017

README.md

Nowa wersja API

Ta wersja API nie jest już rozwijana. Prosimy zapoznać się z najnowszą wersją pod adresem https://github.com/automater-pl/rest-api

Dokumentacja API v2 dla Automater.pl

PHP SDK: możesz wykorzystać gotową bibliotekę w języku PHP

Podstawowe informacje

System Automater.pl udostępnia REST API w wersji 2. Komunikacja musi odbywać się poprzez szyfrowany kanał HTTPS dostępny pod adresem:

https://automater.pl/api_v2/

Do poprawnego funkcjonowania API wymagane jest pobranie API Key i API Secret z panelu użytkownika. Można je pobrać w menu Ustawienia / Konto / API. Ze względu na to, że klucze umożliwiają zdalny dostęp do zasobów użytkownika, wymagane jest aby nie były widoczne dla użytkownika końcowego, np. klienta sklepu internetowego.

Klucz API w każdym żądaniu

Każde żądanie wysłane do API musi w query string zawierać parametr key=wartość-api_key. Przykładowe wywołanie:

GET https://automater.pl/api_v2/products?key=wartość-api-key

Stronicowanie wyników

Dla metod zwracających listę z wynikami (np. lista produktów lub baz kodów) należy wykorzystać mechanizm stronicowania. Domyślnie zwracanych jest 50 rekordów posortowanych od najstarszych do najnowszych. Jeśli pobrane dane można stronicować to w odpowiedzi serwera znajdziemy pola:

array(
  'code' => 200,
  'data' => array() // odpowiedź serwera,
  'page' => 1, // strona wyników
  'current' => 1, // ilość wyświetlonych rekordów
  'all' => 5 // ilość wszystkich rekordów
)

Wyniki mogą być stronicowane poprzez dodanie tzw. named params w następujący sposób:

GET https://automater.pl/api_v2/products/page:2/limit:75/?key=wartość-api-key

W powyższym przykładzie ustawiono, by serwer zwrócił 75 wyników z od drugiej strony. Maksymalna możliwa liczba rekordów do zwrotu to 100.

Podpisy pakietów

Dla metody POST wymagane jest, aby przesyłane pakiet zawierał dodatkowe pole: sign. To pole powinno zawierać sumę md5 uzyskaną poprzez połączenie ze sobą przesyłanych elementów i doklejenie do nich parametru API Secret.

Poniżej znajduje się pseudokod obrazujący działanie algorytmu do uzyskania wartości sign:

  • sortowanie elementów tablicy przesyłanej metodą POST alfabetycznie według ich kluczy,
  • łączenie ze sobą wszystkich elementów posortowanej tablicy z dodatkowym znakiem "|" po każdym polu,
  • dodanie na końcu ciągu wartości API Secret,
  • wygenerowanie podpisu md5 dla otrzymanego ciągu.

Przykład funkcji zwracającej sign w języku PHP:

function sign( $query , $secret ) { 
  ksort( $query );
  $sign = implode( '|' , $query ); 
  $sign .= '|' . $secret;
  return md5( $sign );
}

Format zwracanych danych

Serwer zawsze odbpowiada w postaci JSON. W przypadku błędu odpowiedź będzie wyglądać następująco:

array(
  'code' => 501, // jeśli wystąpi błąd to kod jest większy lub równy 500
  'message' => 'Auth failed' // opis błędu
)

W przypadku pozytywnej odpowiedzi zawsze zawiera ono pole code z wartością 200. Pozostałe elementy, które zostaną zwrócone, mogą się róznić w zależności od wybranej funkcji.

Dostępne funkcje

Produkty

Pobranie listy produktów

GET https://automater.pl/api_v2/products?key=wartość-api-key

Format odpowiedzi:

Array
(
  [code] => 200 // status
  [data] => Array // tablica wyników
  (
    [0] => Array
    (
        [id] => 75353 // id produktu
        [database_id] => 28360 // id powiązanej bazy kodów
        [name] => testowa gra // nazwa produktu
        [description] => <p>kod do gry</p> // opis produktu z formatowaniem HTML
        [price] => 10.50 // cena za sztukę
        [currency] => USD // waluta
        [available] => 17 // ilość dostępnych kodów / plików w bazie
    )
  
    [1] => Array
    (
        [id] => 54333
        [database_id] => 14432
        [name] => testowy kod
        [description] => <p>testowy produkt 2</p>
        [price] => 1
        [currency] => PLN
        [available] => 9
    )
  )

  [page] => 1
  [current] => 2
  [count] => 14
)

Transakcje

Utworzenie nowej transakcji w systemie

POST https://automater.pl/api_v2/buyers?key=wartość-api-key

Przykładowe żądanie:

$packet = array(
  // identyfikatory produktów połączone przecinkiem lub jeden identyfikator dla których tworzymy zamówienie
  // POLE OBOWIĄZKOWE
  'listing_ids' => '54333,75353', 
  // adres e-mail klienta na który mają zostać wysłane produkty
  // POLE OBOWIĄZKOWE
  'email' => 'jan@nowak.pl', 
  // ilość zakupionych produktów w przedziale 1-100
  // gdy w tym polu znajdzie się jedna liczba to system przypisze ją dla wszystkich zamówień
  // gdy w tym polu znajdą się liczby oddzielone przecinkami to system przypisze je do produktów, np. 2 szt dla 75353
  // POLE NIEOBOWIĄZKOWE, domyślnie: 1
  'quantity' => '1,2',
  // numer telefonu (format: +48123456789) do oopcjonalnej wysyłki kodu na SMS
  // POLE NIEOBOWIĄZKOWE, domyślnie: null
  'phone' => '+48123456789'
  // język wiadomości do klienta
  // POLE NIEOBOWIĄZKOWE: domyślnie: pl, możliwe: pl lub en
  'language' => 'pl',
  // czy system ma wysłać wiadomość ze statusem transakcji do klienta
  // POLE NIEOBOWIĄZKOWE: domyślnie: 1, możliwe: 1 lub 2 (tak lub nie)
  'status' => 1,
  // informacja która ma zostać dodana do rejestru transakcji w systemie
  // POLE NIEOBOWIĄZKOWE: domyślnie:null, możliwe: string do 255 znaków
  'custom' => 'nowa transakcja z API'
)

Format odpowiedzi:

Array
(
  [code] => 200 // kod statusu
  [cart_id] => 651 // id utworzonego koszyka zakupowego
  [transaction_ids] => Array // id utworzonych transakcji
  (
      [0] => 1031414
      [1] => 1031415
      [2] => 1031416
  )
)

Księgowanie wpłaty dla koszyka / transakcji

POST https://automater.pl/api_v2/payment?key=wartość-api-key

Przykładowe żądanie dla księgowania płatności koszyka:

$packet = array(
  // typ płatności
  // POLE OBOWIĄZKOWE: możliwe: cart dla koszyka lub transaction dla transakcji
  'type' => 'cart',
  // id koszyka
  // POLE OBOWIĄZKOWE
  'cart_id' => 651,
  // id płatności, np. ID płatności z Transferuj.pl lub własnego systemu
  // POLE OBOWIĄZKOWE: string
  'payment_id' => 'testowa_platnosc_1',
  // kwota wpłaty
  // POLE OBOWIĄZKOWE: typ liczbowy
  'payment_amount' => 20.50,
  // waluta płatności
  // POLE OBOWIĄZKOWE: możliwe: PLN, EUR, USD lub GBP
  'payment_currency' => 'PLN',
  // informacja która ma zostać dodana do rejestru transakcji w systemie
  // POLE NIEOBOWIĄZKOWE: domyślnie:null, możliwe: string do 255 znaków
  'custom' => 'nowa płatność z API'

Przykładowe żądanie dla księgowania płatności dla poszczególnych transakcji:

$packet = array(
  // typ płatności
  // POLE OBOWIĄZKOWE: możliwe: cart dla koszyka lub transaction dla transakcji
  'type' => 'transaction',
  // identyfikatory transakcji połączone przecinkiem lub jeden identyfikator
  // POLE OBOWIĄZKOWE
  'transaction_ids' => '1031414,1031415',
  // id płatności, np. ID płatności z Transferuj.pl lub własnego systemu
  // POLE OBOWIĄZKOWE: string
  'payment_id' => 'testowa_platnosc_1',
  // kwota wpłaty
  // POLE OBOWIĄZKOWE: typ liczbowy
  'payment_amount' => 20.50,
  // waluta płatności
  // POLE OBOWIĄZKOWE: możliwe: PLN, EUR, USD lub GBP
  'payment_currency' => 'PLN',
  // informacja która ma zostać dodana do rejestru transakcji w systemie
  // POLE NIEOBOWIĄZKOWE: domyślnie:null, możliwe: string do 255 znaków
  'custom' => 'nowa płatność z API'

Format odpowiedzi:

Array
(
  [code] => 200 // kod statusu
  [transaction_ids] => Array // ID transakcji dla których prawidłowo zaksięgowano wpłatę 
  (
    [0] => 1031434
    [1] => 1031435
    [2] => 1031436
  )

Bazy kodów

Pobranie ilości dostępnych kodów / plików dla produktu

GET https://automater.pl/api_v2/products/ID_PRODUKTU/counter?key=wartość-api-key

Format odpowiedzi:

Array
(
  [code] => 200 // kod statusu
  [data] => Array 
  (
    [id] => 123, // id produktu
    [counter] => 11 // ilość kodów / plików w powiązanej bazie
  )

Pobranie adresów do obrazków z ilością kodów

GET https://automater.pl/api_v2/products/ID_PRODUKTU/counter?key=wartość-api-key&language=pl

W żądaniu można przesłać dodatkowy parametr language (pl lub en), który oznacza wersję językową obrazków.

Format odpowiedzi:

Array
(
  [code] => 200 // kod statusu
  [data] => Array 
  (
    [v1] => https://automater.pl/imgv1.png, // wersja 1: przezroczysty kwadrat z czarną czcionką
    [v2] => https://automater.pl/imgv1.png, // wersja 1: przezroczysty kwadrat z białą czcionką
    [v3] => https://automater.pl/imgv1.png, // wersja 1: przezroczysty prostokąt z czarną czcionką
    [v4] => https://automater.pl/imgv1.png, // wersja 1: przezroczysty prostokąt z białą czcionką
  )

Pobranie listy baz kodów

GET https://automater.pl/api_v2/databases?key=wartość-api-key

Format odpowiedzi:

Array
(
  [code] => 200 // status
  [data] => Array // tablica wyników
  (
    [0] => Array
    (
        [id] => 75353 // id bazy kodów
        [type] => 2 // typ bazy: 1 - baza normalna (1 kod do 1 klienta), 2 - baza rekurencyjna (ten sam kod do wszystkich)
        [name] => testowa baza kodów // nazwa produktu
        [available] => 11 // ilość dostępnych kodów / plików w bazie
        [sent] => 123 // ilość wysłanych kodów / plików z bazy
    )
  )

  [page] => 1
  [current] => 1
  [count] => 14
)

Dodawanie kodu do bazy

POST https://automater.pl/api_v2/codes/ID_BAZY_KODOW?key=wartość-api-key

Przykładowe żądanie dla dodania kodu do bazy o ID 75353:

$packet = array(
  // kody do dodania
  // POLE OBOWIĄZKOWE: format: tablica JSON
  'codes' => '["testowy kod 1","testowy kod 2","testowy kod 3"]'
)

Format odpowiedzi:

Array
(
  [code] => 200 // kod statusu
  [success] => Array  // tablica z kodami które zostały poprawnie dane
  (
    [0] => Array
    (
      [id] => 1124242,
      [code] => testowy kod 1
    )
    [1] => Array
    (
      [id] => 1124243,
      [code] => testowy kod 2
    )
  )
  [error] => Array  // tablica z kodami które nie zostały dodane z powodu błędu
  (
    [0] => Array
    (
      [code] => testowy kod 3
    )
  )
)

Zwracane kody błędów

  • 404: nie znaleziono zasobu
  • 501: nieprawidłowe dane uwierzytelniające (API Key)
  • 550: nieznany błąd
  • 551: nieprawidłowy podpis sign

Tworzenie nowej transakcji:

  • 501: brak parametru listing_ids lub e-mail
  • 502: adres e-mail jest nieprawidłowy
  • 503: listing_ids jest nieprawidłowy
  • 504: nie znaleziono produktów przekazanych w parametrze listing_ids
  • 505: liczba elementów w tablicy quantity nie pokrywa się z liczbą elementów w listing_ids
  • 506: ilość zakupionych produktów musi mieścić się w przedziale 1-100

Księgowanie wpłaty dla koszyka/transakcji:

  • 510: brak pól payment_id, payment_amount lub payment_currency lub wartości nieprawidłowe
  • 511: nie rozpoznano parametru type
  • 512: nie rozpoznano parametru cart_id lub jest nieprawidłowy
  • 513: nie rozpoznano parametru transaction_ids lub jest nieprawidłowy
  • 514: nie znaleziono żadnych transakcji

Dodawanie kodu do bazy:

  • 520: nie przekazano żadnych kodów do dodania