Dokumentacja API 0.1 Automater.pl zdalne tworze i zarządza transakcjami dokumentacja API wersja 0.1 Automater sp. z o.o., ul. Belgradzka 4/42, 02-793 Warszawa
2 1. Wstęp System Automater.pl udostępnia API, dzięki któremu możliwe jest zdalne rozpoczyna transakcji i zarządza sprzedażą. Komunikacja oparta jest na architekturze REST API. Żądania należy przesyłać poprzez protokół POST. Odpowiedź jest zawsze zwracana w postaci tablicy JSON. 2. Generowa dostępu API Aby uzyskać dostęp do zdalnego interfejsu API należy zalogować się na swoje konto Automater, a następ przejść do ustawień konta. Następ z lewego menu należy wybrać opcję API. Jeśli klucze zostały jeszcze wygenerowane to należy je najpierw wygenerować. Każde kolejne generowa kluczy API spowoduje nadpisa starych. System generuje zawsze 2 unikatowe klucze: API Key - klucz służący do identyfikacji żądań użytkowników przez system, API Secret tajny klucz do podpisywania transakcji (o ile jest to wymagane). 3. Podpisywa transakcji Niektóre operacje wykonywane na koncie wymagają szczególnych środków bezpieczeństwa. Tak jest np. z księgowam wpłat za zakupy. Jeśli komunikacja zosta odpowiednio zabezpieczona to hacker prostym sposobem może zaksięgować wpłatę ręcz i wykraść z bazy kody. Do podpisywania transakcji wykorzystywany jest klucz API Secret. Poniżej znajduje się pseudokod obrazujący działa algorytmu zwracającego podpis transakcji sign : 1. sortowa elementów tablicy przesyłanej metodą POST alfabetycz według ich kluczy, 2. łącze ze sobą wszystkich elementów (string) posortowanej tablicy z dodatkowym znakiem po każdym polu, 3. doda na końcu ciągu pola API Secret, 4. wygenerowa podpisu md5 dla utworzonego ciągu. Poniżej znajduje się funkcja w języku PHP zwracająca podpis transakcji: function sign( $query, $secret ) ksort( $query ); $sign = implode( ' ', $query ); $sign.= ' '. $secret; return md5( $sign ); Przykład użycia funkcji sign() dla metody księgowania wpłaty: $sign = sign(array('buyer_id' => 123, 'payment_id' => '4SDF23', 'amount' => 1000, 'key' => '522748524ad010358705b6852b81be4c'), '5f039b4ef0058a1d652f13d612375a5b');
3 4. Tworze nowej transakcji Transakcje mogą zostać utworzone tylko dla produktów, które zostały dodane do sklepu. Funkcja ta ma zastosowa np. przy sprzedaży ebook a przez swoją stronę internetową, komunikacja powinna wtedy wyglądać następująco: 1. wysła żąda stworzenia nowej transakcji dla produktu o określonym ID, 2. po potwierdzeniu płatności przesła żądania potwierdzenia wpłaty. 4.1 Żąda Aby utworzyć nową transakcje należy przesłać żąda POST pod adres: http://nowy.automater.pl/api/buyers/create.json Pola przesyłane metodą POST powinny zawierać: Nazwa pola Wymagane Opis key API Key dostępny w panelu listing_id Identyfikator produktu dla którego transakcja ma zostać rozpoczęta mail Adres mailowy klienta, jest to rówż adres na który mają zostać wysłane kody quantity domyśl: 1 zakres: 1-1000 Ilość zakupionych sztuk phone language custom domyśl: brak domyśl: EN domyśl: brak Numer telefonu klienta, używany np. do wysyłki kodu na SMS jeśli wybrano ą opcję Wersja językowa wiadomości i powiadomień dla klienta, możliwe wartości: EN angielski PL - polski Dodatkowa informacja o transakcji dodawana do rejestru, maksymal 255 znaków
4 4.2 Odpowiedź Na przesłane żąda serwer odpowie w formacie tablicy JSON zależ od rezultatu. 4.2.1 Transakcja stworzona prawidłowo W przypadku prawidłowego dodania transakcji do systemu zwrócona zosta tablica JSON zawierająca następujące elementy: transaction: id: id_nowoutworzonej_transakcji created: data dodania transakcji w formacie unix time "transaction": "id": "211", "created": 1427825310 4.2.2 Błąd przy tworzeniu transakcji W przypadku problemu przy tworzeniu nowej transakcji zosta zwrócona tablica JSON zawierające następujące elementy: code: 500 name: opis_błędu message: opis_błędu url: /api/buyers/create.json "code": 500, "name": "Method error", "message": "Method error", "url": "\/api\/buyers\/create.json"
5 5. Księgowa wpłaty dla transakcji Istje możliwość zdalnego potwierdzenia wpłaty dla transakcji. Po zaksięgowaniu wpłaty kody lub pliki zostaną automatycz dostarczone do klienta, o ile w bazie kodów będzie znajdować się ich wystarczająca ilość. 5.1 Żąda Aby zmienić status płatności dla transakcji o wybranym identyfikatorze należy przesłać żąda metodą POST pod adres: http://nowy.automater.pl/api/buyers/payment.json Pola przesyłane metodą POST powinny zawierać: Nazwa pola Wymagane Opis key API Key dostępny w panelu buyer_id Numer transakcji (ID) payment_id długość: do 50 znaków Unikalny identyfikator wpłaty pochodzący z zewnętrznego systemu, np. txn_id z PayPal lub tr_id z Transferuj payment_description domyśl: brak długość: do 255 znaków Ilość zakupionych sztuk payment_endtime amount sign domyśl: aktualny czas format: unix time format: wartość w groszach format: hash md5 Data odebrania wpłaty w formacie unix time, w przypadku zdefiniowania pola zosta pobrany bieżący czas Kwota wpłaty w groszach (analogicz dla innych walut), np. dla kwoty 23,59 PLN należy przekazać wartość 2359. Podpis transakcji z wykorzysta API Secret (dokładny opis podpisywania transakcji znajduje się w pkt. 3 dokumentacji)
6 5.2 Odpowiedź Na przesłane żąda serwer odpowie w formacie tablicy JSON zależ od rezultatu. 5.2.1 Płatność zaksięgowana prawidłowo W przypadku prawidłowego dodania transakcji do systemu zwrócona zosta tablica JSON zawierająca następujące elementy: transaction: id: id_wpłaty created: data dodania płatności w formacie unix time "payment": "id": "211", "created": 1427825310 5.2.2 Błąd przy tworzeniu transakcji W przypadku problemu przy tworzeniu nowej transakcji zosta zwrócona tablica JSON zawierające następujące elementy: code: 500 name: opis_błędu message: opis_błędu url: /api/buyers/payment.json "code": 352, "name": "You are not the owner of this transaction", "message": "You are not the owner of this transaction", "url": "\/api\/buyers\/payment.json"