URBANETAURBANETA
URBANETAURBANETA

Язык

Тема

Developer Docs

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

Создавайте интеграции с Urbaneta. Автоматизируйте выставление счетов, синхронизируйте жильцов, считывайте данные счётчиков и многое другое.

API-ключи

Создавайте API-ключи в настройках аккаунта. Каждый ключ привязан к вашей организации.

Bearer-авторизация

Все запросы требуют действующего Bearer-токена. Токены истекают через 15 минут — используйте refresh-токены для автоматического обновления.

Вебхуки

Подписывайтесь на события (invoice.created, payment.received, reading.submitted) с HMAC-подписанными данными.

Базовый URL
https://testlnp.workizon.com/api

Все запросы должны выполняться по HTTPS. Замените на URL вашего собственного сервера, если применимо.

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

Включайте токен доступа в заголовок Authorization в каждом запросе.

# Токены краткосрочны. Используйте POST /auth/refresh с refresh-токеном для автоматического получения нового токена доступа. Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Быстрый старт

Три шага до первой интеграции через API.

1. Авторизуйтесь и получите токен

curl -X POST https://testlnp.workizon.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

# Response
{ "data": { "accessToken": "eyJ...", "refreshToken": "dGhp..." } }

2. Получите список ваших зданий

curl https://testlnp.workizon.com/api/buildings \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Сгенерируйте счета для здания

curl -X POST https://testlnp.workizon.com/api/invoices/generate-bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildingId":"<uuid>","periodStart":"2025-01-01","periodEnd":"2025-01-31"}'

Пример на JavaScript / TypeScript

SDK не нужен — API использует стандартный REST. Пример получения счетов и записи платежа.

# Fetch unpaid invoices
curl "https://testlnp.workizon.com/api/invoices?buildingId=<uuid>&status=sent" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Mark invoice as paid
curl -X PATCH "https://testlnp.workizon.com/api/invoices/<invoice-id>" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","paidDate":"2025-02-01"}'

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

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

POST/auth/loginВход по email и паролю, возвращает токены доступа и обновления
POST/auth/refreshОбновить истёкший токен доступа с помощью refresh-токена
POST/auth/logoutЗавершить текущую сессию
POST/auth/magic-linkЗапросить письмо с magic-ссылкой для входа

Здания

GET/buildingsСписок всех зданий текущего арендатора
POST/buildingsСоздать новое здание
GET/buildings/:idПолучить здание по ID
PATCH/buildings/:idОбновить настройки здания (название, адрес, расчёты и т.д.)
DELETE/buildings/:idУдалить здание (требует подтверждения паролем)

Квартиры

GET/buildings/:id/apartmentsСписок квартир в здании
POST/buildings/:id/apartmentsСоздать квартиру
PATCH/buildings/:id/apartments/:aptIdОбновить данные квартиры
DELETE/buildings/:id/apartments/:aptIdУдалить квартиру

Счета

GET/invoicesСписок счетов с фильтрацией (статус, здание, диапазон дат)
GET/invoices/:idПолучить детали счёта включая позиции
POST/invoices/generate-bulkСгенерировать счета для здания и периода
PATCH/invoices/:idОбновить статус, дату оплаты или ссылку счёта
POST/invoices/send-bulkОтправить счета жильцам по email
GET/invoices/:id/pdfСкачать счёт в формате PDF

Счётчики

GET/metersСписок счётчиков в здании
POST/metersСоздать новый счётчик
POST/meters/:id/readingsПодать показания счётчика
POST/meters/ocrИзвлечь показание из фото счётчика с помощью AI OCR

Жильцы и пользователи

GET/residentsСписок жильцов, связанных с вашими зданиями
POST/invitationsПригласить пользователя в квартиру
GET/invitationsСписок ожидающих приглашений
DELETE/invitations/:idОтменить приглашение

Платежи

POST/payments/banklinkИнициировать оплату через Paysera / Maksekeskus banklink
GET/paymentsСписок записанных платежей арендатора
POST/bank-statements/importИмпортировать CSV/XML выписку банка для авторекончиляции

Вебхуки

GET/webhooksСписок настроенных вебхук-эндпоинтов
POST/webhooksСоздать вебхук-эндпоинт (URL + типы событий)
DELETE/webhooks/:idУдалить вебхук-эндпоинт

Типы событий для вебхуков

Подписывайтесь на любую комбинацию событий при создании вебхука.

invoice.createdНовый счёт сгенерирован
invoice.sentСчёт отправлен жильцу по email
invoice.paidСчёт отмечен как оплаченный (вручную или через banklink)
invoice.overdueСчёт не оплачен после срока
payment.receivedПлатёж записан к счёту
reading.submittedЖилец подал показания счётчика
reading.confirmedУправляющий подтвердил показания счётчика
maintenance.createdПодана новая заявка на ремонт
maintenance.updatedСтатус заявки на ремонт изменился

Пример данных

POST https://your-server.com/webhook X-Urbaneta-Signature: sha256=... { "event": "invoice.paid", "timestamp": "2025-02-01T10:30:00Z", "tenantId": "550e8400-e29b-41d4-a716-...", "data": { "invoiceId": "...", "amount": 142.50 } }

HTTP-коды ошибок

400Неверный запросНеверное тело запроса или отсутствуют обязательные поля
401Не авторизованОтсутствует или истёк токен доступа
403Доступ запрещёнАвторизован, но недостаточно прав
404Не найденоРесурс не найден или недоступен для вашего арендатора
409КонфликтДублирующийся ресурс (например, номер квартиры уже существует)
422Ошибка валидацииПроверка не прошла — проверьте массив errors в ответе
429Превышен лимитСлишком много запросов — повторите попытку после значения заголовка Retry-After
500Ошибка сервераНеожиданная ошибка — обратитесь в поддержку, если проблема повторяется

Готовы к интеграции?

Войдите в аккаунт Urbaneta, чтобы создать API-ключи и настроить вебхуки.

Перейти в панель управления