Една интеграция. Всички имоти.

Бърз старт

1. Администраторът създава токен, свързан с конкретна агенция.
2. Партньорът проверява връзката чрез GET /api/v1/partner/me.
3. Изпраща една обява или пакет до 100 обяви.
4. Новите обяви се създават като чернова или се изпращат за модерация.

curl https://imoti-apartamenti.bg/api/v1/partner/me \
  -H "Authorization: Bearer iap_YOUR_TOKEN" \
  -H "Accept: application/json"

Сигурност

• Токенът се показва само веднъж; в базата се пази единствено SHA-256 хеш.
• Всеки токен е свързан с една агенция и права listings:read/listings:write.
• Лимит: 120 заявки в минута; пакетът съдържа максимум 100 обяви.
• Токен може да бъде отзован незабавно. Не го поставяйте в браузър, URL или Google таблица.
• XML/CSV се приемат само по HTTPS. Частни, локални и служебни IP адреси се блокират.
• Всяка пакетна операция получава request_id и се записва в журнал.

REST API

Една обява

POST /api/v1/partner/listings
Authorization: Bearer iap_YOUR_TOKEN
Content-Type: application/json

{
  "external_id": "AG-10492",
  "title": "Светъл тристаен апартамент в Лозенец",
  "description": "Описание с минимум 40 символа...",
  "deal_type": "sale",
  "property_type": "apartment",
  "location": "София",
  "district": "Лозенец",
  "price": 329000,
  "currency": "EUR",
  "area": 112.5,
  "rooms": 3,
  "images": ["https://partner.example/1.jpg"],
  "submit_for_review": true
}

Пакет

POST /api/v1/partner/listings/batch с тяло {"listings":[...]}. При частични грешки отговорът е HTTP 207 и съдържа номера на реда.

Архивиране

DELETE /api/v1/partner/listings/{external_id}. Липсата на обява в следващ пакет или XML не я изтрива автоматично.

Полета и типове

XML фид

Кодировка UTF‑8, максимален размер 10 MB. Коренът може да е <listings>, а елементът на обявата — <listing>, <property>, <offer> или <imot>. Полетата използват имената от таблицата по-горе.

<?xml version="1.0" encoding="UTF-8"?>
<listings>
  <listing>
    <external_id>AG-10492</external_id>
    <title>Светъл тристаен апартамент</title>
    <description>Подробно описание с минимум 40 символа...</description>
    <deal_type>sale</deal_type>
    <property_type>apartment</property_type>
    <location>София</location>
    <district>Лозенец</district>
    <price>329000</price>
    <currency>EUR</currency>
    <area>112.5</area>
    <images>
      <image>https://partner.example/1.jpg</image>
    </images>
  </listing>
</listings>

Google Sheets и Google Drive

1. Свалете CSV шаблона и качете заглавията като първи ред.
2. Един ред е една обява; external_id никога не се променя.
3. За Google Sheets включете „Всеки с връзката може да преглежда“ и поставете връзката към таблицата в админката.
4. За XML/CSV в Google Drive файлът също трябва да е публично достъпен. Частните файлове ще получат OAuth интеграция отделно.
5. Синхронизацията е на всеки час; има и бутон за ръчно стартиране.

Правила за синхронизация

• Ключът е двойката agency_id + external_id.
• Повторно подаване със същото ID обновява обявата и не създава дубликат.
• Нова обява не се публикува директно.
• Публикувана обява остава публикувана при безопасно обновяване; модераторът може да я свали.
• Пропуснат ред не означава изтриване. Използвайте DELETE за архивиране.
• Снимките трябва да са публични HTTPS URL адреси без cookies и временни подписи.

HTTP кодове и грешки