Podręcznik Integracji

Podręcznik Integracji

Spis treści 1. Integracja oferty... 3 1.1. Samodzielne wprowadzanie oferty sklepu... 3 1.2. Automatyczne wprowadzanie oferty z pliku XML... 3 1.3. Cyklicznie pobieranie oferty ze strony... 3 1.4. Lista obsługiwanych formatów XML... 3 2. Mapowanie (przypisywanie kategorii)... 4 3. API dla Partnerów rozliczających się za faktyczną sprzedaŝ... 4 3.1. Autoryzacja... 4 3.2. Lista moŝliwych operacji... 5 3.3. Odpowiedzi zwracane przez dostępne metody... 6 3.4. Przykłady zwracanych danych... 6

1. Integracja oferty Proces integracji polega na wprowadzeniu oferty do pasaŝu. Wymagania jakie musi spełniać sklep: mieć koszyk oraz dawać moŝliwość zakupów przez Internet umoŝliwiać eksport swojej oferty w jednym z obsługiwanych formatów jeśli Partner rozlicza się za sprzedaŝ, musi mieć moŝliwość zgłaszania transakcji przez API pasaŝu Przygotowaliśmy trzy metody integracji: Metoda ręczna samodzielne wprowadzanie oferty sklepu Metoda automatyczna automatyczne wprowadzanie oferty z pliku XML Metoda automatyczna ze strony cyklicznie pobieranie oferty ze strony 1.1. Samodzielne wprowadzanie oferty sklepu Metoda ta polega na ręcznym wprowadzaniu kaŝdej oferty z państwa sklepu. Aby wgrać produkty naleŝy zalogować się na panel i wybrać z menu Wgraj produkty. Pojawi nam się strona z trzema formularzami, wypełniamy formularz w sekcji Ręcznie pojedyncze oferty i zatwierdzamy Wyślij. Po poprawnym wprowadzeniu wszystkich produktów z Państwa sklepu naleŝy jeszcze przypisać swoje kategorie do kategorii pasaŝu. (Zobacz punkt 2) 1.2. Automatyczne wprowadzanie oferty z pliku XML Jeśli generują Państwo plik XML dla jednej z obsługiwanych przez nas porównywarek cen (Zobacz listę obsługiwanych porównywarek Rozdział 1.4), system moŝe automatycznie pobrać całą ofertę sklepu z podanego pliku XML. Aby jednorazowo wgrać plik XML naleŝy zalogować się na panel i wybrać Wgraj produkty. Pojawi nam się strona z formularzem Automatycznie pliki XML. Plik z ofertą moŝemy wybrać z dysku lub podać adres pliku XML który istnieje w Internecie oraz wybieramy format pliku przygotowanego dla porównywarki. 1.3. Cyklicznie pobieranie oferty ze strony Cykliczne pobieranie oferty ze strony to funkcja która umoŝliwia automatyczne pobieranie oferty ze wskazanego przez Państwa pliku XML. Plik z ofertą powinien być w jednym z obsługiwanych przez nas formatów (Zobacz listę punkt 1.4) Na stronie Wgraj produkty wypełniamy ostatni formularz Automatycznie ze strony. Podajemy poprawny adres URL pliku dostępnego w Internecie, login i hasło (jeśli plik jest zabezpieczony hasłem), wybieramy format pliku przygotowanego dla porównywarki oraz częstotliwość pobierania oferty. 1.4. Lista obsługiwanych formatów XML Oto lista obsługiwanych przez nasz system porównywarek cen wraz z adresem do specyfikacji formatu lub przykładowego pliku XML Cenuj - http://www.cenuj.pl/cenuj.xml (przykładowy plik XML) Kupujemy.pl http://www.kupujemy.pl/wymiana-danych.html

