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
}}