Циан API - Документация

Обзор

Циан API позволяет агентствам недвижимости и риелторам интегрировать данные об объектах Циан в свою CRM-систему и автоматизировать публикацию объявлений.

Официальная документация: https://public-api.cian.ru/

Требования для доступа к API

1. Тарифный план

API доступен для пользователей тарифа "Базовый" и выше: - Агентства недвижимости - Частные риелторы

2. Авторизационный ключ

Каждому аккаунту Циан выдается отдельный авторизационный ключ для работы с API.

---

Получение API ключа

1. Войдите в личный кабинет Циан
2. Перейдите в раздел "Настройки" → "API"
3. Создайте новый API ключ
4. Сохраните:
5. API Key
6. User ID

---

Аутентификация

Циан API использует API Key authentication.

Пример запроса

GET https://public-api.cian.ru/v1/offers
Authorization: Bearer YOUR_API_KEY

Или через query parameter:

GET https://public-api.cian.ru/v1/offers?access_token=YOUR_API_KEY

---

Основные возможности API

1. Получение объявлений

Список всех объявлений

GET https://public-api.cian.ru/v1/offers
Authorization: Bearer YOUR_API_KEY

Parameters: - page - номер страницы (default: 1) - per_page - кол-во на странице (max: 100) - status - статус объявления (active, archived)

Response:

{
  "data": [
    {
      "id": 123456789,
      "type": "sale",
      "category": "flatSale",
      "status": "active",
      "address": {
        "fullAddress": "Москва, Можайское шоссе, 10",
        "coordinates": {
          "lat": 55.721749,
          "lng": 37.415663
        }
      },
      "price": {
        "value": 5000000,
        "currency": "RUB"
      },
      "area": {
        "total": 50,
        "living": 30,
        "kitchen": 12
      },
      "views": 245,
      "contacts": 12,
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-02-15T14:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "pages": 8
  }
}

Получить одно объявление

GET https://public-api.cian.ru/v1/offers/{offer_id}
Authorization: Bearer YOUR_API_KEY

---

2. Публикация объявлений через XML

Циан поддерживает автоматическую загрузку объявлений через XML-фид.

Требования к XML файлу

1. URL фида должен быть постоянным и доступным по HTTP/HTTPS
2. Документ должен содержать корневой элемент <feed>
3. XML должен быть в кодировке UTF-8
4. Размер файла: максимум 100 MB
5. Обновление: не чаще 1 раза в 30 минут

Пример XML структуры для недвижимости

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <feed_version>2</feed_version>
  <object>
    <ExternalId>property_502</ExternalId>
    <Category>landSale</Category>
    <Description>Продается земельный участок 10 соток в ДНП Тихие Луга</Description>

    <!-- Адрес -->
    <Address>
      <Country>Россия</Country>
      <Region>Московская область</Region>
      <District>Можайский район</District>
      <Locality>ДНП Тихие Луга</Locality>
      <Lat>55.523456</Lat>
      <Lng>36.234567</Lng>
    </Address>

    <!-- Цена -->
    <BargainTerms>
      <Price>299000</Price>
      <Currency>RUR</Currency>
    </BargainTerms>

    <!-- Характеристики -->
    <Land>
      <Area>
        <Value>10</Value>
        <Unit>sotka</Unit>
      </Area>
      <Status>individualHousingConstruction</Status>
    </Land>

    <!-- Контакты -->
    <ContactInfo>
      <ContactPerson>Иван Иванов</ContactPerson>
      <PhoneSchema>
        <CountryCode>+7</CountryCode>
        <Number>9991234567</Number>
      </PhoneSchema>
    </ContactInfo>

    <!-- Фото -->
    <Image>
      <FullUrl>https://example.com/photo1.jpg</FullUrl>
      <IsDefault>true</IsDefault>
    </Image>
    <Image>
      <FullUrl>https://example.com/photo2.jpg</FullUrl>
    </Image>
  </object>
</feed>

Регистрация XML фида

1. Войдите в личный кабинет Циан
2. Перейдите в "Загрузка объявлений" → "XML Feed"
3. Укажите URL вашего XML файла
4. Циан будет проверять фид каждые 30 минут

Документация: https://www.cian.ru/xml_import/doc/

---

3. Обновление объявления

PATCH https://public-api.cian.ru/v1/offers/{offer_id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "price": {
    "value": 280000
  },
  "status": "active"
}

