Создание и обновление
Один endpoint PUT /listings для всех операций с объявлениями: создание, обновление и публикация. API автоматически определяет, создать новое объявление или обновить существующее.
Создайте объявление
Отправьте данные объекта. Если externalId новый — создаётся объявление, если существующий — обновляется.
const response = await fetch('https://crm.rentix.md/api/v1/listings', {
method: 'PUT',
headers: {
'Authorization': 'ApiKey YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
externalId: 'apt-001',
announcementType: 'rent',
propertyType: 'residential',
propertySecondaryType: 'apartment',
announcementValue: 500,
announcementCurrency: 'EUR',
announcementPayPeriod: 'monthly',
propertyArea: 65,
propertyFloorNumber: 3,
propertyFloorsTotal: 9,
propertyQuantitySize: 'custom-value',
propertyQuantitySizeValue: 3, // 3 комнаты
propertyHousingMarket: 'new-build', // новостройка
propertyVisualState: 'euro-renovation', // евроремонт
propertyAddress: 'Chișinău, str. Columna 81/1', // or propertyCoordinates: { lat, lng } (preferred)
announcementDescription: 'Уютная 3-комнатная квартира с тёплыми полами и автономным отоплением.'
})
});
const result = await response.json();
console.log(result.created ? 'Создано' : 'Обновлено');
curl -X PUT https://crm.rentix.md/api/v1/listings \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "apt-001",
"announcementType": "rent",
"propertyType": "residential",
"propertySecondaryType": "apartment",
"announcementValue": 500,
"announcementCurrency": "EUR",
"announcementPayPeriod": "monthly",
"propertyArea": 65,
"propertyFloorNumber": 3,
"propertyFloorsTotal": 9,
"propertyQuantitySize": "custom-value",
"propertyQuantitySizeValue": 3,
"propertyHousingMarket": "new-build",
"propertyVisualState": "euro-renovation",
"propertyAddress": "Chișinău, str. Columna 81/1",
"announcementDescription": "Уютная 3-комнатная квартира с тёплыми полами и автономным отоплением."
}'
$data = [
'externalId' => 'apt-001',
'announcementType' => 'rent',
'propertyType' => 'residential',
'propertySecondaryType' => 'apartment',
'announcementValue' => 500,
'announcementCurrency' => 'EUR',
'announcementPayPeriod' => 'monthly',
'propertyArea' => 65,
'propertyFloorNumber' => 3,
'propertyFloorsTotal' => 9,
'propertyQuantitySize' => 'custom-value',
'propertyQuantitySizeValue' => 3,
'propertyHousingMarket' => 'new-build',
'propertyVisualState' => 'euro-renovation',
'propertyAddress' => 'Chișinău, str. Columna 81/1',
'announcementDescription' => 'Уютная 3-комнатная квартира с тёплыми полами и автономным отоплением.'
];
$ch = curl_init('https://crm.rentix.md/api/v1/listings');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ApiKey YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
{
"id": 42,
"externalId": "apt-001",
"status": "draft",
"publicUrl": "https://rentix.md/announcement/42",
"created": true,
"jobId": null
}
Объявление создано в статусе draft. Для публикации нужны фотографии.
Опубликуйте объявление
Для публикации требуется:
- Минимум 3 фотографии
- Статус
active
Самый простой способ — передать URL фотографий прямо при создании. Рекомендуется добавлять externalFileId для отслеживания:
{
"externalId": "apt-001",
"announcementStatus": "active",
"files": [
{ "url": "https://placehold.co/1920x1080/jpg?text=Гостиная", "externalFileId": "apt-001-photo-1" },
{ "url": "https://placehold.co/1920x1080/jpg?text=Спальня", "externalFileId": "apt-001-photo-2" },
{ "url": "https://placehold.co/1920x1080/jpg?text=Кухня", "externalFileId": "apt-001-photo-3" }
]
}
Также можно использовать уже загруженные файлы:
{
"externalId": "apt-001",
"announcementStatus": "active",
"files": [
{ "id": 123 },
{ "externalFileId": "apt-001-photo-2" },
{ "externalFileId": "apt-001-photo-3" }
]
}
{
"id": 42,
"externalId": "apt-001",
"status": "pending_active",
"publicUrl": "https://rentix.md/announcement/42",
"updated": true,
"jobId": 789
}
Статус pending_active означает, что объявление обрабатывается (оптимизация фото, перевод). Через несколько секунд станет active.
Обновите объявление
Передайте только изменённые поля — остальные сохранятся:
{
"externalId": "apt-001",
"announcementValue": 600,
"announcementDescription": "Обновлённое описание квартиры..."
}
Чтобы очистить поле, отправьте null:
{
"externalId": "apt-001",
"propertyFloorNumber": null
}
Скройте или закройте сделку
| Действие | Как |
|---|---|
| Скрыть с сайта | "announcementStatus": "hidden" |
| Вернуть на сайт | "announcementStatus": "active" |
| Отметить как завершённую | "announcementStatus": "completed" |
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
id | number | Внутренний ID Rentix |
externalId | string | Ваш ID из CRM |
status | string | Текущий статус объявления |
publicUrl | string | URL объявления на rentix.md |
created | boolean | true если объявление создано |
updated | boolean | true если объявление обновлено |
jobId | number | ID задачи (при публикации) |
Параметры запроса
Идентификация
| Поле | Тип | Описание |
|---|---|---|
id | number | Внутренний ID Rentix |
externalId | string | Ваш ID из CRM (до 255 символов) |
id, либоexternalId — не оба одновременно.Тип объявления (обязательные)
| Поле | Тип | Значения |
|---|---|---|
announcementType | enum | rent, sale |
propertyType | enum | residential, commercial, parking |
propertySecondaryType | enum | Зависит от propertyType (см. обзор) |
Цена
| Поле | Тип | Описание |
|---|---|---|
announcementValue | number | Цена (от 1 до 1 000 000 000) |
announcementCurrency | enum | EUR, USD, MDL |
announcementPayPeriod | enum | monthly, daily, hourly, yearly (только для аренды) |
Характеристики
| Поле | Тип | Описание |
|---|---|---|
propertyArea | number | Площадь, м² |
propertyLandArea | number | Площадь участка, м² |
propertyFloorNumber | number | Этаж (от -10 до 100) |
propertyFloorsTotal | number | Всего этажей (от 1 до 100) |
propertyCeilingHeight | number | Высота потолков, м |
propertyQuantitySize | enum | apartment-studio, custom-value |
propertyQuantitySizeValue | number | Количество комнат (если custom-value) |
Местоположение
| Поле | Тип | Описание |
|---|---|---|
propertyCoordinates | object | { lat, lng } — точные GPS-координаты (рекомендуется) |
propertyAddress | string | Адрес — автоматически геокодируется в координаты (макс. 500 символов) |
propertyCoordinates, либоpropertyAddress — не оба одновременно. Координаты рекомендуются для точности. Формат propertyAddress: Город, Улица Номер (напр. Chișinău, str. Columna 81/1).Состояние
| Поле | Тип | Значения |
|---|---|---|
propertyVisualState | enum | classic-renovation, euro-renovation, design-renovation, requires-renovation, white-finish, rough-finish |
propertyHousingMarket | enum | secondary, new-build |
propertyBuildingMaterial | enum | brick, mixed, cotilet, monolithic, concrete, block, wood, panel, aerated-concrete |
propertyLayout | enum | 102, 135, 143, brezhnevka, varnitskaia, gostinka, custom, small-family, moldovan-series, ground-level, rubashka, stalinka, khrushchyovka, cheska |
propertyAttributes | array | Удобства и правила (см. схему) |
Условия аренды
| Поле | Тип | Описание |
|---|---|---|
announcementMinRentPeriod | number | Минимальный срок, часы |
announcementPrepayment | enum | no-prepayment, first-and-last-month, months-3, months-6, custom-amount |
announcementPrepaymentValue | number | Сумма (при custom-amount) |
announcementRentDeposit | enum | months-1, months-3, custom-amount |
announcementRentDepositValue | number | Сумма (при custom-amount) |
announcementBargain | enum | yes, no |
Описание и медиа
| Поле | Тип | Описание |
|---|---|---|
announcementDescription | string/object | Описание (40–2000 символов) или объект с переводами |
files | array | Массив файлов (см. ниже) |
applyAnalysis | boolean | Автоопределение атрибутов по фото и описанию (по умолчанию true) |
Формат элементов files:
| Формат | Пример | Описание |
|---|---|---|
| URL + external ID | { "url": "...", "externalFileId": "..." } | Рекомендуется — автоимпорт с отслеживанием |
| Только URL | { "url": "https://..." } | Автоимпорт без отслеживания |
| По internal ID | { "id": 123 } | Уже загруженный файл |
| По external ID | { "externalFileId": "photo-1" } | Файл с вашим ID |
externalFileId при передаче URL — это позволит отслеживать файлы и избежать дублирования при повторных запросах.Пользователь и статус
| Поле | Тип | Описание |
|---|---|---|
user | object | { userId } или { externalUserId } — назначить агента |
announcementStatus | enum | draft, active, hidden, completed |
Валидация
Проверьте данные без сохранения — полезно для валидации формы в CRM.
POST /api/v1/listings/validate
curl -X POST https://crm.rentix.md/api/v1/listings/validate \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"announcementType": "rent",
"propertyType": "residential",
"propertySecondaryType": "apartment",
"announcementValue": 500,
"announcementDescription": "Короткое"
}'
{
"valid": false,
"errors": [
{
"field": "announcementDescription",
"code": "STRING_TOO_SHORT",
"message": "Минимальная длина: 40 символов"
}
],
"warnings": []
}
{
"valid": true,
"errors": [],
"warnings": []
}
Многоязычное описание
Описание может быть строкой или объектом с переводами:
{
"announcementDescription": {
"ru": "Уютная 3-комнатная квартира с тёплыми полами...",
"en": "Cozy 3-room apartment with heated floors...",
"ro": "Apartament confortabil cu 3 camere cu podele calde..."
}
}
Если передать строку — система автоматически переведёт на остальные языки.
Поддерживаемые локали: ru, en, ro
Частые ошибки
| Ошибка | Причина | Решение |
|---|---|---|
Cannot provide both id and externalId | Передали оба идентификатора | Используйте только один |
announcementDescription too short | Описание меньше 40 символов | Добавьте больше деталей |
Minimum 3 photos required | Недостаточно фото для публикации | Загрузите минимум 3 фото |
Invalid propertySecondaryType | Подтип не соответствует типу | Проверьте допустимые комбинации |
Следующие шаги
- Загрузить фотографии — способы загрузки медиафайлов
- Массовые операции — создание нескольких объявлений за раз
- Получить объявления — запрос списка и деталей