У Urbaneta теперь есть публичный API — вот что вы можете с ним сделать
Несколько недель назад управляющий недвижимостью задал мне вопрос, который запомнился. «Мы используем Urbaneta для наших зданий, но наше бухгалтерское ПО — кастомное. Можем ли мы автоматически вытягивать данные инвойсов вместо экспорта CSV каждый месяц?»
Мой ответ тогда был «пока нет». Мой ответ сегодня — другой.
У Urbaneta теперь есть публичный API. Он работает, задокументирован и готов для интеграций. Если вы разработчик, управляющая компания с собственным IT или просто тот, кто хочет перестать копировать данные между системами — это для вас.
Что реально вышло
Три вещи запущены вместе, и они работают как набор:
1. Документация API — публичный справочник на `/api-docs`, который точно говорит, какие эндпоинты существуют, что они принимают и что возвращают.
2. API-ключи — ограниченные токены, которые вы генерируете в админ-панели для аутентификации запросов.
3. Webhooks — уведомления в реальном времени, которые отправляют события на ваш сервер вместо того, чтобы заставлять вас поллить.
Разберём каждый.
Документация API: карта
Первое, что нужно при разработке против любого API — чёткая документация. Мы разместили нашу на `/api-docs` на основном домене Urbaneta. Без логина — она публичная.
Она покрывает:
- Аутентификацию: как включить API-ключ в заголовок `Authorization: Bearer`.
- Здания, квартиры и жильцов: CRUD-операции для основных сущностей.
- Инвойсы и показания счётчиков: данные, которые управляющих реально волнуют.
- Подписку на webhooks: как зарегистрировать и управлять webhook-эндпоинтами.
- Коды ошибок: что значат `400`, `401`, `403` и `429` на практике, плюс поведение rate-limiting.
Документация генерируется из исходного кода API, поэтому она не устаревает. Если эндпоинт меняется, документация обновляется вместе с ним.
API-ключи: ограниченные, а не всесильные
Вот на чём я настоял при проектировании: API-ключи должны быть ограниченными. Не стоит давать сторонней интеграции ключ, который может удалять здания, только потому что ей нужно читать данные инвойсов.
В админ-панели, в разделе Интеграции → API-ключи, вы можете создавать ключи с конкретными разрешениями:
- `read:buildings` — список зданий и квартир
- `read:invoices` — получение данных инвойсов
- `write:invoices` — создание или обновление инвойсов
- `read:residents` — доступ к справочнику жильцов
- `webhooks:manage` — подписка и управление webhook-эндпоинтами
Вы можете создать несколько ключей для разных интеграций. Если ключ вендора утечёт, вы отзываете только его. Не нужно ротировать всё.
Ключи имеют префикс `nmv_`, поэтому их легко заметить в логах и код-ревью. На нашей стороне используется SHA-256 хэширование, поэтому даже утечка базы данных не раскрывает сами токены.
Webhooks: прекратите поллить, начните реагировать
Это то, чем я лично больше всего горжусь. Поллинг — расточителен. Если вы проверяете каждые 5 минут, не создан ли новый инвойс, вы делаете 288 запросов в день ради данных, которые, может, изменились дважды.
С webhooks Urbaneta отправляет события на ваш URL по мере их возникновения:
- `invoice.created`
- `invoice.paid`
- `resident.invited`
- `maintenance_request.updated`
- `meter_reading.submitted`
Вы подписываетесь на события, которые вам важны, в Интеграции → Webhooks. Urbaneta отправляет POST-запрос на ваш эндпоинт с подписанным payload. Вы проверяете подпись, обрабатываете событие — и готово.
Мы включили механизм повторных попыток: если ваш эндпоинт возвращает не-2xx статус или тайм-аут, мы повторяем с экспоненциальной задержкой до 24 часов. Доставка — at-least-once, поэтому ваш эндпоинт должен быть идемпотентным. Мы также включаем заголовок `X-Urbaneta-Event-ID`, чтобы вы могли дедуплицировать при необходимости.
Практический пример
Допустим, вы управляете компанией по управлению недвижимостью с дюжиной зданий. Вы хотите:
1. Вытянуть все инвойсы, созданные в этом месяце, в вашу бухгалтерскую систему.
2. Отметить инвойс как оплаченный, когда банковский перевод проходит.
3. Уведомить вашу команду по ремонту, когда жилец отправляет фото показания счётчика.
До API это был ручной экспорт CSV, сопоставление в таблице и телефонные звонки. Теперь это:
- Cron-задача, которая раз в день вызывает `GET /api/v1/invoices?created_after=2026-07-01`.
- Webhook-обработчик для `invoice.paid`, который автоматически обновляет вашу книгу.
- Webhook-обработчик для `meter_reading.submitted`, который отправляет в ваш внутренний Slack-канал.
Вся интеграция может занять у разработчика день-два. Экономия времени начинается немедленно.
Что это значит для управляющих недвижимостью
Если вы не разработчик, вы можете подумать: «это мило, но я не пишу код». Справедливо. Вот почему это всё равно важно:
Ваши вендоры могут интегрироваться. Если вы используете бухгалтерский инструмент, платформу для ремонта или приложение для общения с жильцами, вы можете попросить их построить интеграцию с Urbaneta. API и webhooks дают им всё необходимое. Вы получаете автоматическую синхронизацию данных, не трогая ни строчки кода.
White-label порталы остаются независимыми. API-ключи ограничены по tenant. Если вы запускаете white-label портал управления недвижимостью под своим доменом, ваши API-ключи видят только ваши данные. Нет утечки между tenant.
Что дальше
Текущий API покрывает основные потоки управления недвижимостью: здания, жильцы, инвойсы, показания счётчиков, ремонт и платежи. Мы расширяем его на основе того, что интеграторы реально запрашивают.
Если вы строите что-то и вам нужен эндпоинт, которого ещё нет — дайте знать. API спроектирован для роста — мы предпочитаем поставлять небольшую, надёжную поверхность и добавлять к ней, а не строить массивный spec, который никто не использует.
С чего начать
1. Откройте `/api-docs` в браузере. Прочитайте раздел аутентификации.
2. Перейдите в админ-панель → Интеграции → API-ключи и создайте тестовый ключ.
3. Сделайте первый запрос: `GET /api/v1/buildings` с вашим ключом в заголовке.
4. Если нужны события в реальном времени — перейдите в Интеграции → Webhooks и зарегистрируйте ваш эндпоинт.
Документация включает готовые `curl`-примеры для каждого эндпоинта. Не нужно угадывать форму payload.
---
Год назад кто-то сказал мне, что ПО для управления недвижимостью должно «просто работать» без интеграций. Я раньше верил в это. Теперь думаю наоборот: лучшая платформа управления недвижимостью — та, которая соединяется со всем остальным, что вы уже используете.
Именно это мы и строим.