Najtaniej24.pl http://www.najtaniej24.pl/shop/integracja_najtaniej24.pdf Nokaut - http://www.nokaut.pl/dl/nokaut-integracja.pdf Od ręki - http://www.odreki.pl/?mode=instrukcja_integracji&shops=1&download=1&file=integ racja_z_odreki_pl.pdf Okazje.info.pl - http://www.okazje.info.pl/r/files/okazje-integracja.pdf OnetZakupy - http://zakupy.onet.pl/panel/_i/podrecznik_integracji.pdf Radar - http://www.radar.pl/download/radar_-_instrukcja_integracji.pdf 2. Mapowanie (przypisywanie kategorii) Proces mapowania polega na przypisywaniu kategorii sklepu, w których znajdują się produkty, do kategorii pasaŝu (Czynność mapowania nie jest konieczna w przypadku ręcznego dodawania produktów). Na stronie panelu w sekcji Mapowanie kategorii wybieramy Przypisz kategorię wyświetli nam lista z zaimportowanymi kategoriami, które powinniśmy przypisać do kategorii pasaŝu. Aby zmapować daną kategorię wybieramy kategorię z listy i przechodzimy na stro1nę Zmień kategorię. Następnie naleŝy wybrać odpowiednią kategorię z naszego serwisu oraz zatwierdzamy Zmień. Jeśli nie ma odpowiadającej kategorii, klient moŝe zmienić szablon produktu wchodząc na Twoje produkty w pasaŝu, wybierając produkt i kliknąć edytuj produkt. Następnie wybieramy szablon produktu i akceptujemy. 3. API dla Partnerów rozliczających się za faktyczną sprzedaŝ KaŜdy Partner, który rozlicza się za faktyczną sprzedaŝ musi sprawdzać przy kaŝdym wejściu na sklep, czy nagłówek HTTP_REFERER wskazuje na stronę pasaŝu. JeŜeli uŝytkownik przychodzi z naszego pasaŝu to Partner powinien zapisać o tym informację w cookies lub sesji i przy kaŝdym jego zakupie (do zamknięcia przeglądarki) transakcja musi wprowadzana przez nasz interfejs programistyczny (API) pasaŝu. Architektura interfejsu programistycznego PasaŜu jest zgoda z wzorcem REST gdzie jednostką informacji jest zasób. Jako format danych uŝywamy formatu JSON Korzystanie z zasobów interfejsu wymaga autoryzacji Partnera poprzez wcześniej wygenerowany API_KEY. (więcej informacji punkt 3.1. Autoryzacja) Komunikacja z interfejsem programistycznym odbywa się poprzez adres URL: http://muratordom.pl/api/transactions/ 3.1. Autoryzacja Partner rozliczający się za faktyczną sprzedaŝ powinien pobrać klucz api_key oraz secret. KaŜde zapytanie aby było poprawnie uwierzytelnianie musi zawierać w nagłówku następujące dane: _api_ver - uŝywana wersja API (w tym dokumencie opisana jest wersja 0.1) _api_key - klucz api który moŝna pobrać z panelu klienta _timestamp - czas wykonania zapytania _signature - unikalna sygnatura identyfikująca dane zapytanie

timestamp - Czas wykonania zapytania w postaci liczby sekund od godz. 00:00 1 stycznia 1970 r (standardowy UNIXowy timestamp). Uwaga, naleŝy upewnić się, Ŝe na komputerze z którego wykonywane jest zapytanie jest ustawiony poprawny czas. Np. 1264167558 Secret - ciąg znaków pobrany razem z kluczem api z panelu klienta Np. "kdk&/t~2zduqjx:ye$! Kroki generowania _signature: 1. Sklejamy ciągi znaków w następującej kolejności: uri, timestamp, secret Przykładowy wynik: /api/transactions/1264167558"kdk&/t~2zduqjx:ye$! (zwróć uwagę na brak spacji) 2. Dla otrzymanego ciągu obliczamy sumę kontrolną SHA1 Przykładowy wynik dla danych z poprzedniego punktu: d4812548af61216e88765a3c408aeea43149a2fd Przykładowa implementacja w języku Python: signature = sha1( "%s%s%s" % (uri, timestamp, secret) ).hexdigest() Uwaga, timestamp oraz sygnatura muszą być za kaŝdym razem generowane na nowo. Nawet powtarzając zapytanie, które z jakiegoś powodu nie zostało wykonane pomyślnie. 3.2. Lista moŝliwych operacji Operowanie na transakcjach odbywa się przez zasób transactions - (http://wymarzonyogrod.pl/api/transactions/), który posiada funkcje takie jak: GET /api/transactions/ Lista wszystkich transakcji danego klienta. GET /api/transactions/{transaction_id} Szczegółowe informacje o wybranej transakcji POST /api/transactions/ Dodanie transakcji do systemu DELETE /api/transactions/{transaction_id} Usunięcie wybranej transakcji Wymagane parametry przy dodawaniu transakcji: passage symbol amount kwota transakcji client_ip identyfikator klienta client_browser przeglądarka klienta transaction_number numer transakcji elements lista produktów elements składa się z następujących pól: object_id identyfikator produktu w sklepie name nazwa produktu quantity ilość produktów price cena produktu value wartość produktu

3.3. Odpowiedzi zwracane przez dostępne metody KaŜdy zasób zwraca kod odpowiedzi który informuje o rezultacie wykonania danej operacji. 200 OK operacja została wykonana prawidłowo 201 CREATED operacja tworzenia nowego obiektu została wykonana pomyślnie 204 NO CONTENT operacja usuwania obiektu została wykonana pomyślnie 400 BAD REQUEST zły format zapytania 401 UNAUTHORIZED błąd autoryzacji 403 FORBIDDEN brak dostępu 410 GONE obiekt nie istnieje 3.4. Przykłady zwracanych danych Zasoby pobierające dane z naszego systemu zwracają dane w formacie JSON. Przykład danych zwróconych przy pobieraniu transakcji: GET /api/transactions/14/ { transaction_number, 14, amount : 500, client_ip : 127.0.0.1, client_browser : Firefox, elements : { object_id : 4, name : Wiertarka udarowa, quantity : 1, price : 500, value : 500 }} Przykład danych zwróconych przy listowaniu transakcji: GET /api/transactions/ {{ id, 14, passage : WO, amount : 10, transaction_number, 1 }, { id, 15, passage : WO, settlement: CPT, amount : 20, transaction_number, 2 }}