Partner API v1 — integrare CRM

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", ... }'

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

03 Endpoint-uri

03b Performanța anunțurilor

Cifrele de care ai nevoie ca să-i arăți proprietarului ce a făcut anunțul lui: câți l-au văzut, câți au cerut numărul, câți au sunat sau au scris pe WhatsApp, câți l-au salvat și câte lead-uri a adus. Sunt date private — cheia ta vede exclusiv anunțurile agenției tale, și nu apar nicăieri public.

Dacă anunțurile îți vin prin REBS sau Immoflux, {external_id} e chiar codul din CRM-ul tău: pentru REBS, CP + id-ul proprietății (ex. CP3378065) — același cod pe care îl afișăm și pe pagina anunțului. Merge și fără prefix.

curl "https://www.imospot.ro/api/v1/listings/CP3378065/stats?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer sk_..."

{
  "status": "ok",
  "listing": {
    "external_id": "CP3378065",
    "url": "https://www.imospot.ro/anunturi/...",
    "state": "active",
    "totals": { // tot istoricul anunțului
      "views": 412, "phone_reveals": 18, "phone_calls": 9,
      "whatsapp": 6, "saves": 7, "leads": 3
    },
    "period": {
      "from": "2026-08-01", "to": "2026-08-31",
      "totals": { "views": 96, "phone_reveals": 4, ... },
      "daily": [ { "date": "2026-08-01", "views": 7, ... } ]
    }
  }
}

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

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 }

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" }
  }
}

07 Erori

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

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

08 Mediu de test

Integrarea se testează direct pe producție, cu o cheie de test. Anunțurile trimise cu ea trec prin exact același lanț ca cele reale — validare, geolocalizare, descărcarea pozelor, agenți — dar nu devin publice niciodată și nu consumă credite.

• Răspunsurile au aceleași coduri și aceeași state pe care le-ați primi în producție, plus "sandbox": true.
• Anunțurile de test sunt separate de cele reale: un external_id folosit la teste nu se ciocnește de același id trimis ulterior cu cheia de producție a agenției.
• Promovarea se validează, dar nu se aplică: promotion.applied: false.
• Rezultatul se verifică oricând cu GET /listings/{external_id}, iar cu contul de test primit de la noi îl vedeți și pe site, în previzualizare.

# Ce a înțeles Imospot din ultimul push
curl https://www.imospot.ro/api/v1/listings/CRM-8842 \
  -H "Authorization: Bearer sk_agentie_xxxxx"

// 200 OK
{
  "status": "ok",
  "listing": {
    "id": 13245, "external_id": "CRM-8842", "state": "active", "sandbox": true,
    "url": "https://www.imospot.ro/anunturi/…",
    "title": "Apartament 3 camere, Centru", "price": 85000, "currency": "EUR",
    "images": ["https://…/listings/1.jpg", "https://…/listings/2.jpg"],
    "updated_at": "2026-09-11T10:00:00+03:00"
  }
}