Концепции
External ID
Используйте ваши ID из CRM вместо внутренних ID Rentix
External ID — рекомендуемый подход для интеграции. Вам не нужно хранить ID Rentix в своей базе данных. Используйте ID объектов из вашей CRM — API сам найдёт соответствующие записи.
Проблема без External ID
Типичная интеграция без external ID требует дополнительной таблицы маппинга:
Ваша CRM Таблица маппинга Rentix
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ ID: APT-001 │ ──────────► │ APT-001 → 42 │ ───► │ ID: 42 │
│ ID: APT-002 │ │ APT-002 → 43 │ │ ID: 43 │
└─────────────┘ └──────────────────┘ └─────────────┘
При каждом обновлении нужно:
- Найти маппинг в своей базе
- Получить ID Rentix
- Отправить запрос с этим ID
Решение с External ID
С external ID маппинг не нужен — API делает его сам:
Ваша CRM Rentix
┌─────────────┐ ┌─────────────────────┐
│ ID: APT-001 │ ───── externalId: "APT-001" ────────► │ ID: 42 │
│ ID: APT-002 │ │ externalId: APT-001 │
└─────────────┘ └─────────────────────┘
При обновлении:
- Отправьте запрос с
externalId: "APT-001" - API сам найдёт объявление #42
Как использовать
При создании
Передайте externalId — ваш ID из CRM:
{
"externalId": "APT-001",
"announcementType": "rent",
"propertyType": "residential",
"propertySecondaryType": "apartment",
"announcementValue": 500
}
При обновлении
Тот же externalId — API найдёт существующее объявление:
{
"externalId": "APT-001",
"announcementValue": 600
}
При получении
Используйте endpoint с /external/:
// По external ID
const response = await fetch(
'https://crm.rentix.md/api/v1/listings/external/APT-001',
{ headers: { 'Authorization': 'ApiKey YOUR_API_KEY' } }
);
const listing = await response.json();
console.log(listing.id); // 42 (внутренний ID)
console.log(listing.externalId); // "APT-001" (ваш ID)
curl https://crm.rentix.md/api/v1/listings/external/APT-001 \
-H "Authorization: ApiKey YOUR_API_KEY"
$ch = curl_init('https://crm.rentix.md/api/v1/listings/external/APT-001');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: ApiKey YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$listing = json_decode($response, true);
Правила использования
| Правило | Описание |
|---|---|
| Максимальная длина | 255 символов |
| Допустимые символы | Буквы, цифры, дефисы, подчёркивания |
| Уникальность | В пределах агентства и типа ресурса |
Один
externalId может быть у объявления, другой такой же — у медиафайла. Конфликта не будет, потому что это разные типы ресурсов.Поддерживаемые ресурсы
External ID работает для всех основных ресурсов:
| Ресурс | Пример endpoint |
|---|---|
| Объявления | GET /listings/external/{externalId} |
| Пользователи | GET /users/external/{externalId} |
| Медиафайлы | GET /media/external/{externalId} |
Привязка к существующим объектам
Если объект уже создан без externalId, его можно привязать позже:
// Привязать external ID к объявлению #42
await fetch('https://crm.rentix.md/api/v1/listings/42/link', {
method: 'POST',
headers: {
'Authorization': 'ApiKey YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ externalId: 'APT-001' })
});
curl -X POST https://crm.rentix.md/api/v1/listings/42/link \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "externalId": "APT-001" }'
$ch = curl_init('https://crm.rentix.md/api/v1/listings/42/link');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['externalId' => 'APT-001']));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ApiKey YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
Отвязать external ID:
curl -X DELETE https://crm.rentix.md/api/v1/listings/42/link \
-H "Authorization: ApiKey YOUR_API_KEY"
Частые ошибки
| Ошибка | Причина | Решение |
|---|---|---|
External ID already linked | ID уже используется другим объектом | Используйте уникальный ID |
Cannot provide both id and externalId | Передали оба параметра | Используйте только один |