Anunțuri

Creare și actualizare

Cum să creezi, actualizezi și publici anunțuri prin API

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');
Răspuns
{
  "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:

  1. Minim 3 fotografii
  2. 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" }
  ]
}
Răspuns
{
  "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.

Cum să încarci fotografii — în secțiunea Fișiere media.

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țiuneCum
Ascunde de pe site"announcementStatus": "hidden"
Restabilește pe site"announcementStatus": "active"
Marchează ca finalizat"announcementStatus": "completed"

Câmpuri răspuns

CâmpTipDescriere
idnumberID intern Rentix
externalIdstringID-ul tău din CRM
statusstringStatusul curent al anunțului
publicUrlstringURL-ul anunțului pe rentix.md
createdbooleantrue dacă anunțul a fost creat
updatedbooleantrue dacă anunțul a fost actualizat
jobIdnumberID-ul sarcinii (la publicare)

Parametri cerere

Identificare

CâmpTipDescriere
idnumberID intern Rentix
externalIdstringID-ul tău din CRM (până la 255 caractere)
Transmite fieid, fieexternalId — nu ambele simultan.

Tip anunț (obligatorii)

CâmpTipValori
announcementTypeenumrent, sale
propertyTypeenumresidential, commercial, parking
propertySecondaryTypeenumDepinde de propertyType (vezi prezentare)

Preț

CâmpTipDescriere
announcementValuenumberPreț (de la 1 la 1 000 000 000)
announcementCurrencyenumEUR, USD, MDL
announcementPayPeriodenummonthly, daily, hourly, yearly (doar pentru închiriere)

Caracteristici

CâmpTipDescriere
propertyAreanumberSuprafață, m²
propertyLandAreanumberSuprafață teren, m²
propertyFloorNumbernumberEtaj (de la -10 la 100)
propertyFloorsTotalnumberTotal etaje (de la 1 la 100)
propertyCeilingHeightnumberÎnălțime tavane, m
propertyQuantitySizeenumapartment-studio, custom-value
propertyQuantitySizeValuenumberNumăr camere (dacă custom-value)

Localizare

CâmpTipDescriere
propertyCoordinatesobject{ lat, lng } — coordonate GPS exacte (recomandat)
propertyAddressstringAdresă — geocodificată automat în coordonate (max 500 caractere)
Transmite fiepropertyCoordinates, 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âmpTipValori
propertyVisualStateenumclassic-renovation, euro-renovation, design-renovation, requires-renovation, white-finish, rough-finish
propertyHousingMarketenumsecondary, new-build
propertyBuildingMaterialenumbrick, mixed, cotilet, monolithic, concrete, block, wood, panel, aerated-concrete
propertyLayoutenum102, 135, 143, brezhnevka, varnitskaia, gostinka, custom, small-family, moldovan-series, ground-level, rubashka, stalinka, khrushchyovka, cheska
propertyAttributesarrayFacilități și reguli (vezi schema)

Condiții închiriere

CâmpTipDescriere
announcementMinRentPeriodnumberPerioadă minimă, ore
announcementPrepaymentenumno-prepayment, first-and-last-month, months-3, months-6, custom-amount
announcementPrepaymentValuenumberSumă (pentru custom-amount)
announcementRentDepositenummonths-1, months-3, custom-amount
announcementRentDepositValuenumberSumă (pentru custom-amount)
announcementBargainenumyes, no

Descriere și media

CâmpTipDescriere
announcementDescriptionstring/objectDescriere (40–2000 caractere) sau obiect cu traduceri
filesarrayArray de fișiere (vezi mai jos)
applyAnalysisbooleanAuto-detectare atribute din fotografii și descriere (implicit true)

Format elemente files:

FormatExempluDescriere
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
Se recomandă să indici întotdeauna externalFileId la transmiterea URL-ului — asta permite urmărirea fișierelor și evitarea duplicării la cereri repetate.

Utilizator și status

CâmpTipDescriere
userobject{ userId } sau { externalUserId } — atribuie un agent
announcementStatusenumdraft, active, hidden, completed
Lista completă de câmpuri pentru un tip specific de proprietate — în referința schemei.

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"
  }'
Răspuns cu erori
{
  "valid": false,
  "errors": [
    {
      "field": "announcementDescription",
      "code": "STRING_TOO_SHORT",
      "message": "Lungime minimă: 40 caractere"
    }
  ],
  "warnings": []
}
Validare reușită
{
  "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

EroareCauzăSoluție
Cannot provide both id and externalIdAi transmis ambii identificatoriFolosește doar unul
announcementDescription too shortDescrierea are mai puțin de 40 caractereAdaugă mai multe detalii
Minimum 3 photos requiredFotografii insuficiente pentru publicareÎncarcă minim 3 fotografii
Invalid propertySecondaryTypeSubtipul nu corespunde tipuluiVerifică combinațiile permise

Pașii următori

Copyright © 2026