Dokumentacja API

 Dokumentacja API Automater.pl zdalne tworzenie i zarządzanie transakcjami dokumentacja API wersja 0.1 A u t o m a t e r s p . z o . o . , u l . B e l g r a d z k a 4 / 4 2 , 0 2 -­‐ 7 9 3 W a r s z a w a 0.1 2 1. Wstęp System Automater.pl udostępnia API, dzięki któremu możliwe jest zdalne rozpoczynanie transakcji i zarządzanie 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. Generowanie dostępu API Aby uzyskać dostęp do zdalnego interfejsu API należy zalogować się na swoje konto Automater, a następnie przejść do ustawień konta. Następnie z lewego menu należy wybrać opcję API. Jeśli klucze nie zostały jeszcze wygenerowane to należy je najpierw wygenerować. Każde kolejne generowanie kluczy API spowoduje nadpisanie 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. Podpisywanie transakcji Niektóre operacje wykonywane na koncie wymagają szczególnych środków bezpieczeństwa. Tak jest np. z księgowaniem wpłat za zakupy. Jeśli komunikacja nie zostanie odpowiednio zabezpieczona to hacker prostym sposobem może zaksięgować wpłatę ręcznie i wykraść z bazy kody. Do podpisywania transakcji wykorzystywany jest klucz API Secret. Poniżej znajduje się pseudokod obrazujący działanie algorytmu zwracającego podpis transakcji „sign”: 1. sortowanie elementów tablicy przesyłanej metodą POST alfabetycznie według ich kluczy, 2. łączenie ze sobą wszystkich elementów (string) posortowanej tablicy z dodatkowym znakiem „|” po każdym polu, 3. dodanie na końcu ciągu pola API Secret, 4. wygenerowanie 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. Tworzenie nowej transakcji Transakcje mogą zostać utworzone tylko dla produktów, które zostały dodane do sklepu. Funkcja ta ma zastosowanie np. przy sprzedaży eBook’a przez swoją stronę internetową, komunikacja powinna wtedy wyglądać następująco: 1. wysłanie żądanie stworzenia nowej transakcji dla produktu o określonym ID, 2. po potwierdzeniu płatności przesłanie żądania potwierdzenia wpłaty. 4.1 Żądanie Aby utworzyć nową transakcje należy przesłać żądanie POST pod adres: http://nowy.automater.pl/api/buyers/create.json Pola przesyłane metodą POST powinny zawierać: Nazwa pola Wymagane Opis key tak API Key dostępny w panelu listing_id tak Identyfikator produktu dla którego transakcja ma zostać rozpoczęta mail tak Adres mailowy klienta, jest to również adres na który mają zostać wysłane kody quantity nie domyślnie: 1 zakres: 1-­‐1000 Ilość zakupionych sztuk phone nie domyślnie: brak Numer telefonu klienta, używany np. do wysyłki kodu na SMS jeśli wybrano taką opcję language nie domyślnie: EN Wersja językowa wiadomości i powiadomień dla klienta, możliwe wartości: EN – angielski PL -­‐ polski custom nie domyślnie: brak Dodatkowa informacja o transakcji dodawana do rejestru, maksymalnie 255 znaków 4 4.2 Odpowiedź Na przesłane żądanie serwer odpowie w formacie tablicy JSON zależnie od rezultatu. 4.2.1 Transakcja stworzona prawidłowo W przypadku prawidłowego dodania transakcji do systemu zwrócona zostanie tablica JSON zawierająca następujące elementy: transaction:
id: id_nowoutworzonej_transakcji
created: data dodania transakcji w formacie unix time
Przykładowa odpowiedź serwera: {
"transaction": {
"id": "211",
"created": 1427825310
}
}
4.2.2 Błąd przy tworzeniu transakcji W przypadku problemu przy tworzeniu nowej transakcji zostanie 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
Przykładowa odpowiedź serwera: {
}
"code": 500,
"name": "Method error",
"message": "Method error",
"url": "\/api\/buyers\/create.json"
5 5. Księgowanie wpłaty dla transakcji Istnieje możliwość zdalnego potwierdzenia wpłaty dla transakcji. Po zaksięgowaniu wpłaty kody lub pliki zostaną automatycznie dostarczone do klienta, o ile w bazie kodów będzie znajdować się ich wystarczająca ilość. 5.1 Żądanie Aby zmienić status płatności dla transakcji o wybranym identyfikatorze należy przesłać żądanie metodą POST pod adres: http://nowy.automater.pl/api/buyers/payment.json Pola przesyłane metodą POST powinny zawierać: Nazwa pola Wymagane Opis key tak API Key dostępny w panelu buyer_id tak Numer transakcji (ID) payment_id tak 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 nie domyślnie: brak długość: do 255 znaków Ilość zakupionych sztuk payment_endtime nie domyślnie: aktualny czas format: unix time Data odebrania wpłaty w formacie unix time, w przypadku nie zdefiniowania pola zostanie pobrany bieżący czas amount tak format: wartość w groszach Kwota wpłaty w groszach (analogicznie dla innych walut), np. dla kwoty 23,59 PLN należy przekazać wartość 2359. sign tak format: hash md5 Podpis transakcji z wykorzystanie API Secret (dokładny opis podpisywania transakcji znajduje się w pkt. 3 dokumentacji) 6 5.2 Odpowiedź Na przesłane żądanie serwer odpowie w formacie tablicy JSON zależnie od rezultatu. 5.2.1 Płatność zaksięgowana prawidłowo W przypadku prawidłowego dodania transakcji do systemu zwrócona zostanie tablica JSON zawierająca następujące elementy: transaction:
id: id_wpłaty
created: data dodania płatności w formacie unix time
Przykładowa odpowiedź serwera: {
"payment": {
"id": "211",
"created": 1427825310
}
}
5.2.2 Błąd przy tworzeniu transakcji W przypadku problemu przy tworzeniu nowej transakcji zostanie 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
Przykładowa odpowiedź serwera: {
}
"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"