Automater API v2
Latest commit 22bee28 Dec 3, 2016 @kiczek kiczek committed on GitHub Update README.md
Permalink
Failed to load latest commit information.
README.md Update README.md Dec 2, 2016

README.md

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