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:
https://api.oglaszamy24.pl/api/adverts
Dane mogą zawierać następujące pola:
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
cat1_id
obowiązkowy
integer
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
nieobowiązkowy
string
Adres email
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
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)
images
nieobowiązkowy
array
Lista z adresami URL do zdjęć, które mają być dodane do ogłoszenia (
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 images:
W parametrze
images należy podać 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 (JSON):
{"images":["adres_url_do_zdjecia_1.jpg", "adres_url_do_zdjecia_1.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 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;
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
