Bazarok Partner API — інтеграція через OAuth 2.0

Версія 1 · Базова адреса: https://www.bazarok.ua · English version: partner_api_oauth.md

1. Підключення агентства (OAuth 2.0, authorization code)

1.1 Перенаправте агентство на Bazarok

GET https://www.bazarok.ua/oauth_authorize.php
    ?response_type=code
    &client_id=<client_id>
    &redirect_uri=https://<ваша-crm>/oauth/bazarok/callback   (точно як зареєстровано)
    &state=<випадкове значення, яке ваша CRM перевіряє при поверненні>
    [&code_challenge=<BASE64URL(SHA256(verifier))>&code_challenge_method=S256]   (PKCE, необов'язково)

вилин і працює один раз;

• відмовлено: ?error=access_denied&state=<state>.

1.2 Обмін коду (сервер — сервер)

POST https://www.bazarok.ua/oauth_token.php
Authorization: Basic base64(client_id:client_secret)      (або client_id / client_secret у тілі)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<той самий redirect_uri>[&code_verifier=<verifier>]

{ "access_token": "…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "…", "account_id": 123456 }

account_id — ідентифікатор акаунта агентства на Bazarok: зберігайте його разом із токенами агентства. У кожного агентства свої токени.

1.3 Оновлення токена

Access-токен діє 1 годину, refresh-токен — 1 рік. Refresh-токени змінюються: кожне оновлення повертає нову пару і робить попередній refresh-токен недійсним — завжди зберігайте новий.

POST /oauth_token.php        grant_type=refresh_token&refresh_token=<refresh_token>     (автентифікація клієнта як вище)

1.4 Відключення

POST /oauth_revoke.php       token=<access або refresh токен>        (автентифікація клієнта як вище)

Відкликає весь зв'язок між агентством і вашою CRM (усі його токени). Щоб підключитися знову, агентство має пройти крок 1.1. Той самий результат: DELETE /api/v1/connection з access-токеном. Помилки OAuth — за RFC 6749: {"error": "invalid_grant", "error_description": "…"}.

2. Загальні правила API

• Кожен запит: Authorization: Bearer <access-токен агентства>; тіло в JSON із Content-Type: application/json, UTF-8. Дати: YYYY-MM-DD HH:MM:SS, час сервера (Europe/Paris).
• Помилки: HTTP-статус + стабільний код (перевіряйте код, а не текст повідомлення):

{ "error": { "code": "validation_error", "message": "Some fields are missing or invalid.",
             "fields": { "price": "required, number > 0", "contact.phone": "invalid phone number: 12" } } }

оголошень агентства. |

вилину для агентства: зачекайте Retry-After секунд. |

2.1 Робота з сотнями агентств

ронізації.

3. Акаунт — GET /api/v1/me

{ "account_id": 123456, "name": "ESTATYQ", "email": "…", "phone": "…",
  "status": "trial",                       // trial | active | expired
  "trial_ends_at": "2026-12-07 10:00:00",
  "subscription": null,                    // або { "status": "active", "paid_until": "…" }
  "listings": { "active": 212, "allowed": 300 },
  "site": { "domain": "bazarok.ua", "country_code": "ua",
            "currencies": ["uah", "usd", "eur"],   // допустимі значення "currency" (перше — за замовчуванням)
            "land_units": ["сотка", "га"] } }      // допустимі значення "land_area_unit" (перше — за замовчуванням)

4. Локації

Місце розташування оголошення задається через city_id Bazarok (рекомендовано) або через назви city + region (українською чи російською, точно як на Bazarok).

• GET /api/v1/locations/cities?q=Київ → { "cities": [ { "city_id": 1, "name": "Київ", "name_ru": "Киев", "region": "Київська область", "region_ru": "…" } ] }
• GET /api/v1/locations/districts?city_id=1 → { "districts": [ { "district_id": 7, "name": "Печерський", "name_ru": "Печерский" } ] }

5. Оголошення

Публікація — POST /api/v1/listings → 201

{
  "external_id": "CRM-48213",
  "deal_type": "rent",                 // sale (продаж) | rent (оренда)
  "property_type": "apartment",        // apartment | room | house | land | commercial | garage
  "price": 18000, "currency": "uah",   // одна з site.currencies (GET /me) — для оренди ціна за місяць
  "description": "Світла 2-кімнатна квартира…",   // 10–10000 символів
  "rooms": 2, "area": 54.5, "living_area": 30,   // м²
  "land_area": null, "land_area_unit": "сотка",   // одиниця: одна з site.land_units (GET /me)
  "floor": 5, "floors_total": 9,
  "lift": true, "balcony": true, "new_building": false, "parking": false, "furnished": true,
  "city_id": 1, "district": "Печерський", "address": "вул. Лесі Українки, 10",
  "lat": 50.4301, "lon": 30.5402,
  "photos": [ "https://cdn.example.com/1.jpg", "https://cdn.example.com/2.jpg" ],   // до 15, публічні http(s) URL, перше = обкладинка
  "contact": {
    "name": "Іван",
    "phone": "0671234567,0501234567"
  }
}

Обов'язкові поля: external_id, deal_type, property_type, price, description, city_id (або city + region). Заголовок Bazarok формує сам із типу, кількості кімнат, площі та локації.

contact (необов'язково): рієлтор агентства, який веде це оголошення.

• name: до 100 символів.
• phone: обов'язкове всередині contact; від 1 до 5 номерів через кому ("0671234567,0501234567") або JSON-масив (["+380671234567", "0501234567"]); цифри, пробіли, + ( ) -, від 9 до 15 цифр у кожному номері.
• Відвідувачі, які натискають «Показати номер» в оголошенні, бачать перший номер та ім'я контакту; інші номери зберігаються і повертаються через API.
• Без contact показується телефон акаунта агентства.

Відповідь:

{ "listing": { "id": 9876543, "external_id": "CRM-48213", "status": "active",
               "url": "https://www.bazarok.ua/oholoshennya/…-9876543.html",
               "title": "Квартира 2-кімн. оренда Київ, Печерський – 54.5 м²", "photos_count": 2,
               "contact": { "name": "Іван", "phone": "0671234567,0501234567" },
               "updated_at": "2026-10-27 14:02:11" } }

status: active (на сайті) · expired (термін минув) · inactive (неактивне) · deleted (видалене).

Оновлення — PUT /api/v1/listings/{external_id} → 200

Статус — GET /api/v1/listings/{external_id} · Зняття — DELETE /api/v1/listings/{external_id}

Зняте оголошення можна опублікувати знову через POST з тим самим external_id.

6. З чого почати

1. Надішліть нам назву CRM, URI повернення; ми надішлемо client_id і client_secret.
2. Додайте для агентств кнопку «Підключити Bazarok» (1.1), обміняйте код (1.2), збережіть токени з account_id.
3. Зіставте ваші міста з city_id (GET /api/v1/locations/cities).
4. З тестовим агентством: опублікуйте оголошення, відкрийте отриманий url, оновіть його, зніміть.

Питання: contact@bazarok.ua