Integracja API
Udostępniamy naszym użytkownikom interfejs API, dzięki któremu można w zautomatyzowany sposób dodać większą ilość ogłoszeń do serwisu lub dokonywać eksportu ogłoszeń z serwisu partnerskiego.
Jeżeli masz dodatkowe pytania lub chcesz podzielić się uwagami - skontaktuj się z nami.
- Jak rozpocząc korzystanie z API?
- Przesyłanie zapytań
- Zwracane odpowiedzi
- Autoryzacja
- Jak dodać ogłoszenie za pomocą API?
- Pobieranie listy kategorii
- Pobieranie listy miast
- Jak dodać ogłoszenie Premium lub Wyróżnione?
- Jak dodać zdjęcia do ogłoszenia
- Wyświetlenie listy zdjęć dodanych do ogłoszenia
- Wyświetlenie zdjęcia dodanego do ogłoszenia
- Usunięcie pojedyńczego zdjęcia
- Usunięcie wszystkich zdjęć z ogłoszenia
- Edycja ogłoszenia
- Usunięcie ogłoszenia
- Sprawdzenie limitu konta
- Jak doładować konto?
Jak rozpocząc korzystanie z API?
Aby rozpocząć korzystanie z API należy wygenerować klucz API.
Klucz API jest unikalny dla każdego użytkownika i powinien być traktowany jak hasło do konta.
W celu wygenerowania klucza API przejdź na tę stronę.
Klucz API jest unikalny dla każdego użytkownika i powinien być traktowany jak hasło do konta.
W celu wygenerowania klucza API przejdź na tę stronę.
Przesyłanie zapytań
API zostało napisane według standardu REST i dostępne jest pod adresem https://api.oglaszamy24.pl/api/
Zarówno zapytania, jak i odpowiedzi przesyłane są za pomocą protokołu HTTPS.
API obsługuje 4 dostępne metody zapytań: POST, GET, PUT, DELETE.
W przypadku zapytań POST oraz PUT należy przesłać odpowiednie dane jako parametr "data". Przesyłane dane muszą być w formacie JSON a znaki muszą być zakodowane w standardzie UTF-8.
Zarówno zapytania, jak i odpowiedzi przesyłane są za pomocą protokołu HTTPS.
API obsługuje 4 dostępne metody zapytań: POST, GET, PUT, DELETE.
W przypadku zapytań POST oraz PUT należy przesłać odpowiednie dane jako parametr "data". Przesyłane dane muszą być w formacie JSON a znaki muszą być zakodowane w standardzie UTF-8.
Zwracane odpowiedzi
Po przesłaniu zapytania API zwróci odpowiedź w formacie JSON. Znaki zakodowane będą w formacie UTF-8.
W przypadku poprawnej odpowiedzi zwrócona odpowiedź zawierać będzie pola:
W przypadku błędnej odpowiedzi zwrócona odpowiedź zawierać będzie pola:
W przypadku poprawnej odpowiedzi zwrócona odpowiedź zawierać będzie pola:
- status - pole przyjmie wartość "ok"
- message - komunikat przesłany jako odpowiedź
- data - dane przesłane w odpowiedzi
{"status":"ok", "message":"hello", "data":{"method":"GET"}}
W przypadku błędnej odpowiedzi zwrócona odpowiedź zawierać będzie pola:
- status - pole przyjmie wartość "error"
- message - w polu znajdzie się komunikat z błędem
- code - kod błędu
{"status":"error", "message":"Niepoprawna komenda API.", "code":9}
Autoryzacja
Do każdego zapytania należy przesłać klucz API.
Klucz API musi zostać przesłany w nagłówku header zapytania jako parametr API-Key.
Przykładowe przesłanie klucza API za pomocą biblioteki CURL.
Przykładowe przesłanie klucza API za pomocą PHP:
W odpowiedzi serwer powinien zwrócić następującą odpowiedź:
Klucz API musi zostać przesłany w nagłówku header zapytania jako parametr API-Key.
Przykładowe przesłanie klucza API za pomocą biblioteki CURL.
curl -X GET -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/hello
Przykładowe przesłanie klucza API za pomocą PHP:
$api_key = 'TWOJ-KLUCZ-API';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/hello');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/hello');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
W odpowiedzi serwer powinien zwrócić następującą odpowiedź:
{"status":"ok", "message":"hello", "data":{"method":"GET"}}
Jak dodać ogłoszenie za pomocą API?
W celu dodania ogłoszenia za pomocą API należy wysłać dane ogłoszenia zakodowane w formacie JSON (kodowanie znaków w UTF-8).
Dane muszą zostać przesłane za pomocą metody POST jako parametr "data" na adres:
Dane mogą zawierać następujące pola:
Uwagi:
W przypadku ustawienia wartości parametru email_disabled jako 1 parametr telephone będzie obowiązkowy.
Domyślnie ogłoszenia będą dodawane z adresem email kontaktowym podanym podczas rejestracji konta. Jeżeli exportujesz ogłoszenia z serwisu partnerskiego lub chciałbyś dodawać ogłoszenia z różnymi adresami email - skontaktuj się z nami.
Parametr extra_info:
Parametr extra_info to tablica składająca się z pól info1...info12. W parametrze extra_info, w polach info1...info12, można podać dodatkowe informacje o sprzedawanej/wynajmowanej nieruchomości, samochodzie lub motocyklu.
Parametry info1...info12 nie są obowiązkowe.
Przykład w języku PHP pokazujący dodanie ogłoszenia:
W przypadku prawidłowego dodania ogłoszenia otrzymamy odpowiedź w formacie JSON, gdzie pole status zawierać będzie ok. Dodatkowo w odpowiedzi zostanie przesłane ID ogłoszenia, które zostało dodane.
ID to należy zachować ponieważ będzie ono potrzebne gdybyśmy chcieli zmodyfikować ogłoszenie lub je usunąć.
Przykładowa odpowiedź po poprawnym dodaniu ogłoszenia (ID nowego ogłoszenia to 123456):
W przypadku błędu pole status zawierać będzie wartość error a w polu message podany będzie komunikat o błędzie.
Przykład pokazujący dodanie tego samego ogłoszenia przy wykorzystaniu biblioteki CURL:
Dane muszą zostać przesłane za pomocą metody POST jako parametr "data" na adres:
https://api.oglaszamy24.pl/api/adverts
Dane mogą zawierać następujące pola:
Parametr
Obowiązkowy
Typ
Opis
title
obowiązkowy
string
Tytuł ogłoszenia. Minimalna długość to 5 znaków.
description
obowiązkowy
string
Treść ogłoszenia. Maksymalna długość to 4000 znaków. Nowe linie w opisie należy oddzielać za pomocą znacznika: \r\n
cat2_id
obowiązkowy
integer
ID podkategorii drugiego rzędu. Jeżeli podkategoria drugiego rzędu zawiera podkategorie trzeciego rzędu, należy wówczas określić ID kategorii trzeciego rzędu (cat3_id).
cat3_id
obowiązkowy
integer
ID podkategorii trzeciego rzędu. W przypadku gdy dana podkategoria drugiego rzędu nie posiada dalszych podkategorii wartość należy ustawić jako 0.
contact_name
obowiązkowy
string
Imie osoby kontaktowej
telephone
nieobowiązkowy
integer
Numer telefonu kontaktowego. Bez spacji. W przypadku kierunkowego wpisać 00 zamiast +.
email_disabled
nieobowiązkowy
integer
Dostępne wartości: 0 lub 1. W przypadku gdy nie chcemy otrzymywać odpowiedzi mailem a jedynie telefonicznie należy ustawić wartość parametru jako 1.
ad_sell
nieobowiązkowy
integer
Liczba całkowita określająca rodzaj oferty. Dostępne wartości: 1 lub 2. Jeżeli oferta dotyczy sprzedaży/wynajmu komuś/oferowania usług ustaw wartość parametru jako 1, jeżeli oferta dotyczy kupna/wynajmu od kogoś/poszukiwania usług ustaw wartość parametru jako 2. W przypadku pominięcia parametru, przyjmie on domyślną wartość 1.
price
nieobowiązkowy
integer
Cena w zł. Dotyczy przedmiotów wystawionych na sprzedaż lub oferowanch usług.
city_id
nieobowiązkowy
integer
ID miasta do którego chcemy dodać ogłoszenie (zobacz poniżej pobieranie listy miast). Jeżeli chcemy aby ogłoszenie wyświetlało się we wszystkich miastach, należy podać wartość 0.
ad_type
nieobowiązkowy
integer
rodzaj ogłoszenia (dostępne wartości: 1,2 lub 3). 1 - ogłoszenie bezpłatne, 2 - ogłoszenie premium, 3 - ogłoszenie wyróżnione. W przypadku dodawania ogłoszenia premium lub wyróżnionego należy uprzednio zakupić pakiet ogłoszeń Wyróżnionych lub Premium.
auto_renewal
nieobowiązkowy
integer
Dostępne wartości: 1 lub 0. Jeżeli chcemy aby ogłoszenie Premium lub Wyróżnionych było automatycznie ponawiane wówczas ustaw wartość parametru jako 1. Aby ogłoszenie mogło być automatycznie ponowione należy, w momencie ponawiania, posiadać aktywny pakiet ogłoszeń Wyróżnionych lub Premium.
extra_info
nieobowiązkowy
array
Dodatkowe informacje dostępne w przypadku niektórych kategorii takich jak nieruchomości czy motoryzacja (zobacz poniżej)
Uwagi:
W przypadku ustawienia wartości parametru email_disabled jako 1 parametr telephone będzie obowiązkowy.
Domyślnie ogłoszenia będą dodawane z adresem email kontaktowym podanym podczas rejestracji konta. Jeżeli exportujesz ogłoszenia z serwisu partnerskiego lub chciałbyś dodawać ogłoszenia z różnymi adresami email - skontaktuj się z nami.
Parametr extra_info:
Parametr extra_info to tablica składająca się z pól info1...info12. W parametrze extra_info, w polach info1...info12, można podać dodatkowe informacje o sprzedawanej/wynajmowanej nieruchomości, samochodzie lub motocyklu.
Parametry info1...info12 nie są obowiązkowe.
W przypadku wynajmu nieruchomości:
W przypadku sprzedaży nieruchomości - domu:
W przypadku sprzedaży nieruchomości - mieszkania:
W przypadku samochodu:
W przypadku motocykla:
Parametr
Typ
Opis
info1
integer
Liczba pokoi. 0 - nie określono
info2
integer
Liczba łazienek. 0 - nie określono
info3
integer
Na którym piętrze znajduje się mieszkanie (np. 1, 2, 3) . 0 - Parter, -1 - Nie określono
info4
integer
Czy jest podłączony internet.
Dostępne wartości:
0 - Nie określono
1 - Brak
2 - Jest
3 - Można podłączyć
Dostępne wartości:
0 - Nie określono
1 - Brak
2 - Jest
3 - Można podłączyć
info5
integer
Określa czy nieruchomość mogą wynająć osoby palące.
Dostępne wartości:
0 - Obojętnie
1 - Tak
2 - Nie
Dostępne wartości:
0 - Obojętnie
1 - Tak
2 - Nie
info6
integer
Dla ilu osób ma być wynajęta nieruchomość.
info7
integer
Metraż mieszkania (wartość w m2.)
info8
integer
Kaucja w zł.
info9
integer
Dodatkowe opłaty takie jak np. prąd, gaz. Kwota w zł.
info10
string
Dzielnica w której znajduje się nieruchomość.
info11
string
Ulica przy której położona jest nieruchomość.
info12
string
Od kiedy dostępne do wynajęcia. Data w formacie YYYY-MM-DD (rok-miesiac-dzień)
W przypadku sprzedaży nieruchomości - domu:
Parametr
Typ
Opis
info1
integer
Liczba pokoi. 0 - nie określono
info2
integer
Liczba łazienek. 0 - nie określono
info3
integer
Rodzaj ogrzewania
Dostępne wartości:
0 - Nie określono
1 - Miejskie
2 - Gazowe
3 - Elektryczne
4 - Węglowe
5 - Olejowe
6 - Inne
Dostępne wartości:
0 - Nie określono
1 - Miejskie
2 - Gazowe
3 - Elektryczne
4 - Węglowe
5 - Olejowe
6 - Inne
info4
integer
Typ budynku:
Dostępne wartości:
0 - Nie określono
1 - Wolnostojący
2 - Bliźniak
3 - Kamienica
4 - Willa
5 - Szeregowy
6 - Inny
Dostępne wartości:
0 - Nie określono
1 - Wolnostojący
2 - Bliźniak
3 - Kamienica
4 - Willa
5 - Szeregowy
6 - Inny
info5
integer
Liczba pięter. 0 - nie określono, 1 - dom parterowy
info6
integer
Materiał jaki zastosowano do budowy.
Dostępne wartości:
0 - Nie określono
1 - Cegła
2 - Pustak
3 - Płyta
4 - Gazobeton
5 - Bloczki
6 - Drewno
7 - Inny
Dostępne wartości:
0 - Nie określono
1 - Cegła
2 - Pustak
3 - Płyta
4 - Gazobeton
5 - Bloczki
6 - Drewno
7 - Inny
info7
integer
Metraż (wartość w m2.)
info8
integer
Rok budowy (YYYY, np. 1995)
info10
string
Dzielnica w której znajduje się nieruchomość.
info11
string
Ulica przy której położona jest nieruchomość.
W przypadku sprzedaży nieruchomości - mieszkania:
Parametr
Typ
Opis
info1
integer
Liczba pokoi. 0 - nie określono
info2
integer
Liczba łazienek. 0 - nie określono
info3
integer
Rodzaj ogrzewania
Dostępne wartości:
0 - Nie określono
1 - Miejskie
2 - Gazowe
3 - Elektryczne
4 - Węglowe
5 - Olejowe
6 - Inne
Dostępne wartości:
0 - Nie określono
1 - Miejskie
2 - Gazowe
3 - Elektryczne
4 - Węglowe
5 - Olejowe
6 - Inne
info4
integer
Na którym piętrze znajduje się mieszkanie (np. 1, 2, 3) . 0 - Parter, -1 - Nie określono
info5
integer
Określa materiał jaki zastosowano do budowy.
Dostępne wartości:
0 - Nie określono
1 - Cegła
2 - Pustak
3 - Płyta
4 - Gazobeton
5 - Bloczki
6 - Drewno
7 - Inny
Dostępne wartości:
0 - Nie określono
1 - Cegła
2 - Pustak
3 - Płyta
4 - Gazobeton
5 - Bloczki
6 - Drewno
7 - Inny
info7
integer
Metraż mieszkania (wartość w m2.)
info10
string
Dzielnica w której znajduje się nieruchomość.
info11
string
Ulica przy której położona jest nieruchomość.
W przypadku samochodu:
Parametr
Typ
Opis
info1
integer
Typ pojazdu
Dostępne wartości:
0 - Nie określono
1 - Sedan/Limuzyna
2 - Hatchback
3 - Kombi
4 - Van
5 - Kabriolet
6 - Suv/Terenowy
7 - Pick-up
8 - Inny
Dostępne wartości:
0 - Nie określono
1 - Sedan/Limuzyna
2 - Hatchback
3 - Kombi
4 - Van
5 - Kabriolet
6 - Suv/Terenowy
7 - Pick-up
8 - Inny
info2
integer
Typ silnika
Dostępne wartości:
0 - Nie określono
1 - Benzyna
2 - Benzyna+Gaz
3 - Diesel
4 - Hybryda
5 - Elektryczny
6 - CNG
7 - Inny
Dostępne wartości:
0 - Nie określono
1 - Benzyna
2 - Benzyna+Gaz
3 - Diesel
4 - Hybryda
5 - Elektryczny
6 - CNG
7 - Inny
info3
integer
Liczba drzwi
Dostępne wartości:
0 - Nie określono
1 - 2/3
2 - 4/5
3 - 6/7
Dostępne wartości:
0 - Nie określono
1 - 2/3
2 - 4/5
3 - 6/7
info4
integer
Skrzynia biegów
Dostępne wartości:
0 - Nie określono
1 - Manualna
2 - Automatyczna
3 - Półautomatyczna
Dostępne wartości:
0 - Nie określono
1 - Manualna
2 - Automatyczna
3 - Półautomatyczna
info5
integer
Określa czy pojazd uszkodzony. Wartości: 1 - nie, 2 - tak, 0 - nie określono
info6
integer
Klimatyzacja. Wartości: 1 - jest, 2 - brak, 0 - nie określono
info7
integer
Rok produkcji samochodu (YYYY, np. 2014). 0 - Nie określono
info8
integer
Pojemność silnika
Przykładowe wartości:
Wartość parametru: 90 - oznacza 0,9 litra
Wartość parametru: 100 - oznacza 1,0 litra
Wartość parametru: 110 - oznacza 1,1 litra
Wartość parametru: 120 - oznacza 1,2 litra
Przykładowe wartości:
Wartość parametru: 90 - oznacza 0,9 litra
Wartość parametru: 100 - oznacza 1,0 litra
Wartość parametru: 110 - oznacza 1,1 litra
Wartość parametru: 120 - oznacza 1,2 litra
info9
integer
Dotychczasowy przebieg w km
W przypadku motocykla:
Parametr
Typ
Opis
info1
integer
Określa czy motocykl jest uszkodzony. Wartości: 0 - nie określono, 1 - nie , 2 - tak
info2
integer
Typ silnika
Dostępne wartości:
0 - Nie określono
1 - Benzyna
2 - Benzyna+Gaz
3 - Diesel
4 - Hybryda
5 - Elektryczny
6 - CNG
7 - Inny
Dostępne wartości:
0 - Nie określono
1 - Benzyna
2 - Benzyna+Gaz
3 - Diesel
4 - Hybryda
5 - Elektryczny
6 - CNG
7 - Inny
info7
integer
Rok produkcji (format YYYY, np. 1995). 0 - Nie określono.
info8
integer
Pojemność silnika w cm3
Przykładowe wartości:
Wartość parametru: 90 - oznacza 90 cm3
Wartość parametru: 100 - oznacza 100 cm3
Wartość parametru: 110 - oznacza 110 cm3
Wartość parametru: 120 - oznacza 120 cm3
Przykładowe wartości:
Wartość parametru: 90 - oznacza 90 cm3
Wartość parametru: 100 - oznacza 100 cm3
Wartość parametru: 110 - oznacza 110 cm3
Wartość parametru: 120 - oznacza 120 cm3
info9
integer
Dotychczasowy przebieg w km.
info10
string
Określa wersji konkretnego modelu.
Przykład w języku PHP pokazujący dodanie ogłoszenia:
$data = array();
$data['title'] = 'Duże mieszkanie do wynajęcia';
$data['description'] = "Do wynajęcia dla 2 osób, dwupokojowe mieszkanie w Krakowie.\r\n";
$data['description'] .= 'Mieszkanie jest całkowicie umeblowane niedawno wyremontowane.';
$data['price'] = 2100; // cena w zł
$data['cat1_id'] = 2; // nieruchomości
$data['cat2_id'] = 24; // wynajem
$data['cat3_id'] = 97; // mieszkania
$data['ad_sell'] = 1;
$data['city_id'] = 2; // Kraków
$data['telephone'] = 5012012013;
$data['contact_name'] = 'Jan Kowalski';
$data['ad_type'] = 1; // ogłoszenie standardowe
$data['auto_renewal'] = 0;
$data['extra_info'] = array();
$data['extra_info']['info1'] = 2; // dwupokojowe
$data['extra_info']['info2'] = 1; // jedna łazienka
$data['extra_info']['info3'] = 4; // piętro
$data['extra_info']['info4'] = 2; // internet
$data['extra_info']['info5'] = 0; // dla palących
$data['extra_info']['info6'] = 2; // dla 2 osob
$data['extra_info']['info7'] = 52; // metraż - 52m kw
$data['extra_info']['info8'] = 1200; // kaucja w zł
$data['extra_info']['info9'] = 1000; // dodatowe oplaty w zł
$data['extra_info']['info10'] = 'Stare miasto'; // dzielnica
$data['extra_info']['info11'] = 'Garncarska'; // ulica
$data['extra_info']['info12'] = '2019-03-21'; // wolne od
$data = json_encode($data);
$api_key = 'TWOJ-KLUCZ-API'; // wpisz tutaj swój klucz API
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('data' => $data)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$response = json_decode($response);
if ($response->status == 'ok') echo 'ID dodanego ogłoszenia to: '.$response->data->id;
else if ($response->status == 'error') echo 'Wystąpił problem podczas dodawania ogłoszenia: '.$response->message;
$data['title'] = 'Duże mieszkanie do wynajęcia';
$data['description'] = "Do wynajęcia dla 2 osób, dwupokojowe mieszkanie w Krakowie.\r\n";
$data['description'] .= 'Mieszkanie jest całkowicie umeblowane niedawno wyremontowane.';
$data['price'] = 2100; // cena w zł
$data['cat1_id'] = 2; // nieruchomości
$data['cat2_id'] = 24; // wynajem
$data['cat3_id'] = 97; // mieszkania
$data['ad_sell'] = 1;
$data['city_id'] = 2; // Kraków
$data['telephone'] = 5012012013;
$data['contact_name'] = 'Jan Kowalski';
$data['ad_type'] = 1; // ogłoszenie standardowe
$data['auto_renewal'] = 0;
$data['extra_info'] = array();
$data['extra_info']['info1'] = 2; // dwupokojowe
$data['extra_info']['info2'] = 1; // jedna łazienka
$data['extra_info']['info3'] = 4; // piętro
$data['extra_info']['info4'] = 2; // internet
$data['extra_info']['info5'] = 0; // dla palących
$data['extra_info']['info6'] = 2; // dla 2 osob
$data['extra_info']['info7'] = 52; // metraż - 52m kw
$data['extra_info']['info8'] = 1200; // kaucja w zł
$data['extra_info']['info9'] = 1000; // dodatowe oplaty w zł
$data['extra_info']['info10'] = 'Stare miasto'; // dzielnica
$data['extra_info']['info11'] = 'Garncarska'; // ulica
$data['extra_info']['info12'] = '2019-03-21'; // wolne od
$data = json_encode($data);
$api_key = 'TWOJ-KLUCZ-API'; // wpisz tutaj swój klucz API
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('data' => $data)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$response = json_decode($response);
if ($response->status == 'ok') echo 'ID dodanego ogłoszenia to: '.$response->data->id;
else if ($response->status == 'error') echo 'Wystąpił problem podczas dodawania ogłoszenia: '.$response->message;
W przypadku prawidłowego dodania ogłoszenia otrzymamy odpowiedź w formacie JSON, gdzie pole status zawierać będzie ok. Dodatkowo w odpowiedzi zostanie przesłane ID ogłoszenia, które zostało dodane.
ID to należy zachować ponieważ będzie ono potrzebne gdybyśmy chcieli zmodyfikować ogłoszenie lub je usunąć.
Przykładowa odpowiedź po poprawnym dodaniu ogłoszenia (ID nowego ogłoszenia to 123456):
{"status":"ok", "message":"Ogłoszenie zostało dodane", "data":{"id":"123456"}}
W przypadku błędu pole status zawierać będzie wartość error a w polu message podany będzie komunikat o błędzie.
Przykład pokazujący dodanie tego samego ogłoszenia przy wykorzystaniu biblioteki CURL:
curl -H 'API-Key: TWOJ-KLUCZ-API' --data 'data={"title":"Du\u017ce mieszkanie do wynaj\u0119cia","description":"Do wynaj\u0119cia dla 2 os\u00f3b, dwupokojowe mieszkanie w Krakowie.\r\nMieszkanie jest ca\u0142kowicie umeblowane niedawno wyremontowane.", "price":2100, "cat1_id":2, "cat2_id":24, "cat3_id":97, "ad_sell":1, "city_id":2, "telephone":5012012013, "contact_name":"Jan Kowalski", "ad_type":1, "auto_renewal":0, "extra_info":{"info1":2, "info2":1,"info3":4, "info4":2,"info5":0, "info6":2, "info7":52, "info8":1200, "info9":1000, "info10":"Stare miasto", "info11":"Garncarska", "info12":"2019-03-21"}}' https://api.oglaszamy24.pl/api/adverts
Pobieranie listy kategorii
W celu pobrania listy kategorii należy wysłać zapytanie GET pod adres:
W odpowiedzi otrzymamy listę dostępnych kategorii oraz podkategorii wraz z parametrami cat1_id, cat2_id, cat3_id.
Przykład z użyciem biblioteki CURL.
https://api.oglaszamy24.pl/api/categories
W odpowiedzi otrzymamy listę dostępnych kategorii oraz podkategorii wraz z parametrami cat1_id, cat2_id, cat3_id.
Przykład z użyciem biblioteki CURL.
curl -X GET -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/categories
Pobieranie listy miast
W celu pobrania listy kategorii należy wysłać zapytanie GET pod adres:
W odpowiedzi otrzymamy listę dostępnych miast do których można dodać ogłoszenia wraz z ID miasta (parametr city_id).
Przykład z użyciem biblioteki CURL:
Standardowo wszystkie ogłoszenia dodawane za pomocą API zamieszczane są na okres 2 tygodni. Wcześniejsze usunięcie ogłoszenia możliwe jest za pomocą odpowiedniej komendy API.
https://api.oglaszamy24.pl/api/cities
W odpowiedzi otrzymamy listę dostępnych miast do których można dodać ogłoszenia wraz z ID miasta (parametr city_id).
Przykład z użyciem biblioteki CURL:
curl -X GET -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/cities
Standardowo wszystkie ogłoszenia dodawane za pomocą API zamieszczane są na okres 2 tygodni. Wcześniejsze usunięcie ogłoszenia możliwe jest za pomocą odpowiedniej komendy API.
Jak dodać ogłoszenie Premium lub Wyróżnione?
W celu dodania ogłoszenia Premium lub Wyróżnionego za pomocą API należy uprzednio zakupić odpowiedni pakiet ogłoszeń a następnie dodając ogłoszenie z użyciem API w paramerze ad_type należy przesłać wartość: 2 - jeżeli chcemy dodać ogłoszenie Wyróżnione - lub 3 jeżeli chcemy dodać ogłoszenie Premium.
Jak dodać zdjęcia do ogłoszenia?
Istnieją dwie metody dodania zdjęć do ogłoszenia.
1. Metoda pierwsza - przesłanie listy zdjęć.
W celu dodania zdjęć do ogłoszenia należy przesłać zapytanie metodą POST pod adres URL:
gdzie {id_ogloszenia} to ID ogłoszenia do którego chcemy dodać zdjęcia.
Zapytanie musi zawierać parametr POST "data" z danymi zakodowanymi w formacie JSON.
W parametrze POST data należy przesłać zmienną images zawierającą listę adresów URL ze zdjęciami w formacie JPG. Zdjęcia muszą być dostępne pod wskazanymi adresami URL tak aby nasze interfejs API mógł je pobrać. Maksymalny rozmiar pojedyńczego zdjęcia to 2 MB.
Przykładowa wartość parametru images zawierająca 2 zdjęcia:
Podając adres do zdjęcia należy podać pełny adres URL rozpoczynający sie od http lub https.
Przykładowo: http://www.mojadomena.pl/zdjecia/zdjecie1.jpg
Do ogłoszeń bezpłatnych można dodać maksymalnie 2 zdjęcia. Natomiast do ogłoszen Premium lub Wyróżnionych można dodać maksymalnie 10 zdjęć.
Przykład dla języka PHP:
2. Druga metoda - przesłanie plików ze zdjęciami.
W celu dodania zdjęć do ogłoszenia należy przesłać zapytanie metodą POST pod adres URL:
gdzie {id_ogloszenia} to ID ogłoszenia do którego chcemy dodać zdjęcia.
W parametrze POST data należy przesłać plik ze zdjęciem w formacje JPG.
Przykład z wykorzystaniem biblioteki CURL:
Aby dodać kilka zdjęć do ogłoszenia należy wysłać osobne zapytania dla każdego zdjęcia.
W przypadku porawnego dodania zdjęcia w odpowiedzi pole status zawierać będzie wartość ok. Natomiast w przypadku błędu pole status przyjmie wartość error a w polu message zawarta będzie wiadomość z błędem.
Przykładowa poprawna odpowiedź:
- Pierwsza metoda polega na przesłaniu listy adresów URL, pod którymi dostępne są zdjęcia.
- Druga metoda polega na bezpośrednim przesłaniu plików ze zdjęciami na adres serwera API.
1. Metoda pierwsza - przesłanie listy zdjęć.
W celu dodania zdjęć do ogłoszenia należy przesłać zapytanie metodą POST pod adres URL:
https://api.oglaszamy24.pl/api/adverts/{id_ogloszenia}/images
gdzie {id_ogloszenia} to ID ogłoszenia do którego chcemy dodać zdjęcia.
Zapytanie musi zawierać parametr POST "data" z danymi zakodowanymi w formacie JSON.
W parametrze POST data należy przesłać zmienną images zawierającą listę adresów URL ze zdjęciami w formacie JPG. Zdjęcia muszą być dostępne pod wskazanymi adresami URL tak aby nasze interfejs API mógł je pobrać. Maksymalny rozmiar pojedyńczego zdjęcia to 2 MB.
Przykładowa wartość parametru images zawierająca 2 zdjęcia:
{"images":["adres_url_do_zdjecia1.jpg", "adres_url_do_zdjecia2.jpg"]}
Podając adres do zdjęcia należy podać pełny adres URL rozpoczynający sie od http lub https.
Przykładowo: http://www.mojadomena.pl/zdjecia/zdjecie1.jpg
Do ogłoszeń bezpłatnych można dodać maksymalnie 2 zdjęcia. Natomiast do ogłoszen Premium lub Wyróżnionych można dodać maksymalnie 10 zdjęć.
Przykład dla języka PHP:
$api_key = 'TWOJ-KLUCZ-API';
$id = 12345;// ID ogloszenia
$data['images'] = array( 'http://www.mojadomena.pl/zdjecie1.jpg', 'http://www.mojadomena.pl/zdjecie2.jpg' );
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/'. $id. '/images');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('data' => json_encode($data))));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$id = 12345;// ID ogloszenia
$data['images'] = array( 'http://www.mojadomena.pl/zdjecie1.jpg', 'http://www.mojadomena.pl/zdjecie2.jpg' );
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/'. $id. '/images');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('data' => json_encode($data))));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
2. Druga metoda - przesłanie plików ze zdjęciami.
W celu dodania zdjęć do ogłoszenia należy przesłać zapytanie metodą POST pod adres URL:
https://api.oglaszamy24.pl/api/adverts/{id_ogloszenia}/images/upload
gdzie {id_ogloszenia} to ID ogłoszenia do którego chcemy dodać zdjęcia.
W parametrze POST data należy przesłać plik ze zdjęciem w formacje JPG.
Przykład z wykorzystaniem biblioteki CURL:
curl -H 'API-Key: TWOJ-KLUCZ-API' -F 'data=@/home/images/zdjecie1.jpg' https://api.oglaszamy24.pl/api/adverts/12345/images/upload
Aby dodać kilka zdjęć do ogłoszenia należy wysłać osobne zapytania dla każdego zdjęcia.
W przypadku porawnego dodania zdjęcia w odpowiedzi pole status zawierać będzie wartość ok. Natomiast w przypadku błędu pole status przyjmie wartość error a w polu message zawarta będzie wiadomość z błędem.
Przykładowa poprawna odpowiedź:
{"status":"ok", "message":"Zdjęcie zostało dodane."}
Wyświetlenie listy zdjęć dodanych do ogłoszenia
W celu otrzymania listy zdjęć, które zostały dodane do ogłoszenia, należy wysłać zapytanie metodą GET pod adres:
W odpowiedzi otrzymamy listę ID zdjęć.
Przykładowe zapytanie by otrzymać listę zdjęć dodanych do ogłoszenia o ID 12345 z użyciem biblioteki CURL:
Powyższy przykład dla języka PHP:
https://api.oglaszamy24.pl/api/adverts/{id_ogłoszenia}/images
W odpowiedzi otrzymamy listę ID zdjęć.
Przykładowe zapytanie by otrzymać listę zdjęć dodanych do ogłoszenia o ID 12345 z użyciem biblioteki CURL:
curl -X GET -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/adverts/12345/images
Powyższy przykład dla języka PHP:
$api_key = 'TWOJ-KLUCZ-API';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345/images');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345/images');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
Wyświetlenie zdjęcia dodanego do ogłoszenia
W celu wyświetlenia konkretnego zdjęcia należy wysłać zapytanie metodą GET pod adres:
W odpowiedzi wyświetlone zostanie zdjęcie w formacie JPG.
https://api.oglaszamy24.pl/api/adverts/{id_ogłoszenia}/images/{id_zdjęcia}
W odpowiedzi wyświetlone zostanie zdjęcie w formacie JPG.
Usunięcie pojedyńczego zdjęcia
W celu usunięcia pojedyńczego zdjęcia, należy wysłać zapytanie metodą DELETE pod adres:
Przykładowe usunięcie zdjęcia o ID 789 z ogłoszenia o ID 12345 przy użyciu biblioteki CURL.
Powyższy przykład dla języka PHP:
W odpowiedzi poprawnego usunięcia zdjęcia w odpowiedzi serwer powinien zwrócić następującą odpowiedź:
W przypadku błędu zostanie zwrócona odpowiedź z komunikatem o błędzie.
https://api.oglaszamy24.pl/api/adverts/{id_ogłoszenia}/images/{id_zdjecia}
Przykładowe usunięcie zdjęcia o ID 789 z ogłoszenia o ID 12345 przy użyciu biblioteki CURL.
curl -X DELETE -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/adverts/12345/images/789
Powyższy przykład dla języka PHP:
$api_key = 'TWOJ-KLUCZ-API';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345/images/789');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345/images/789');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
W odpowiedzi poprawnego usunięcia zdjęcia w odpowiedzi serwer powinien zwrócić następującą odpowiedź:
{"status":"ok","message":" Zdjęcie zostało usunięte."}
W przypadku błędu zostanie zwrócona odpowiedź z komunikatem o błędzie.
Usunięcie wszystkich zdjęć z ogłoszenia
W celu usunięcia wszystkich zdjęć z ogłoszenia, należy wysłać zapytanie metodą DELETE pod adres:
Przykładowe usunięcie wszystkich zdjęć z ogłoszenia o ID 12345 przy użyciu biblioteki CURL.
Powyższy przykład dla języka PHP:
W odpowiedzi poprawnego usunięcia zdjęcia w odpowiedzi serwer powinien zwrócić następującą odpowiedź:
W przypadku błędu zostanie zwrócona odpowiedź z komunikatem o błędzie.
https://api.oglaszamy24.pl/api/adverts/{id_ogłoszenia}/images
Przykładowe usunięcie wszystkich zdjęć z ogłoszenia o ID 12345 przy użyciu biblioteki CURL.
curl -X DELETE -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/adverts/12345/images
Powyższy przykład dla języka PHP:
$api_key = 'TWOJ-KLUCZ-API';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345/images');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345/images');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
W odpowiedzi poprawnego usunięcia zdjęcia w odpowiedzi serwer powinien zwrócić następującą odpowiedź:
{"status":"ok","message":" Zdjęcia zostały usunięte."}
W przypadku błędu zostanie zwrócona odpowiedź z komunikatem o błędzie.
Edycja ogłoszenia
W celu edycji ogłoszenia za pomocą API należy wysłać dane ogłoszenia zakodowane w formacie JSON (kodowanie znaków w UTF-8).
Dane muszą zostać przesłane za pomocą metody PUT jako parametr "data" na adres:
Gdzie {id_ogłoszenia} to ID ogłoszenia, które chcemy zmodyfikować.
Dane ogłoszenia przesyłane jako parametr data są takie same jak w przypadku dodawania ogłoszenia.
Jeżeli chcesz zaktualizować zdjęcia do ogłoszenia, należy usunąć uprzednio dodane zdjęcia za pomocą odpowiedniej komendy API.
Dane muszą zostać przesłane za pomocą metody PUT jako parametr "data" na adres:
https://api.oglaszamy24.pl/api/adverts/{id_ogłoszenia}
Gdzie {id_ogłoszenia} to ID ogłoszenia, które chcemy zmodyfikować.
Dane ogłoszenia przesyłane jako parametr data są takie same jak w przypadku dodawania ogłoszenia.
Jeżeli chcesz zaktualizować zdjęcia do ogłoszenia, należy usunąć uprzednio dodane zdjęcia za pomocą odpowiedniej komendy API.
Usunięcie ogłoszenia
W celu usunięcia ogłoszenia, należy wysłać zapytanie metodą DELETE pod adres:
Przykładowe usunięcie ogłoszenia o ID 12345 przy użyciu biblioteki CURL.
Powyższy przykład dla języka PHP:
W odpowiedzi , w przypadku poprawnego wykonania zapytania serwer powinien zwrócić następującą odpowiedź:
W przypadku błędu zostanie zwrócona odpowiedź z komunikatem o błędzie.
https://api.oglaszamy24.pl/api/adverts/{id_ogłoszenia}
Przykładowe usunięcie ogłoszenia o ID 12345 przy użyciu biblioteki CURL.
curl -X DELETE -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/adverts/12345
Powyższy przykład dla języka PHP:
$api_key = 'TWOJ-KLUCZ-API';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.oglaszamy24.pl/api/adverts/12345');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API-Key: '.$api_key));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close ($ch);
W odpowiedzi , w przypadku poprawnego wykonania zapytania serwer powinien zwrócić następującą odpowiedź:
{"status":"ok", "message":"Ogłoszenie zostało usunięte."}
W przypadku błędu zostanie zwrócona odpowiedź z komunikatem o błędzie.
Sprawdzenie limitu konta
W celu sprawdzenia ile jeszcze ogłoszeń możemy dodać poprzez API, należy wysłać zapytanie metodą GET pod adres:
Przykładowe zapytanie przy użyciu biblioteki CURL.
W odpowiedzi, w przypadku poprawnego wykonania, serwer zwróci odpowiedź w formacje JSON, gdzie zmienna balance_standard, zawierać będzie ilość standardowych ogłoszeń, które możemy jeszcze dodać bez doładowywania konta. Ponadto odpowiedź zawierać będzie pola balance_bold - ilość ogłoszeń wyróżnionych, które możemy dodać oraz balance_premium - ilość ogłoszeń premium, które możemy dodać.
Przykładowa odpowiedź:
Co oznacza, iż nasze saldo na koncie pozwala na dodanie jeszcze 175 ogłoszeń, a po przekroczeniu tego limitu konieczne będzie doładowanie konta.
https://api.oglaszamy24.pl/api/account
Przykładowe zapytanie przy użyciu biblioteki CURL.
curl -X GET -H 'API-Key: TWOJ-KLUCZ-API' https://api.oglaszamy24.pl/api/account
W odpowiedzi, w przypadku poprawnego wykonania, serwer zwróci odpowiedź w formacje JSON, gdzie zmienna balance_standard, zawierać będzie ilość standardowych ogłoszeń, które możemy jeszcze dodać bez doładowywania konta. Ponadto odpowiedź zawierać będzie pola balance_bold - ilość ogłoszeń wyróżnionych, które możemy dodać oraz balance_premium - ilość ogłoszeń premium, które możemy dodać.
Przykładowa odpowiedź:
{"balance_standard":"175", "balance_bold":"0", "balance_premium":"15"}
Co oznacza, iż nasze saldo na koncie pozwala na dodanie jeszcze 175 ogłoszeń, a po przekroczeniu tego limitu konieczne będzie doładowanie konta.
Jak doładować konto?
W celu doładowania konta przejdź na stronę swojego konta.
Jeżeli masz dodatkowe pytania lub chcesz podzielić się uwagami - skontaktuj się z nami.
Poznan.Oglaszamy24.pl - Darmowe ogłoszenia Poznań. Dodaj bezpłatne ogłoszenia drobne!
INFORMACJE O SERWISIE
© 2024 Oglaszamy24.pl