Aukcje Zwierząt

Darmowy europejski system pośrednictwa handlu zwierzętami - Inflolinia Techniczna: 89 542 50 40

Witaj Gościu! Zaloguj się lub Zarejestruj.

Potrzebujesz pomocy

API - Specyfikacja techniczna

Pobieranie Ogłoszeń

Metodologia i format przesyłu danych

API systemu pozwala przyjmować wartości w dwóch formatach. Jako dane zakodowane w formularzu przesłane za pomocą metody POST jak również dokumentu XML zgodnego ze strukturą interfejsu. Interfejs korzysta jednocześnie z metody GET lub POST do przesyłania parametrów zapytania do których należą:

ApiKey - Zawierający klucz API do systemu
page - Określający stronę wyników

Wszystkie dane powinny zostać wysłane w następujący formacie: 

http://aukcjezwierzat.pl/api/getDataByXML.php?ApiKey=Twoj_klucz_api&page=numer_strony

Zapytania powinny być kierowane na adre: 

// W przypadku zapytań poprzez XML
http://aukcjezwierzat.pl/api/getDataByXML.php

// W przypadku zapytań poprzez POST
http://aukcjezwierzat.pl/api/getDataByPOST.php


Autoryzacja
Autoryzacja API odbywa się na podstawie klucza wygenerowanego za pomocą panelu zarządzania API w systemie aukcjezwierzat.pl. Klucz API powinien zostać przesłany do systemu za pomocą metody GET na adres 

http://aukcjezwierzat.pl/api/getDataByXML.php?ApiKey=Twoj_klucz_api
W przypadku błędnej autoryzacji w zależności od formy błędu system zwróci następujące komunikaty:

ERR001: Auth Error - W przypadku awarii systemu autoryzacji
ERR002: Auth Timeout - W przypadku przekroczenia czasu potwierdzenia autoryzacji
ERR003: Auth Deny - W przypadku zablokowania klucza użytkownika
ERR004: Wrong Key - W przypadku podania niewłaściwego klucza
ERR005: Key Auth Timeout Exceeded - W przypadku próby autoryzacji 10 klucz w ciągu 60sek. Czas trwania 60min

Struktura zapytania
Zapytanie powinno być kierowane w jednej z dwóch dostępnych form (Formularz POST, Dokument XML). Poniższa tabelka przedstawia parametry, które można wysyłać w zpaytaniu do systemu. Parametry te pozwalają filtrować wyniki w zależności od warunków, które państwa interesują.

Parametr Domyślnie Dopuszczalne Opis
ApiKey 0 32 znakowy klucz Klucz Api wygenerowany w systemie odpowiada za weryfikację przesyłanych danych
Kategoria 0 0 do 21 Kategoria określa gatunek wyszukiwanych zwierząt. Wartość domyślna jednocześnie określa dowolny gatunek

0 - Dowolny
Lista Gatunków wraz z kodami

SubKategoria 0 od 0 do 1071 Kategoria określa rase wyszukiwanych zwierząt. Jest ściśle połączona z Kategorią. Wybór Subkategorii która nie wiąże się z kategorią spowoduje wyświetlenie zerowego wyniku.

0 - Dowolny
Lista ras wraz z kodami

Sex 0 0 do 4 Płeć zwierząt. W zależności od kategorii okreśelnia płci są charakterystyczne. Podstawowy podział wygląda następująco

0 - Dowolna Płeć
1 - Samica
2 - Samica
3 - Młode zwierze Samica
4 - Młode zwierzę Samiec

AdvertType 0 0,1,2,3 Parametr określa rodzaj ogłoszenia, które chcemy pobrać

0 - Dowolny typ
1 - Ogłoszenia
2 - Licytacje
3 - Kupuje/Sprzedaje

Country 4 od 1 do 250, 666 Określa kraj na który przeznaczone jest ogłoszenie.

4 - Dowolne/Wszystkie kraje świata
666 - Unia Europejska ;]
1 do 250 Lista krajów wraz z kodami

String Wartość pusta Ciąg znaków Możesz filtrować ogłoszenia na podstawie wartości tekstowej. Tytuł i Opis ogłoszenia zostanie przeszukany na zawieranie wnioskowanej frazy.

Np: Wartość "Konik" zwróci ogłoszenia zawierające w tytule lub opisie wartość "Konik"

Rok 0 od 0 do obecny rok Wartość określa rok dodania ogłoszenia

0 - dowolny rok

Miesiac 0 od 0 do 12 Wartość określa miesiąc dodania ogłoszenia

0 - dowolny miesiąc

Dzien 0 od 0 do 31 Wartość określa dzień dodania ogłoszenia

0 - dowolny dzień

User 0 INTEGER Wartość określa numer ID użytkownika, którego ogłoszenia chcemy wyświetlić. W przypadku braku użytkownika w bazie, system zwróci wynik pusty bez żadnego błedu.

