Публичный API Объявки

Публичный API даёт программный доступ к ядру Объявки: создание объектов недвижимости, загрузка фотографий и запуск генерации маркетингового набора (тексты под Авито/Циан/Telegram, PDF-презентация, картинки для соцсетей).

• Base URL: https://api.objavka.app/v1
• Формат: JSON, UTF-8 (фото передаются ссылками, не файлами).
• Доступ: только организации на тарифе Агентство.

Каждый запрос к /v1/* требует заголовок:

X-API-Key: ovk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Формат ключа: префикс ovk_ + случайные url-safe символы.
• На сервере хранится только sha256-хэш ключа — повторно секрет показать нельзя.
• Нет заголовка → 401. Неверный или отозванный ключ → 401. Тариф ниже Агентства → 403.

Ключи создаёт владелец или администратор организации в кабинете в разделе «Команда → API-ключи». Под капотом — служебные эндпоинты (работают по обычной сессии, а не по X-API-Key):

• Список: GET /api/v1/org/api-keys — без секрета, только префикс, имя и время последнего использования.
• Создать: POST /api/v1/org/api-keys — тело {"name": "..."}; ответ содержит поле key — показывается один раз.
• Отозвать: DELETE /api/v1/org/api-keys/{key_id} — отозванный ключ сразу даёт 401.

Лимит запросов — 60 запросов за 60 секунд на организацию (учитываются мутации: создание объекта, загрузка фото, запуск генерации). Превышение → 429. Заголовков X-RateLimit-* нет — при 429 сделайте паузу и повторите (рекомендуется экспоненциальный backoff).

Квота генераций — общий месячный пул организации. На тарифе Агентство квота безлимитна. Если пул исчерпан, списание идёт из активного пакета генераций; если и пакетов нет → 402. Создание объектов и загрузка фото квоту не расходуют — только запуск генерации.

Полный цикл: создать объект → добавить фото → запустить генерацию → дождаться результата. Цены — в копейках целым числом.

API="https://api.objavka.app/v1"
KEY="ovk_..."   # ваш ключ

# 1. Создать объект
curl -s -X POST "$API/objects" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
        "deal_type": "sale",
        "property_type": "apartment",
        "address_raw": "Москва, ул. Тверская, 1",
        "area": 54.3,
        "rooms": 2,
        "floor": 5,
        "floors_total": 12,
        "price_kopecks": 1850000000,
        "tone_of_voice": "warm"
      }'
# → { "id": "<object_id>", "status": "draft", ... }

# 2. Добавить фото по публичным URL (до 20 шт., ≤20 МБ каждое)
curl -s -X POST "$API/objects/<object_id>/photos" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/1.jpg", "https://example.com/2.jpg"]}'

# 3. Запустить генерацию (расходует 1 слот общей квоты)
curl -s -X POST "$API/objects/<object_id>/generate" -H "X-API-Key: $KEY"
# → { "status": "queued", "object_id": "<object_id>" }

# 4. Поллинг результата (раз в 2–5 с), пока нужные kind не станут "done"
curl -s "$API/objects/<object_id>/generations" -H "X-API-Key: $KEY"

Все пути относительно базового URL. Заголовок X-API-Key обязателен.

Пример ответа GET /objects/{id}/generations:

[
  {
    "kind": "text_avito",
    "status": "done",
    "payload": { "title": "...", "body": "..." },
    "finished_at": "2026-06-16T10:47:00Z"
  },
  {
    "kind": "pdf_kit",
    "status": "running",
    "payload": {},
    "finished_at": null
  }
]

Возможные kind: text_avito, text_cian, text_tg, kit_copy, kit_faq, pdf_kit, pdf_onepager, pdf_kit_owner, pdf_kit_bank, social_1x1, social_9x16, motion_poster, floor_plan. Набор зависит от тарифа и данных объекта.

Генерация асинхронная. После POST .../generate опрашивайтеGET .../generations, пока нужные kind не получат статусdone (или failed).

• Вебхуков/колбэков для разработчиков нет — только поллинг.
• Рекомендуемый интервал опроса — 2–5 секунд. Полный набор обычно готов за ~15–30 секунд.
• Тексты (text_*, kit_*) приходят раньше, чем PDF и картинки соцсетей.

Вопросы по интеграции, повышенным лимитам и условиям тарифа Агентство — info@objavka.app.