Creare și actualizare
Un singur endpoint PUT /listings pentru toate operațiile cu anunțuri: creare, actualizare și publicare. API-ul determină automat dacă să creeze un anunț nou sau să actualizeze unul existent.
Creează un anunț
Trimite datele proprietății. Dacă externalId este nou — se creează anunțul, dacă există — se actualizează.
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 camere
propertyHousingMarket: 'new-build', // clădire nouă
propertyVisualState: 'euro-renovation', // renovare euro
propertyAddress: 'Chișinău, str. Columna 81/1', // or propertyCoordinates: { lat, lng } (preferred)
announcementDescription: 'Apartament confortabil cu 3 camere cu podele calde și încălzire autonomă.'
})
});
const result = await response.json();
console.log(result.created ? 'Creat' : 'Actualizat');
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": "Apartament confortabil cu 3 camere cu podele calde și încălzire autonomă."
}'
$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' => 'Apartament confortabil cu 3 camere cu podele calde și încălzire autonomă.'
];
$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
}
Anunțul este creat în statusul draft. Pentru publicare sunt necesare fotografii.
Publică anunțul
Pentru publicare este nevoie de:
- Minim 3 fotografii
- Statusul
active
Cea mai simplă metodă — transmite URL-urile fotografiilor direct la creare. Se recomandă adăugarea externalFileId pentru urmărire:
{
"externalId": "apt-001",
"announcementStatus": "active",
"files": [
{ "url": "https://placehold.co/1920x1080/jpg?text=Living", "externalFileId": "apt-001-photo-1" },
{ "url": "https://placehold.co/1920x1080/jpg?text=Dormitor", "externalFileId": "apt-001-photo-2" },
{ "url": "https://placehold.co/1920x1080/jpg?text=Bucătărie", "externalFileId": "apt-001-photo-3" }
]
}
De asemenea poți folosi fișiere deja încărcate:
{
"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
}
Statusul pending_active înseamnă că anunțul este în procesare (optimizare fotografii, traducere). În câteva secunde va deveni active.
Actualizează anunțul
Transmite doar câmpurile modificate — celelalte vor fi păstrate:
{
"externalId": "apt-001",
"announcementValue": 600,
"announcementDescription": "Descriere actualizată a apartamentului..."
}
Pentru a goli un câmp, trimite null:
{
"externalId": "apt-001",
"propertyFloorNumber": null
}
Ascunde sau finalizează tranzacția
| Acțiune | Cum |
|---|---|
| Ascunde de pe site | "announcementStatus": "hidden" |
| Restabilește pe site | "announcementStatus": "active" |
| Marchează ca finalizat | "announcementStatus": "completed" |
Câmpuri răspuns
| Câmp | Tip | Descriere |
|---|---|---|
id | number | ID intern Rentix |
externalId | string | ID-ul tău din CRM |
status | string | Statusul curent al anunțului |
publicUrl | string | URL-ul anunțului pe rentix.md |
created | boolean | true dacă anunțul a fost creat |
updated | boolean | true dacă anunțul a fost actualizat |
jobId | number | ID-ul sarcinii (la publicare) |
Parametri cerere
Identificare
| Câmp | Tip | Descriere |
|---|---|---|
id | number | ID intern Rentix |
externalId | string | ID-ul tău din CRM (până la 255 caractere) |
id, fieexternalId — nu ambele simultan.Tip anunț (obligatorii)
| Câmp | Tip | Valori |
|---|---|---|
announcementType | enum | rent, sale |
propertyType | enum | residential, commercial, parking |
propertySecondaryType | enum | Depinde de propertyType (vezi prezentare) |
Preț
| Câmp | Tip | Descriere |
|---|---|---|
announcementValue | number | Preț (de la 1 la 1 000 000 000) |
announcementCurrency | enum | EUR, USD, MDL |
announcementPayPeriod | enum | monthly, daily, hourly, yearly (doar pentru închiriere) |
Caracteristici
| Câmp | Tip | Descriere |
|---|---|---|
propertyArea | number | Suprafață, m² |
propertyLandArea | number | Suprafață teren, m² |
propertyFloorNumber | number | Etaj (de la -10 la 100) |
propertyFloorsTotal | number | Total etaje (de la 1 la 100) |
propertyCeilingHeight | number | Înălțime tavane, m |
propertyQuantitySize | enum | apartment-studio, custom-value |
propertyQuantitySizeValue | number | Număr camere (dacă custom-value) |
Localizare
| Câmp | Tip | Descriere |
|---|---|---|
propertyCoordinates | object | { lat, lng } — coordonate GPS exacte (recomandat) |
propertyAddress | string | Adresă — geocodificată automat în coordonate (max 500 caractere) |
propertyCoordinates, fiepropertyAddress — nu ambele simultan. Coordonatele sunt recomandate pentru precizie. Format propertyAddress: Oraș, Stradă Număr (ex. Chișinău, str. Columna 81/1).Stare
| Câmp | Tip | Valori |
|---|---|---|
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 | Facilități și reguli (vezi schema) |
Condiții închiriere
| Câmp | Tip | Descriere |
|---|---|---|
announcementMinRentPeriod | number | Perioadă minimă, ore |
announcementPrepayment | enum | no-prepayment, first-and-last-month, months-3, months-6, custom-amount |
announcementPrepaymentValue | number | Sumă (pentru custom-amount) |
announcementRentDeposit | enum | months-1, months-3, custom-amount |
announcementRentDepositValue | number | Sumă (pentru custom-amount) |
announcementBargain | enum | yes, no |
Descriere și media
| Câmp | Tip | Descriere |
|---|---|---|
announcementDescription | string/object | Descriere (40–2000 caractere) sau obiect cu traduceri |
files | array | Array de fișiere (vezi mai jos) |
applyAnalysis | boolean | Auto-detectare atribute din fotografii și descriere (implicit true) |
Format elemente files:
| Format | Exemplu | Descriere |
|---|---|---|
| URL + external ID | { "url": "...", "externalFileId": "..." } | Recomandat — auto-import cu urmărire |
| Doar URL | { "url": "https://..." } | Auto-import fără urmărire |
| După internal ID | { "id": 123 } | Fișier deja încărcat |
| După external ID | { "externalFileId": "photo-1" } | Fișier cu ID-ul tău |
externalFileId la transmiterea URL-ului — asta permite urmărirea fișierelor și evitarea duplicării la cereri repetate.Utilizator și status
| Câmp | Tip | Descriere |
|---|---|---|
user | object | { userId } sau { externalUserId } — atribuie un agent |
announcementStatus | enum | draft, active, hidden, completed |
Validare
Verifică datele fără salvare — util pentru validarea formularului în 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": "Scurt"
}'
{
"valid": false,
"errors": [
{
"field": "announcementDescription",
"code": "STRING_TOO_SHORT",
"message": "Lungime minimă: 40 caractere"
}
],
"warnings": []
}
{
"valid": true,
"errors": [],
"warnings": []
}
Descriere multilingvă
Descrierea poate fi un string sau un obiect cu traduceri:
{
"announcementDescription": {
"ru": "Уютная 3-комнатная квартира с тёплыми полами...",
"en": "Cozy 3-room apartment with heated floors...",
"ro": "Apartament confortabil cu 3 camere cu podele calde..."
}
}
Dacă transmiți un string — sistemul va traduce automat în celelalte limbi.
Locale suportate: ru, en, ro
Erori frecvente
| Eroare | Cauză | Soluție |
|---|---|---|
Cannot provide both id and externalId | Ai transmis ambii identificatori | Folosește doar unul |
announcementDescription too short | Descrierea are mai puțin de 40 caractere | Adaugă mai multe detalii |
Minimum 3 photos required | Fotografii insuficiente pentru publicare | Încarcă minim 3 fotografii |
Invalid propertySecondaryType | Subtipul nu corespunde tipului | Verifică combinațiile permise |
Pașii următori
- Încarcă fotografii — modalități de încărcare fișiere media
- Operații în masă — creare mai multe anunțuri deodată
- Obține anunțuri — interogare listă și detalii