0 - dowolny użytkownik

FormatWyniku 1 0,1,2 Parametr określa format wyniku, który zostanie udzielony w odpowiedzi na zapytanie

0 - Serialized PHP
1 - Struktura XML bez nagłówka
2 - Pełny dokument XML

Debug 0 0,1 Tryb debugowania zwraca zamiast wartości logicznej komunikaty systemowe. W przypadku gdy proces autoryzacji i zapytania przebiegł prawidłowo system zwraca odpowiedź OK. W wypadku błędów Debug zwraca konkretne elementy, które nie przeszły weryfikacji.
Limit 0 0 do 100 Parametr określa ile elementów ma zotać przesłanych za pomocą jednego zapytania. Kolejne strony można realizować na podstawie parametru GET page jak również Parametru Strona dla metody POST lub XML
Strona 1 INT Parametr jest odpowiednikiem parametru sterowania przesyłanego za pomocą GET. Określa stronę wyników w określonym limicie.

Dane wysyłane w formacie XML powinny przyjąć następującą formę
Wszystkie elementy poza ApiKey są opcjonalne. 

<?xml version="1.0" encoding="utf8"?>
<Document>
	<Zapytanie>
		<ApiKey></ApiKey>		
		<Kategoria></Kategoria>	
		<SubKategoria></SubKategoria>		
		<Sex></Sex>									
		<AdvertType></AdvertType>	
		<Country></Country>	
		<String></String>	
		<Rok></Rok>	
		<Miesiac></Miesiac>			
		<Dzien></Dzien>					
		<User>0</User>
		<FormatWyniku></FormatWyniku>	
		<Debug>0</Debug>	
		<Limit></Limit>	
		<Strona></Strona>	        						
	</Zapytanie>
</Document>

Dane wysyłane w formie formularza POST powinny przyjąć następującą formę
Wszystkie elementy poza ApiKey są opcjonalne. 

<form action='http://aukcjezwierzat.pl/api/getDataByXML.php?ApiKey=klucz' method='post'>
<input type='hidden' name='ApiKey' value=''>
<input type='hidden' name='Kategoria' value=''>	
<input type='hidden' name='SubKategoria' value=''>
<input type='hidden' name='Sex' value=''>								
<input type='hidden' name='AdvertType' value=''>
<input type='hidden' name='Country' value=''>
<input type='hidden' name='String' value=''>
<input type='hidden' name='Rok' value=''>
<input type='hidden' name='Miesiac' value=''>
<input type='hidden' name='Dzien' value=''>		
<input type='hidden' name='User' value='0'>
<input type='hidden' name='FormatWyniku' value=''>	
<input type='hidden' name='Debug' value='0'>
<input type='hidden' name='Limit' value=''>
<input type='hidden' name='Strona' value=''>	        						
</form>
Odbiór Treści
Parametr FormatWyniku definiuje format odpowiedzi API systemu. Poniżej znajdując się 3 możliwe formy odpowiedzi zaserwowane przez system.

Odpowiedź dla formatów 1 i 2 w formie dokumentu XML
W odpowiedzi na zapytanie zostanie wygenerowana następująca struktura. Struktura ta zawiera dane statystyczne w znacznikach <Dane></Dane> a także listę ogłoszeń w znaczniku <Ogloszenia></Ogloszenia>. Ogłoszenia oddzielone są znacznikami <Advert></Advert> 

<Document>
<Dane>
	<LiczbaOgloszen>43</LiczbaOgloszen>
</Dane>
<Ogloszenia>
  <Advert>
    <Id>56</Id>
    <Tytul>fdsfsd</Tytul>
    <Opis>sfds</Opis>
    <Data>2008-10-10 14:22:54</Data>
    <ZdjecieMale>http://animalsmarket.com/img/offers/water/pig_water.gif</ZdjecieMale>
    <ZdjecieDuze>http://animalsmarket.com/img/offers/water/pig_water.gif</ZdjecieDuze>
    <AdresURL>http://aukcjezwierzat.pl/aukcja56_fdsfsd.html</AdresURL>
    <Kategoria>Świnie</Kategoria>
    <SubKategoria>Inne</SubKategoria>
    <Kraj>Wszystkie Kraje Swiata</Kraj>
    <Cena>0</Cena>
    <Waluta>Euro</Waluta>
    <TypAukcji>0</TypAukcji>
    <UzytkownikID>1</UzytkownikID>
  </Advert>
  <Advert>
    <Id>58</Id>
    <Tytul>fdsfsd</Tytul>
    <Opis>sfds</Opis>
    <Data>2008-10-10 14:22:54</Data>
    <ZdjecieMale>http://animalsmarket.com/img/offers/water/pig_water.gif</ZdjecieMale>
    <ZdjecieDuze>http://animalsmarket.com/img/offers/water/pig_water.gif</ZdjecieDuze>
    <AdresURL>http://aukcjezwierzat.pl/aukcja56_fdsfsd.html</AdresURL>
    <Kategoria>Świnie</Kategoria>
    <SubKategoria>Inne</SubKategoria>
    <Kraj>Wszystkie Kraje Swiata</Kraj>
    <Cena>0</Cena>
    <Waluta>Euro</Waluta>
    <TypAukcji>0</TypAukcji>
    <UzytkownikID>1</UzytkownikID>
   </Advert>    
