Documentație feed-uri

Câmpuri standard

Indiferent de format (XML/CSV/JSON), iMove mapează coloanele tale la următoarea structură canonică:

Pentru valori enum: transactionType = SALE/RENT (acceptăm și „vanzare"/„inchiriere"), propertyType ∈ {APARTMENT, STUDIO, HOUSE, LAND, COMMERCIAL, OFFICE} (acceptăm și „apartament"/„casa"/„teren").

Reguli pentru imagini

• URL-uri publice HTTPS, accesibile fără autentificare.
• Format: JPG, PNG, WebP. Recomandat: minimum 1200×800 px.
• Maxim 40 imagini per anunț.
• În CSV, separă URL-urile cu ; sau ,. În XML, folosește tag-uri <image>…</image> repetate.
• La fiecare sync, dacă lista de imagini din feed se modifică, imaginile vechi sunt înlocuite.

Feed XML

Structură recomandată: container repetat <listing> cu câmpurile de mai sus ca tag-uri imediate.

<?xml version="1.0" encoding="UTF-8"?>
<listings>
 <listing>
 <externalId>AG-12345</externalId>
 <title>Apartament 2 camere, Pipera</title>
 <description>...</description>
 <price>129500</price>
 <currency>EUR</currency>
 <transactionType>SALE</transactionType>
 <propertyType>APARTMENT</propertyType>
 <city>bucuresti</city>
 <rooms>2</rooms>
 <usableArea>62</usableArea>
 <images>
 <image>https://cdn.agentia.ro/12345/01.jpg</image>
 <image>https://cdn.agentia.ro/12345/02.jpg</image>
 </images>
 </listing>
</listings>

Feed CSV

Acceptăm separator , ; | sau tab (auto-detectat). Prima linie = header. Encoding UTF-8 (BOM-ul se ignoră automat).

externalId,title,price,currency,transactionType,propertyType,city,rooms,usableArea,imageUrls
AG-12345,"Apartament 2 camere",129500,EUR,SALE,APARTMENT,bucuresti,2,62,"https://cdn.agentia.ro/12345/01.jpg;https://cdn.agentia.ro/12345/02.jpg"
AG-12346,"Casă 4 camere",325000,EUR,SALE,HOUSE,cluj-napoca,4,140,"https://cdn.agentia.ro/12346/01.jpg"

Feed JSON

Răspunde cu un obiect care conține un array listings (sau properties sau items).

API agenție (planuri Pro+)

Generează cheie din Agenție → API. Cheia apare o singură dată — salveaz-o.

Autentificare

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

# Listează anunțurile agenției
GET /api/agency-api/properties?page=1&pageSize=50

# Bulk upsert (creează SAU actualizează după externalId)
POST /api/agency-api/properties
Content-Type: application/json
{ "properties": [ {"externalId":"AG-1","title":"...","price":120000, ...} ] }

# Anunț unic după externalId
GET /api/agency-api/properties/AG-12345
PUT /api/agency-api/properties/AG-12345
DELETE /api/agency-api/properties/AG-12345

# Trigger sync feeds
POST /api/agency-api/sync
{ "feedId": "..." } # opțional, dacă lipsește se sync toate feed-urile ACTIVE

Cereri (lead-uri) și conversații

Pentru inbox-ul din CRM-ul agenției: citiți cererile și conversațiile, răspundeți clientului direct din CRM. Răspunsul ajunge la client ca mesaj iMove (inbox, notificare pe telefon, email dacă nu e online).

# Cererile agenției (cele mai recente primele; since = modificate după data ISO)
GET /api/agency-api/leads?since=2026-10-20T00:00:00Z&status=NEW&page=1&pageSize=50

# O cerere + conversația completă
GET /api/agency-api/leads/{leadId}

# Doar mesajele (cronologic; since = doar mesajele noi)
GET /api/agency-api/leads/{leadId}/messages?since=2026-10-20T12:00:00Z
→ { "leadId": "...", "canReply": true, "messages": [
    { "id": "...", "direction": "INBOUND",  "body": "Bună ziua, ...", "createdAt": "...", "readAt": null,
      "author": { "name": "Ion Popescu", "email": null } },
    { "id": "...", "direction": "OUTBOUND", "body": "Bună ziua! ...", "createdAt": "...", "readAt": "...",
      "author": { "name": "Ana Agent", "email": "[email protected]" } } ] }

# Răspuns către client (cheie cu permisiunea write)
POST /api/agency-api/leads/{leadId}/messages
Content-Type: application/json
{ "body": "Bună ziua! Vă stă bine vineri la 17:00?", "agentEmail": "[email protected]" }
→ 201 { "leadId": "...", "duplicate": false, "message": { ... } }

• direction: INBOUND = mesaj de la client, OUTBOUND = răspuns al agenției (din iMove sau din CRM).
• agentEmail (opțional): agentul din echipă care semnează răspunsul. Dacă lipsește: agentul cererii → agentul anunțului → administratorul agenției.
• canReply = false: clientul a trimis cererea fără cont iMove → răspundeți pe email/telefon (contact din cerere). POST întoarce 409 CLIENT_NO_ACCOUNT.
• Retry sigur: același text pe aceeași cerere în 10 minute nu se trimite de două ori (duplicate: true).
• Erori: 400 date invalide · 401/403 cheie/permisiune · 404 cerere inexistentă sau a altei agenții · 409 fără cont client · 422 agentEmail nu e membru · 429 limită.

Webhook-uri

Configurare în Agenție → Webhooks. Fiecare livrare e semnată: X-iMove-Signature: sha256=HMAC_SHA256(secret, X-iMove-Timestamp + "." + rawBody); antete X-iMove-Event, X-iMove-Delivery (id unic, pentru deduplicare). Răspundeți cu 2xx; altfel reîncercăm automat.

# LEAD_CREATED — cerere nouă
{ "event": "LEAD_CREATED", "occurredAt": "...", "data": {
  "leadId": "...", "status": "NEW", "propertyId": "...", "propertyTitle": "...", "externalId": "AG-123",
  "propertyUrl": "https://imove.ro/proprietati/...", "agentEmail": "[email protected]",
  "contact": { "name": "...", "email": "...", "phone": "..." }, "message": "...",
  "hasImoveAccount": true, "canReply": true } }

# LEAD_MESSAGE — mesaj nou de la client într-o cerere existentă
{ "event": "LEAD_MESSAGE", "occurredAt": "...", "data": {
  "leadId": "...", "propertyId": "...", "externalId": "AG-123", "agentEmail": "[email protected]",
  "contact": { ... }, "message": { "id": "...", "direction": "INBOUND", "body": "...", "createdAt": "..." } } }

Rate limit per cheie: configurat conform planului tău (60–600 req/min). Toate request-urile sunt înregistrate pentru audit.