Об'єкти

Останнє оновлення: 2026-10-038 хв читання

Три типи об'єктів (kind): property - продаж, rental - оренда, complex - житловий комплекс. Читання безкоштовне і доступне будь-якому ключу; створення, зміна і видалення потребують області objects:write і теж не тарифікуються.

Список

curl "https://developers.grem.capital/api/v1/objects?kind=property&city=Berlin&limit=20" \
  -H "Authorization: Bearer gsk_live_xxx"

GET /objects:

Параметр	Опис
`kind`	обов'язковий: `property`, `rental` або `complex`; регістр не важливий
`city`, `country`	фільтр за точним збігом
`priceMin`, `priceMax`	ціна, у доларах США (за нормалізованою ціною)
`areaMin`, `areaMax`	площа, м²
`rooms`	кімнат (property і rental); може бути дробовим
`type`, `residentialType`	категорія - коди з довідників (property і rental)
`page`	сторінка, з 1; менше значення вважається 1
`limit`	на сторінку, за замовчуванням 20, 1-50; значення поза діапазоном зводиться до нього
`sort`	`newest` (за замовчуванням) або `oldest`
`scope`	тільки ключ агентства: за замовчуванням видно об'єкти агентства, `catalog` - публічний каталог

Відповідь: data - масив об'єктів, paginate - currentPage, totalPages, totalCount.

limit і page поза діапазоном зводяться до нього, а не відхиляються. Інші неприпустимі значення відомого параметра (невідоме значення переліку, нецілий page, текст замість числа) відхиляються з 400 validation і назвою поля.

Один об'єкт

GET /objects/{kind}/{id} - об'єкт у тій самій формі. Невідомий id - 404. Ключ агентства може додати scope=catalog, щоб отримати публічний вигляд.

Форма об'єкта

Поле	Опис
`id`, `kind`, `name`, `slug`	ідентифікація
`status`	для чужого об'єкта - `active` або `sold`
`type`	категорія - код
`price`, `currency`	ціна; у complex - `price: { from, to, currency }`
`constructionYear`	рік побудови, ціле число або `null`
`address`	повна адреса, з вулицею і координатами
`nativeAreaUnit`	одиниця площі, в якій об'єкт заведено (для показу); площі віддаються як `{ "value": 50, "unit": "m2" }`
`photos`	фото: `id`, `isMain`, `mimetype`, `variants`, `ready`
`processingStatus`	`ready`, `processing` або `failed` - чи готові фото
`promoted`	об'єкт просувається
`author`	агент або агентство оголошення

Категорії та інші атрибути - коди; підписи мовами - у довідниках. У complex є ще apartmentPlans (планування) і progress (хід будівництва).

ready: false у фото означає, що варіанти з водяним знаком ще генеруються. Показуйте заглушку і перечитайте об'єкт пізніше - не кешуйте незавершене зображення.

Що видно: будь-який об'єкт - публічна картка, як на сайті; ваші об'єкти - повний вигляд власника. Нікому не віддаються контакти власника, дані продавця з імпорту, нотатки модерації і оригінали фото без водяного знака.

Створити, змінити, видалити

Дія	Запит	Відповідь
Створити	`POST /objects/{kind}`	`201` з об'єктом
Змінити	`PUT /objects/{kind}/{id}`	об'єкт; тільки власник, інакше `404`
Видалити	`DELETE /objects/{kind}/{id}`	чернетка видаляється назавжди, опублікований об'єкт знімається в архів; об'єкт з чинним договором про комісію - `409 conflict`

curl -X POST https://developers.grem.capital/api/v1/objects/property \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d" \
  -d '{
    "name": "2-room flat, Torstraße 12",
    "type": "Residential",
    "address": { "country": "Germany", "city": "Berlin", "street": "Torstraße", "streetNumber": "12" },
    "price": 320000, "currency": "EUR",
    "spaceAll": 64, "rooms": 2, "floor": 3, "buildingFloor": 5,
    "photos": ["https://example.com/1.jpg"],
    "publish": false
  }'

publish: false (за замовчуванням) - чернетка, не видна в каталозі; publish: true - публікація. Для публікації потрібно щонайменше 1 фото у property і rental, 2 - у complex.
Створювати об'єкт певного типу може не кожна роль акаунта - як у кабінеті.
Невідомі поля ігноруються. Коди категорій беріть з довідників. Коди condition, conditionType і amenities (у camelCase, наприклад needsRenovation, fridge) перелічені в самій схемі запису (таблиці нижче і /openapi.json) - GET /dictionaries їх не розшифровує.
Площі: число в м² або { "value": 700, "unit": "ft2" }.
PUT без photos залишає наявні фото.
Idempotency-Key на створенні захищає від дубля при повторі.

Фото

photos - масив, кожен елемент:

публічна адреса https://... - GREM сам завантажить зображення;
id файлу, завантаженого через POST /uploads (Файли).

Адреса, яку не вдалося завантажити, пропускається і потрапляє в warnings відповіді. З strictPhotos: true такий запит натомість завершується 422.

Поля для property

Обов'язкові: name, type, address, price.