---

4. Снятие объявления с публикации

DELETE https://public-api.cian.ru/v1/offers/{offer_id}
Authorization: Bearer YOUR_API_KEY

Или обновление статуса:

PATCH https://public-api.cian.ru/v1/offers/{offer_id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "status": "archived"
}

---

Типы недвижимости (Category)

Значение	Описание
flatSale	Продажа квартиры
flatRent	Аренда квартиры
roomSale	Продажа комнаты
houseSale	Продажа дома
houseRent	Аренда дома
landSale	Продажа участка
commercialSale	Продажа коммерческой недвижимости
commercialRent	Аренда коммерческой недвижимости

---

Статистика объявлений

GET https://public-api.cian.ru/v1/statistics/offers/{offer_id}
Authorization: Bearer YOUR_API_KEY

Response:

{
  "offer_id": 123456789,
  "views": {
    "total": 345,
    "unique": 280,
    "yesterday": 25,
    "today": 12
  },
  "contacts": {
    "total": 18,
    "phone_shows": 12,
    "messages": 6
  },
  "favorites": 7,
  "period": {
    "from": "2026-02-01",
    "to": "2026-02-16"
  }
}

---

Работа с чатами (если доступно)

Получить список чатов

GET https://public-api.cian.ru/v1/chats
Authorization: Bearer YOUR_API_KEY

Response:

{
  "chats": [
    {
      "id": "chat_abc123",
      "offer_id": 123456789,
      "user": {
        "name": "Петр",
        "phone": "+79991234567"
      },
      "last_message": {
        "text": "Здравствуйте, интересует участок",
        "created_at": "2026-02-16T15:30:00Z",
        "from": "user"
      },
      "unread_count": 1
    }
  ]
}

Отправить сообщение

POST https://public-api.cian.ru/v1/chats/{chat_id}/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "text": "Здравствуйте! Участок актуален, можем организовать просмотр."
}

---

Категории участков (Land Status)

Значение	Описание
individualHousingConstruction	ИЖС (индивидуальное жилищное строительство)
garden	Садоводство (СНТ)
subsidiary	Личное подсобное хозяйство (ЛПХ)
farming	Фермерство (КФХ)

---

Rate Limits

• Максимум запросов: 1000 запросов/час
• XML Feed обновление: минимум 30 минут между обновлениями
• Кэширование запросов: разрешено до 30 дней

---

Обработка ошибок

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Типичные ошибки:

HTTP Code	Описание	Решение
401	Unauthorized	Проверить API key
403	Forbidden	Проверить доступ к тарифу
422	Validation Error	Проверить формат данных
429	Too Many Requests	Снизить частоту запросов
500	Internal Server Error	Повторить запрос позже

---

Webhook уведомления

Циан может отправлять уведомления о событиях на ваш сервер.

Настройка webhook

1. Войдите в личный кабинет
2. "Настройки" → "Webhooks"
3. Укажите URL: https://silent-meadow.com/api/v1/cian/webhook

События

• offer.created - создано новое объявление
• offer.updated - обновлено объявление
• offer.archived - объявление архивировано
• message.new - новое сообщение в чате

Формат webhook

{
  "event": "message.new",
  "timestamp": "2026-02-16T16:00:00Z",
  "data": {
    "chat_id": "chat_abc123",
    "offer_id": 123456789,
    "message": {
      "text": "Можно уточнить цену?",
      "from": "user"
    }
  }
}

---

Best Practices

1. XML Feed валидация: Проверяйте XML на соответствие схеме перед загрузкой
2. Обновление цен: Обновляйте цены не чаще 1 раза в день
3. Качество фото: Минимум 3 фото на объявление, размер не менее 800x600px
4. Описания: Уникальные тексты для каждого объявления (не дубликаты)
5. Координаты: Точные координаты увеличивают показы на 30-40%

---

Полезные ссылки

• Официальная документация Циан API
• Требования к XML
• Справка для риелторов
• Поддержка Циан
• Интеграции Циан с CRM

---

Обновлено: 2026-02-16