</Ogloszenia>

Dodawanie Ogłoszeń

Api systemu pozwala również na dodawanie ogłoszeń. Dodawanie odbywa się na zasadzie przesłania odpowiedniego dokumentu XML lub formularza POST na adres skryptu nasluchującego API: 

// W przypadku zapytań poprzez XML
http://aukcjezwierzat.pl/api/addDataByXML.php

// W przypadku zapytań poprzez POST
http://aukcjezwierzat.pl/api/addDataByPOST.php
W przypadku błędnej autoryzacji w zależności od formy błędu system zwróci następujące komunikaty:

ERR001: Auth Error - W przypadku awarii systemu autoryzacji
ERR002: Auth Timeout - W przypadku przekroczenia czasu potwierdzenia autoryzacji
ERR003: Auth Deny - W przypadku zablokowania klucza użytkownika
ERR004: Wrong Key - W przypadku podania niewłaściwego klucza
ERR005: Key Auth Timeout Exceeded - W przypadku próby autoryzacji 10 klucz w ciągu 60sek. Czas trwania 60min

Struktura zapytania
Zapytanie powinno być kierowane w jednej z dwóch dostępnych form (Formularz POST, Dokument XML). Poniższa tabelka przedstawia parametry, które można wysyłać w zpaytaniu do systemu. Parametry te pozwalają filtrować wyniki w zależności od warunków, które państwa interesują.

Parametr Domyślnie Dopuszczalne Opis
ApiKey 0 32 znakowy klucz Klucz Api wygenerowany w systemie odpowiada za weryfikację przesyłanych danych
ApiHash Pusta Wartość Znakowa Unikalny identyfikator ogloszenia. Każde ogłoszenie powinno zawierać unikalny parametr w tym polu. Może to być na przykład numer ogłoszenia z systemu użytkownika
BuySell 0 0,1
0 - Ogłoszenie sprzedaży
1 - Ogłoszenie kupna
Kategoria 0 0 do 21 Kategoria określa gatunek wyszukiwanych zwierząt. Wartość domyślna jednocześnie określa dowolny gatunek

Lista Gatunków wraz z kodami

SubKategoria 0 od 0 do 1071 Kategoria określa rase wyszukiwanych zwierząt. Jest ściśle połączona z Kategorią. Wybór Subkategorii która nie wiąże się z kategorią spowoduje wystąpienie błedu i zapytanie nie zostanie wykonane. Należy więć ściśle określić Rasę, która jest definitywnie przypisana do gatunku. Poniżej znajduje się spis ras

Lista ras wraz z kodami

Sex 0 0 do 4 Płeć zwierząt. W zależności od kategorii okreśelnia płci są charakterystyczne. Podstawowy podział wygląda następująco

1 - Samica
2 - Samica
Dla Koni
1 - Ogier 2 - Klacz 3 - Wałach

Dla Krów
1 - Krowa 2 - Byk 3 - Jałówka

Dla Świń
1 - Samiec 2 - Samica

Dla Psów
1 - Pies 2 - Suka

AdvertType 0 0 Parametr określa rodzaj ogłoszenia, które chcemy pobrać

0 - Ogłoszenie

Country 4 od 1 do 250, 666 Określa kraj na który przeznaczone jest ogłoszenie.

4 - Dowolne/Wszystkie kraje świata
666 - Unia Europejska ;]
1 do 250 Lista krajów wraz z kodami

Tytul Wymagana Ciąg znaków Tytul ogłoszenia to ciąg nie przekraczający 255 znaków

Np: Wartość "To jest tytul"

Opis Wymagana Ciąg znaków Opis ogłoszenia to ciąg znaków nie przekraczając 20 000 znaków

Np: Wartość "To jest opis"

DataUrodzenia Pusta RRRR-MM-DD Wartość określa Date Urodzenia zwierzącia

RRRR-MM-DD Rok - Miesiąc - Dzień

Wiek 0 od 0 do 800 Wartość określa wiek w miesiącach

0 - Wiek nie jest ważny

Typ Pusty od 0 do 5 Wartość określa Typ w zależności od rodzaju dodawanego ogłoszenia