Поле	Опис
`type`	`Residential`, `Commercial`, `Industrial` або `Land plot`
`residentialType`, `commercialType`, `industrialType`	підтип - код або масив кодів
`marketSegment`	`primary` (новобудова) або `secondary`
`description`	опис, до 5000 символів
`address`	`country`, `city` (обов'язкові), `district`, `region`, `street`, `streetNumber`, `postalCode`, `location`
`price`, `currency`	ціна; валюта `UAH`, `USD`, `EUR`, `AZN`, `GBP`, `AED`, `CNY`, `TRY`, `GEL`
`constructionYear`	рік, 1700-2100
`spaceAll`, `spaceLiving`, `spaceKitchen`, `effectiveArea`, `auxiliaryArea`, `landPlotArea`	площі
`rooms`, `bedrooms`, `numberOfBathrooms`, `balconies`, `numberWindows`, `unitsCount`	кількості
`floor`, `buildingFloor`, `ceilingHeight`	поверх, поверхів, висота стель
`condition`	`needsRenovation`, `partialRenovation`, `renovated`, `designer`, `shellCore`, `newFromDeveloper`
`buildingType`	`newBuilding`, `secondary`, `stalinka`, `khrushchevka`, `brezhnevka`, `czech`, `gostinka`, `prerevolutionary`, `townhouseRow`, `detached`, `other`
`wallMaterialType`, `constructionTech`, `kitchenType`	матеріал стін, технологія, тип кухні
`amenities`, `buildingAmenities`	зручності в квартирі і в будинку - масиви кодів
`utilitySystem`, `heating`, `windowView`, `balcony`, `parking`	комунікації, опалення, вид, балкон, паркінг
`safety`	`shelterNearby`, `powerBackup`, `autonomousHeating`, `waterReserve`, `starlink`, `gasAvailable`, `internetAvailable`, `elevatorWorks` (так/ні)
`accessibility`	`ramp`, `groundLevelEntrance`, `wideDoors`, `disabledParking`, `wheelchairElevator` (так/ні)
`programs`	`eOselya`, `eVidnovlennya`, `mortgageEligible`, `installment`
`monthRentalRate`, `annualIncome`, `annualYield`, `paybackPeriod`, `propertyTax`, `insuranceCost`, `managementFee`, `repairsReserve`	інвестиційні показники
`commission`	комісія для агентів: `payer`, `type`, `value`
`tour`	3D-тур: `kind`, `url`
`complexId`	ЖК, до якого належить квартира
`photos`, `video`	медіа
`publish`, `strictPhotos`	див. вище

Поля для rental

Обов'язкові: name, type (Residential, Commercial, Industrial), address, price. Більшість полів - як у property; власні поля оренди:

Поле	Опис
`rentalType`	`long` - довгострокова, `short` - подобова
`price`, `dayPrice`, `deposit`	ставка, ставка за добу, застава
`totalArea`, `totalFloors`, `bathrooms`	площа, поверхів, ванних
`minRentTime`, `minTermMonths`	мінімальний термін
`availableFrom`	вільна з дати
`checkIn`, `checkOut`	час заїзду і виїзду: `from`, `to` — година доби (`15` = 15:00)
`withChildren`, `withPets`	з дітьми; з тваринами: `yes`, `no`, `with someone`
`furniture`, `furnitureList`	меблі
`conditionType`	стан - ті самі значення, що `condition` у property
`onsiteAmenities`, `internalFeature`	зручності
`utilitiesIncluded`, `utilitiesCost`	комунальні
`checkInPay`, `onlinePay`, `bankTransfer`, `reportingDocuments`	способи оплати і документи

Поля для complex

Обов'язкові: name, address.

Поле	Опис
`description`, `descriptionPresentation`, `descriptionSocial`	описи
`price`	`from`, `to`, `currency`
`space`	площі квартир: `from`, `to`
`apartType`	типи квартир
`class`	`economy`, `comfort`, `comfortPlus`, `business`, `premium`, `elite`
`stage`	`planning`, `excavation`, `construction`, `finishing`, `commissioned`, `delivered`
`completionQuarter`	квартал здачі
`queues`	черги: `name`, `stage`, `completionQuarter`
`sectionsNumber`, `floors`, `apartmentsNumber`, `parkingSpaces`	кількості
`installment`, `installmentTerms`	розстрочка: `downPaymentPct`, `termMonths`, `interestRate`
`infrastructure`	інфраструктура - масив кодів
`territoryDescription`, `parkingDescription`, `infrastructureDescription`	описи
`apartmentPlans`	планування: `apartType`, `area`, `price`, `description`, `photos`
`progress`	хід будівництва: `title`, `date`, `description`, `photos`

Повна схема кожного типу з усіма значеннями - компоненти ObjectWriteProperty, ObjectWriteRental, ObjectWriteComplex у /openapi.json. Вони згенеровані з тих самих перевірок, що виконує сервер.

Ключ агентства

Запит	Що робить
`PATCH /objects/{kind}/{id}/agency`	перенести об'єкт в агентство або повернути в особисті: тіло `{"targetAgencyId": "<id>"}` або `{"targetAgencyId": null}`; без поля - в агентство ключа
`PATCH /objects/{kind}/{id}/assignee`	призначити відповідального агента: `{"assignTo": "<id користувача>"}`

Особистим ключем обидва запити дають 403. Перенести об'єкт з одного агентства в інше напряму не можна (409 conflict) - спершу в особисті. Призначити агента на особистий об'єкт або на того, хто не є активним учасником агентства, теж не можна - 409 conflict. Права: перенести в агентство - автор об'єкта; повернути в особисті - менеджер, власник агентства або автор; призначити будь-кого - менеджер і вище, агент - тільки себе.

Події

object.created, object.updated, object.published, object.deleted - див. Вебхуки.

Пов'язані статті

Довідники - коди категорій і атрибутів.
Файли - завантаження фото.
Матеріали оголошення - сайт і PDF для об'єкта.

Ця стаття була корисною?