Imospot pentru dezvoltatori

Partner API v1 — integrare CRM

Publică și sincronizează anunțuri imobiliare direct din CRM-ul tău în Imospot.ro. Un singur contract stabil: trimiți proprietățile în format standard, noi le publicăm, geolocalizăm și promovăm.

Base URL https://www.imospot.ro/api/v1 Specificație OpenAPI

01 Pornire rapidă

Ai nevoie de o singură cheie API, pe care ți-o dăm noi pentru fiecare agenție. Cu ea, un anunț ajunge live în trei pași: îl trimiți, îl actualizezi când se schimbă, îl retragi când se vinde.

# Publică un anunț (create sau update — idempotent pe external_id)
curl -X POST https://www.imospot.ro/api/v1/listings \
  -H "Authorization: Bearer sk_agentie_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "CRM-8842", "transaction": "sale", ... }'

Idempotent după external_id. Trimite același external_id (id-ul din CRM-ul tău) de câte ori vrei — creăm anunțul o singură dată, apoi îl actualizăm. Nu se dublează niciodată.

02 Autentificare

Fiecare cerere trece cheia agenției într-un antet. Cheia identifică agenția și compania Imospot legată de ea — nu trimiți nimic despre „cine ești" în payload.

Authorization: Bearer sk_agentie_3f8a92c1b4e7
# sau, echivalent:
X-API-Key: sk_agentie_3f8a92c1b4e7

O cheie per agenție. Un CRM care aduce mai multe agenții primește câte o cheie pentru fiecare. Verifică-ți cheia oricând cu GET /account — îți întoarce și soldul de credite pentru promovare.

03 Endpoint-uri

POST/listingscreează sau actualizează un anunț

PUT/listings/{external_id}actualizează un anunț existent

DELETE/listings/{external_id}retrage anunțul (vândut / expirat)

GET/accountverifică cheia + sold credite promovare

DELETE nu șterge definitiv. Anunțul devine „retras", iar pagina lui rămâne activă cu redirect SEO, ca să nu pierzi poziția în Google. La un nou POST cu același external_id, revine live.

04 Formatul anunțului

Un obiect JSON curat, în engleză, la fel pentru toate CRM-urile. Noi traducem intern la taxonomia Imospot — tip, categorie, oraș și cartier se rezolvă automat din text + coordonate.

{
  "external_id": "CRM-8842",
  "transaction": "sale",            // sale | rent
  "property_type": "apartment",     // apartment|house|land|commercial|warehouse
  "title": "Apartament 3 camere, Centru",
  "description": "Text liber, min. 60 caractere. HTML simplu acceptat.",
  "price": 85000, "currency": "EUR",
  "exclusive": true, "zero_commission": true,
  "video_url": "https://youtu.be/…",
  "contact": {
    "phone": "0721000000",
    "agent": { "name": "Ana Pop", "email": "ana@agentie.ro", "phone": "0721…" }
  },
  "location": {
    "county": "Brașov", "city": "Brașov",
    "neighborhood": "Centrul Vechi", "street": "Str. Mureșenilor",
    "lat": 45.6427, "lng": 25.5887
  },
  "attributes": {
    "rooms": 3, "bathrooms": 2, "surface": 75,
    "floor": 4, "total_floors": 10, "year_built": 2015,
    "comfort": "luxury", "condition": "renovated", "heating": "Centrală proprie"
  },
  "features": ["parking", "balcony", "elevator"],
  "images": ["https://cdn.crm.ro/1.jpg", "https://cdn.crm.ro/2.jpg"],
  "promotion": { "product": "top", "days": 7 }
}

Câmpuri principale

Câmp	Tip	Descriere
external_id	string obligatoriu	Id-ul anunțului în CRM-ul tău. Cheia de deduplicare.
transaction	enum obligatoriu	sale · rent
property_type	enum obligatoriu	apartment · house · land · commercial · warehouse
title	string obligatoriu	Minim 8 caractere.
description	string obligatoriu	Minim 60 de caractere. HTML simplu acceptat; îl curățăm.
price	integer obligatoriu	Preț întreg, fără zecimale.
currency	enum opțional	EUR (implicit) · RON · USD
exclusive	bool opțional	Marchează anunțul „Exclusivitate".
zero_commission	bool opțional	Marchează „Comision 0".
video_url	string opțional	Link YouTube/Vimeo. Îl validăm.
contact.phone	string obligatoriu	Telefonul afișat pe anunț.
contact.agent	object opțional	Prezent → creăm/legăm agentul sub agenție (după email).
location	object obligatoriu	`county` și `city` obligatorii; `lat`/`lng` recomandate.
attributes	object opțional	Ce nu se aplică tipului, ignorăm. Un teren n-are `rooms`.
images	string[] obligatoriu	URL-uri publice. Le descărcăm și le servim de la noi (CDN). Cel puțin una.
promotion	object opțional	Vezi secțiunea Promovări.

Nu trimite id-uri de taxonomie. Oraș, cartier, categorie și sector (București) se rezolvă automat din text și coordonate. Tu trimiți nume, noi normalizăm.

05 Promovări

Agenția își cumpără dinainte credite de promovare din contul Imospot. La publicare, marchezi în payload ce promovare vrei, iar noi o aplicăm consumând din soldul agenției — automat.

"promotion": { "product": "top", "days": 7 }

product	Ce face	Durate (zile)
top	Fixează anunțul în capul categoriei.	5 · 7 · 10
featured	Evidențiere + prezență în secțiunile recomandate.	5 · 7 · 10

Sold insuficient nu blochează publicarea. Dacă agenția n-are destule credite, anunțul se publică normal, iar promovarea e ignorată — îți întoarcem promotion.applied: false cu un motiv, nu o eroare. Nu pierzi niciodată anunțul dintr-o problemă de promovare.

06 Răspunsuri

201 la creare, 200 la actualizare. Îți întoarcem id-ul nostru, URL-ul public și starea. Lucrezi mereu pe external_id-ul tău.

// 201 Created
{
  "status": "ok",
  "listing": {
    "id": 13245, "external_id": "CRM-8842", "state": "active",
    "url": "https://www.imospot.ro/anunturi/…",
    "promotion": { "product": "top", "applied": true, "expires_at": "2026-07-24T00:00:00Z" }
  }
}

state	Înseamnă
active	Live public. Agenție cu abonament activ.
unclaimed	Agenție încă nemapată la o companie — în așteptare la noi.
archived	Retras după DELETE.

07 Erori

Cod HTTP + corp JSON cu ce s-a întâmplat și, la validare, exact ce câmp e greșit.

Cod	Când	Ce faci
401	Cheie lipsă sau invalidă.	Verifică antetul `Authorization`.
422	Payload invalid.	Vezi `errors` — listă pe câmp.
404	DELETE/PUT pe un `external_id` necunoscut.	Publică-l întâi cu POST.
429	Prea multe cereri.	Respectă `Retry-After`. Limită generoasă pentru sincronizări normale.

// 422 Unprocessable
{
  "status": "error", "message": "Validation failed",
  "errors": { "price": ["Câmpul price este obligatoriu."], "images": ["Câmpul images este obligatoriu."] }
}