API CREAM

REST API для обмена данными с CRM: лиды, сделки, объекты, блоки, контрагенты, контакты, подборки, задачи, сотрудники и словари. Изменения приходят вебхуками и лентой событий.

Начало работы

API доступен на тарифе «Про» и выше. Ключ выпускается в кабинете: «Настройки → API». Сделать это могут владелец и сотрудники с доступом к настройкам. Ключ показывается один раз.

Адрес API:

https://crm.broker.kvadera.ru/api/v1

Проверить ключ:

curl https://crm.broker.kvadera.ru/api/v1/organization/ \
  -H "Authorization: Bearer cream_ваш_ключ"

Описание в формате OpenAPI: https://crm.broker.kvadera.ru/api/v1/schema/.

Коллекция для Postman: скачать. После импорта укажите в переменных коллекции api_key — ключ и user_id — id сотрудника для записи.

Авторизация и права

Ключ передаётся в заголовке Authorization: Bearer <ключ>. Ключ принадлежит компании, а не сотруднику, и даёт полный доступ ко всем её данным, независимо от ролей.

Храните ключ только на сервере: не добавляйте его в код сайта или мобильного приложения. Если ключ мог попасть к посторонним, отзовите его в настройках и выпустите новый. У ключа можно задать список разрешённых IP-адресов.

Чтение и фильтры

Списки отдаются постранично, в порядке создания записей:

{
  "next": "https://crm.broker.kvadera.ru/api/v1/deals/?cursor=cD0w...",
  "previous": null,
  "results": [ ... ]
}

Следующая страница — запрос на адрес из next; когда там null, записи кончились. Сортировки нет: порядок постоянный, поэтому при выгрузке записи не пропускаются и не повторяются.

У всех списков есть фильтры ids, created_from, created_to, updated_from, updated_to. Даты — в формате ISO 8601: 2026-11-06T10:00:00+03:00. Остальные фильтры — те же, что в кабинете, они перечислены у каждого раздела ниже. Несколько значений — через запятую, если в описании не сказано иное.

curl "https://crm.broker.kvadera.ru/api/v1/spaces/?status=free&deal_type=rent&area_from=100" \
  -H "Authorization: Bearer cream_ваш_ключ"

Свои поля фильтруются параметром custom: JSON «ключ поля → условие». Строка ищется как часть текста; число и дата — {"from": …, "to": …}; список — вариант или массив вариантов; да/нет — true или false.

В /spaces/ свойства блока (статус, назначение, объект, этаж) находят все блоки. Остальные фильтры работают как «Поиск по блокам» в кабинете: подходит блок, у которого условие аренды или продажи подошло по всем таким фильтрам сразу.

Удалённые записи API не отдаёт: запрос по id вернёт 404, ссылка на удалённую запись — null. Блоки удалённого объекта тоже считаются удалёнными.

Запись

Создание — POST, изменение — PATCH (только переданные поля). Удаления через API нет. Сотрудники, подборки и словари только читаются.

При записи обязателен заголовок X-User-Id — id действующего сотрудника из GET /users/. Он станет автором записи и ответственным по умолчанию. На права он не влияет: права у ключа полные.

curl -X POST https://crm.broker.kvadera.ru/api/v1/leads/ \
  -H "Authorization: Bearer cream_ваш_ключ" \
  -H "X-User-Id: 0192f0aa-..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Анна", "phone": "+7 999 123-45-67", "text": "Ищу офис 200 м²"}'

Ответ на запись — запись целиком, как при чтении.

Повтор запроса

Заголовок Idempotency-Key — любая ваша строка до 255 символов. Если соединение оборвалось, повторите POST с тем же ключом: вернётся первый ответ, вторая запись не появится. Запрос с ошибкой ключ не занимает. Тот же ключ с другим телом запроса вернёт 409. Ключ действует двое суток.

Id вашей системы

Заголовок X-External-Ref — id записи у вас. Первый POST создаст запись, следующие с тем же значением обновят её и вернут 200. Найти запись — фильтром external_ref. Значения уникальны внутри сущности и компании.

События

О любом создании, изменении и удалении записи можно узнать двумя способами: лентой GET /events/ или вебхуком. В событии — только ссылка на изменение, сами данные читаются через API.

{
  "cursor": "1542_8841",
  "entity": "deal",
  "action": "updated",
  "id": "0192f0aa-...",
  "changed": ["stage", "responsible"],
  "occurred_at": "2026-11-06T10:15:30+03:00",
  "source": {"user": "0192f0ab-...", "api_key": null}
}

Несколько изменений одной записи в одной операции — одно событие. Чтение ленты: сохраняйте next из ответа и передавайте в after; after=latest — начать с текущего момента. События хранятся 30 дней. Событие может появиться с задержкой в несколько секунд: лента отдаёт только завершённые изменения. Если запрос записи вернул 404, значит запись уже удалена.

Изменения словарей событий не создают.

Чтение изменённых записей пачкой

Не запрашивайте каждую запись отдельно: при массовом изменении это быстро упрётся в лимит запросов. Соберите id из пачки событий по сущностям, пропустите deleted и прочитайте записи фильтром ids — до 100 id в одном запросе, с page_size=100:

curl "https://crm.broker.kvadera.ru/api/v1/deals/?ids=0192f0aa-...,0192f0ad-...&page_size=100" \
  -H "Authorization: Bearer cream_ваш_ключ"

Адрес списка — сущность во множественном числе: lead → /leads/, company → /companies/. Повторы одного id в пачке достаточно прочитать один раз: ответ — текущее состояние записи. Если записи нет в ответе, она удалена после события.

Вебхуки

Адрес добавляется в «Настройки → API». Можно выбрать сущности и действия. Новый адрес получает только события после подключения.

POST https://ваш-сервер/hook
Content-Type: application/json
X-Cream-Delivery: 0192f0ac-...
X-Cream-Signature: t=1762412130,v1=5f8a...

{
  "events": [ ... ],
  "delivery": "0192f0ac-..."
}

В одной отправке — до 100 событий. Ответьте кодом 2xx в течение 10 секунд: долгую обработку выполняйте после ответа. Адрес должен быть https и не должен вести во внутреннюю сеть; редиректы не выполняются.

При другом ответе отправка повторяется с нарастающей паузой от 30 секунд до часа, порядок сохраняется. Если адрес не отвечает сутки, вебхук отключается, а добавивший его сотрудник получает уведомление. После включения доставка продолжится с места остановки. Событие может прийти повторно: обрабатывайте их так, чтобы повтор ничего не ломал, например по cursor.

Проверка подписи

Подпись — HMAC-SHA256 от метка_времени.тело_запроса с секретом вебхука. Секрет показывается один раз при добавлении и при смене.

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(","))
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(expected, parts["v1"])

Ошибки и лимиты

Справочник методов

Организация

Организация ключа: проверка, что ключ работает.

Словари

Все словари. only — какие нужны, через запятую; без него — все.

События

Лента изменений: created, updated, deleted. Хранится 30 дней. Сохраните next и

Лиды

Лиды: входящие обращения до разбора.

Сделки

Сделки с заявкой, контактами и блоками.

Объекты

Объекты со всеми блоками и условиями.

Блоки

Блоки с условиями.

Условия

Условия блока: аренда и продажа.

Пользователи

Сотрудники компании; id — значение X-User-Id при записи.

Контрагенты

Контрагенты со всеми контактами.

Контакты

Контакты и их контрагенты.

Подборки

Подборки: блоки, реакции клиента, ссылки.

Задачи

Задачи с чек-листом.