Dla Krów
1 - Mleczny 2 - Mięsny 3 - Mieszany

Dla Koni
1 - Rekreacja 4 - Skoki 7 - Ujeżdzanie 9 - WKKW 2 - Powożenie 5 - Wyścigi 8 - Western 10 - Hipoterapia 3 - Hodowla 6 - Rzeźne

Dla Świń
1 - Hodowla 2 - Rzeź

Dla Gołebi
1 - Barwne 2 - Brodawczaki 3 - Dęte 4 - Kuraki 5 - Lotne 6 - Mewki 7 - Strukturalne 8 - Turkoty 9 - Uformowane 10 - Inna

Dla Innych
1 - Rasowy 2 - Mieszany

Wydajność Pusta 0 do 15 Dla krów

Wydajność określa poziom pomnożony przez 1000 w %
MinBia Pusta 0 do 15 Dla krów

Minimalny procent Białka w mleku w procentach.
Cielność Pusta 0 do 9 Dla krów

Określa cielność krowy w miesiącach
DokVet 0 0 do 2 0 - Wymagane
1 - Nie wymagane
2 - Nie ważne
DokHod 0 0 do 2 0 - Wymagane
1 - Nie wymagane
2 - Nie ważne
Wymiary Pusta Ciąg do 30zn Wartość określająca wymiary zwierzęcia
Waga Pusta 0 do 5000 Określa wagę zwierzęcia
Maść Pusta 0 do 30 Dla koni

1 - Kasztanowata
2 - Gniada
3 - Kara
4 - Biała
5 - Siwa
6 - Bułana
7 - Izabelowata (Palomino)
8 - Myszata
9 - Dereszowata
10 - Srokata (Pinto)
11 - Tarantowata
12 - Inna


Dla Gołebi

1 - Mieszana
2 - Niebieski
3 - Niebieski nakrapiany
4 - Ciemny
5 - Czarny
6 - Czerwony
7 - Czerwony nakrapiany
8 - Czerwony
9 - Czerwony nakrapiany
10 - Płowy
11 - Biały
12 - Pstryk
13 - Szpak
14 - Niebieski pstry
15 - Niebieski nakrapiany pstry
16 - Nakrapiany pstry
17 - Ciemny nakrapiany pstry
18 - Ciemny pstry
19 - Czarny pstry
20 - Czerwony pstry
21 - Płowy pstry
22 - Szpak pstry
23 - Ciemny szpak
24 - Czerwony szpak
25 - Inna
Cena 0 INT Cena w formacie Double
Waluta 0 0,1 1 - Euro
2 - Złoty
3 - Dolar Amerykański
4 - Funt Brytyjski
Transport 0 0,1,2 0 - Odbiór osobisty
1 - Transport zapewnia sprzedawca
2 - Transport zapewnia kupujący
Liczba 0 INT Określa Liczbe całkowitą za całą Cenę wyrażaną w jednostkach ( np 1. jed Sztuk, ton, kilogramów, stad )
Jednostka 0 0,1,2,3 0 - Sztuki
1 - Kilogramy
2 - Tony
3 - Stada
Debug 0 0,1 Tryb debugowania zwraca zamiast wartości logicznej komunikaty systemowe. W przypadku gdy proces autoryzacji i zapytania przebiegł prawidłowo system zwraca odpowiedź OK. W wypadku błędów Debug zwraca konkretne elementy, które nie przeszły weryfikacji.




Ważne fakty dotyczące dodawania
Domyślnymi danymi kontaktowymi są dane użytkownika dla którego zostało wygenerowane API. W takim wypadku nie trzeba podawać znaczników odnośnie kontaktu. Jeżeli jednak chcemy umieścić dane kontaktowe do zapytania należy/można dołączyć następujące parametry:

Parametr Domyślnie Dopuszczalne Opis
ContactName Pusta CHAR Określa Imię kontaktu
ContactSName Pusta CHAR Określa Nazwisko kontaktu
ContactStreet Pusta CHAR Określa Ulicę
ContactStreetNr Pusta CHAR Określa Numer ulicy
ContactStreetFlat Pusta CHAR Określa Numer domu
ContactCity Pusta CHAR Określa Miasto
ContactPostcode Pusta CHAR Określa kod pocztowy
ContactTel Pusta CHAR Określa Telefon domowy
ContactTelMob Pusta CHAR Określa Telefon Komórkowy
ContactCountry Pusta INT Kod kraju przygporządkowany na liście identyfikatorów pod adresem:
Lista krajów wraz z kodami
ContactEmail Pusta CHAR Określa Email


Poprawna weryfikacja danych zwróci komunikat 

OK

Jeżeli, któryś z parametrów nie przeszedł weryfikacji lub jest zduplikowany w nieodpowiednim miejscu API zwróci
ERROR z wyjaśnieniem błędnego parametru.