API Imopedia.ro — Ghid de utilizare

Documentație oficială pentru administrarea ofertelor prin webservice-ul Imopedia.ro, destinată integratorilor și partenerilor tehnici.

Changelog

2023.10.25

2023.06.01

2023.05.12

Versiuni anterioare

⚙️ Introducere

Ce face API-ul

API-ul de publicare în sistemul Imopedia.ro utilizează protocolul SOAP pentru administrarea ofertelor imobiliare și sincronizarea datelor între platforme.

Endpoint principal

Webservice-ul expus este disponibil la http://syncapi.imopedia.ro/api2/sync.wsdl. Accesul la webservice este restricționat pe bază de utilizator și parolă comunicate de echipa Imopedia.ro.

Flux de bază

  1. Login în sistem.
  2. Executarea operațiilor necesare (gestionare agenți, proprietăți, fișiere).
  3. Logout pentru închiderea sesiunii.

Documentație asociată

Pachetul complet conține:

Autentificare & sesiune

Login și obținerea session_id

Autentificarea se face prin metoda SOAP login, care returnează un session_id. Acesta trebuie transmis în toate apelurile ulterioare pentru a valida sesiunea activă.

Gestionarea sesiunii

Logout și erori frecvente

Operația logout închide sesiunea curentă și invalidează session_id. Un session_id expirat sau invalid va genera erori de autentificare. Reluați procesul de login și retransmiteți cererea după corectarea datelor.

Operații API

Vedere de ansamblu

Diagrame operații SOAP

Oferte

O ofertă trebuie asociată unei agenții. ID-ul de agenție autorizat pentru publicare este furnizat împreună cu datele de login. Informațiile despre agent pot fi trimise fie prin câmpurile CONTACT_PERS, CONTACT_TEL, CONTACT_EMAIL, fie prin AGENT_ID rezultat din apelul saveAgent.

Tipul imobilului este reprezentat printr-un ID numeric:

Agenți

Fișiere

🧾 Structura datelor

Nume câmp Tip Exemplu Descriere Obligatoriu
ID_LOCAL integer 67654 Identificator intern al ofertei, unic și numeric. Opțional
AGENTIA integer 0 ID-ul agenției autorizate pentru publicare. Da
TAGURI string "[\"Sold\"]" Array JSON cu etichete specifice proprietății (ex.: Sold, Ucraina). Opțional
TITLU string "Apartament 2 camere în Giurgiului" Titlul anunțului afișat public. Da
COMISION float 2 Comisionul perceput, exprimat procentual. Opțional
VIDEO_INFO string [{'TITLE':'Titlu video','FILE_URL':'https://www.youtube.com/watch?v=akotZoPsG5M'}] Listă JSON cu resurse video sau tururi virtuale. Opțional
GEO_LAT / GEO_LONG string 44.392663 / 26.089659 Coordonate geografice pentru harta Google Maps. Opțional
PRET_TEXT_DISCOUNT string "Capacitate 4 persoane..." Detalii privind prețurile cu discount, folosit inclusiv în regimuri speciale. Opțional
T_I_PRET_DISCOUNT float 200 Preț de închiriere cu discount. Opțional
T_H_PRET_DISCOUNT float null Preț regim hotelier cu discount. Opțional

📚 Nomenclatoare

Idei generale

Proprietățile de descriere ale ofertei se completează conform fișierului Excel nomenclatoare_api.xlsx. Pentru fiecare câmp sunt precizate detalii și, acolo unde este cazul, legături către worksheet-urile nomenclatoarelor asociate.

Localizare ofertă

Resurse externe

💬 Întrebări frecvente (FAQ)

Autentificare

  1. Cum pot accesa API-ul Imopedia.ro? Pentru acces sunt necesare credențiale (utilizator și parolă) furnizate de echipa tehnică Imopedia.ro. Odată primite, folosiți endpoint-ul SOAP disponibil la http://syncapi.imopedia.ro/api2/sync.wsdl.
  2. Cum gestionez autentificarea la API? După apelul login salvați session_id și transmiteți-l în toate cererile ulterioare. Finalizați sesiunea cu logout.

Publicare oferte

  1. Ce tipuri de imobile pot publica folosind API-ul? API-ul suportă apartamente, birouri, case/vile, spații comerciale, spații industriale și terenuri. Fiecare tip are un ID specific.
  2. Pot utiliza propriul ID de ofertă? Da, ID-urile pot proveni din sistemul intern dacă sunt numerice și unice.
  3. Cum se gestionează locația unei oferte? Completați JUDET, ZONA, REPER și coordonatele GEO_LAT/GEO_LONG pentru afișarea corectă pe hartă.
  4. Ce tipuri de tranzacții pot gestiona prin API? Sunt acceptate tranzacții de vânzare (T_V_TRANZ) și închiriere (T_I_TRANZ).

Multimedia

  1. Cum pot adăuga imagini la o ofertă? După publicarea unei oferte și obținerea ID-ului, folosiți addFile pentru încărcarea imaginilor Base64 cu detalii despre locație și descriere.
  2. Ce formate de fișiere video sunt acceptate? Trimiteți linkuri către YouTube, Vimeo sau tururi virtuale în câmpul VIDEO_INFO sub formă de JSON.
  3. Ce se întâmplă dacă există deja o imagine în sistem? Verificați existența cu existsFile; dacă imaginea este deja stocată, nu mai este necesară reîncărcarea.

Erori și depanare

  1. Ce se întâmplă dacă o ofertă nu are un agent asociat? Completați câmpurile CONTACT_PERS, CONTACT_TEL, CONTACT_EMAIL sau utilizați un AGENT_ID valid.
  2. Ce se întâmplă dacă oferta nu este publicată corect? Răspunsul API include detalii despre eroare; verificați câmpurile obligatorii și datele transmise.

🧪 Exemple de cod

Fragment PHP minimal

<?php
require 'ImopediaSoap.php';

$client = new ImopediaSoap('http://syncapi.imopedia.ro/api2/sync.wsdl', 'user', 'parola');
$client->connect();

$property = (object) [
    'AGENTIA' => 0,
    'ID_LOCAL' => 67654,
    'TITLU' => 'Apartament 2 camere în Giurgiului',
    'T_V_PRET' => '43423',
    'T_V_MONEDA' => 'EUR',
    'T_V_TRANZ' => 1,
];

$result = $client->execute('saveProperty', $property);
$client->disconnect();

Exemplu PHP extins

<?php

define('IMOPEDIA_USER', 'user');
define('IMOPEDIA_PASSWORD', 'parola');

include 'ImopediaSoap.php';
$imopedia = new ImopediaSoap('http://syncapi.imopedia.ro/api2/sync.wsdl?' . time(), IMOPEDIA_USER, IMOPEDIA_PASSWORD);
$imopedia->connect();

$agentia = 0; // ID-ul agenției, comunicat împreună cu datele de login

$run = [
    'camp_pret' => 'T_V_PRET',
    'camp_moneda' => 'T_V_MONEDA',
    'camp_tranz' => 'T_V_TRANZ',
];

$videos = json_encode([
    [
        'TITLE'    => 'Titlu video',
        'FILE_URL' => 'https://www.youtube.com/watch?v=akotZoPsG5M',
    ],
]);

$options = [
    'AGENTIA'           => $agentia,
    'ID_LOCAL'          => 67654,
    'DATA_MODIFICARE'   => '2012-01-11',
    'DATA_APARITIE'     => '2012-01-11',
    'ZONA'              => 'Giurgiului',
    'JUDET'             => 'Bucuresti',
    'COMISION'          => 2,
    'TITLU'             => 'Apartament 2 camere in Giurgiului',
    'SUPR_UTILA'        => '91.55',
    'GEO_LAT'           => '44.392663',
    'GEO_LONG'          => '26.089659',
    'AN_CONSTRUCTIE'    => 1960,
    'NRCAM'             => 5,
    'NRDORMITOARE'      => 3,
    'NR_BAI'            => 2,
    'NR_GR_SANITARE'    => 2,
    'DOTARI'            => '',
    'VECINATATI'        => '',
    'ACTE_DOBANDIRE'    => '',
    'TIP_IMOBIL_REAL'   => 3,
    $run['camp_pret']   => '43423',
    $run['camp_moneda'] => 'EUR',
    $run['camp_tranz']  => 1,
    'CONTACT_PERS'      => 'Geoerrge Popescu',
    'CONTACT_EMAIL'     => 'teest_agent@run.ro',
    'CONTACT_TEL'       => '0721117111',
    'AMPLASAMENT'       => '',
    'A_IMPARTIRE'       => '',
    'STARE_IMOBIL'      => '',
    'T_EXTRAVILAN'      => '',
    'T_INTRAVILAN'      => '',
    'T_AGRICOL'         => '',
    'NR_BALCOANE'       => 3,
    'REPER'             => 'Piata Progresul',
    'SUPR_ALTE'         => 'Baie 1: 5.54 mp, Bucatarie: 8.64 mp, Camera Zi (Living): 25.43 mp, Dormitor 2: 17.95 mp, Dormitor Matrimonial: 20.75 mp',
    'OBSERVATII'        => 'PIATA PROGRESUL - BLOC NOU. Straduta linistita de case, la cateva minute de bulevard dar ferita de trafic. Este o proprietate rafinata perfecta pentru o familie activa, intr-un bloc deosebit construit in 2008. Apartamentul are un decor minunat, un living perfect pentru recreere, baie cu hidromasaj, bucatarie mobilata si utilata. Cele trei balcoane ofera o panorama larga asupra imprejurimilor.',
    'ADDRESS'           => 'Adresa',
    'C_PIVNITA'         => '',
    'C_MANSARDA'        => '1',
    'T_D_APA'           => '1',
    'T_D_CANALIZARE'    => '1',
    'T_D_GAZE'          => '1',
    'T_D_CURENT'        => '1',
    'VIDEO_INFO'        => $videos,
];

$optionso = arrayToObject($options);
$soap_result = $imopedia->execute('saveProperty', $optionso);
$oferta_adaugata = $soap_result['_success'][0]['result']['property_id'] ?? null;

if ($oferta_adaugata) {
    $photos = [
        [
            'Location'            => 'http://clienti2.run.ro/usr/poze/thumb_612_x_0_309_1747.jpg',
            'Content-Description' => 'Descrierea pozei',
            'Object-ID'           => 4534,
        ],
    ];

    foreach ($photos as $photo) {
        $options['FILE_ID'] = md5($photo['Object-ID'] . $photo['Content-Description'] . $photo['Location']);
        $options['FILE_TITLE'] = $photo['Content-Description'];
        $optionso = arrayToObject($options);

        $rrr = $imopedia->execute('existsFile', $optionso);
        if (($rrr['_success']['0']['photo']['exists'] ?? 0) == 1) {
            continue;
        }

        $options['FILE_BODY'] = base64_encode(file_get_contents($photo['Location']));
        $optionso = arrayToObject($options);
        $imopedia->execute('addFile', $optionso);
    }
}

$imopedia->disconnect();

function objectToArray($data)
{
    if (is_array($data) || is_object($data)) {
        $result = [];
        foreach ($data as $key => $value) {
            $result[$key] = objectToArray($value);
        }
        return $result;
    }
    return $data;
}

function arrayToObject($array)
{
    if (!is_array($array)) {
        return $array;
    }

    $object = new stdClass();
    if (count($array) > 0) {
        foreach ($array as $name => $value) {
            $name = trim($name);
            if (!empty($name)) {
                $object->$name = arrayToObject($value);
            }
        }
        return $object;
    }

    return false;
}

Clasă helper PHP

<?php
class ImopediaSoap
{
    public function __construct($url, $user, $password)
    {
        ini_set('soap.wsdl_cache_enabled', '0');
        ini_set('soap.wsdl_cache_ttl', '0');

        $this->user = $user;
        $this->password = $password;
        $this->client = new SoapClient($url, ['cache_wsdl' => 0, 'trace' => 1]);
    }

    public function connect()
    {
        $this->sess_id = $this->client->__soapCall('login', ['username' => $this->user, 'password' => $this->password]);
        return $this->sess_id;
    }

    public function disconnect()
    {
        $this->client->__soapCall('logout', ['session_id' => $this->sess_id]);
    }

    public function execute($method, $options)
    {
        $payload = [
            'session_id' => $this->sess_id,
            'options'    => $options,
        ];
        return $this->client->__soapCall($method, $payload);
    }
}

Payload JSON ilustrativ

{
  "AGENTIA": 0,
  "ID_LOCAL": 67654,
  "TITLU": "Apartament 2 camere în Giurgiului",
  "TAGURI": ["Sold"],
  "VIDEO_INFO": [
    {
      "TITLE": "Titlu video",
      "FILE_URL": "https://www.youtube.com/watch?v=akotZoPsG5M"
    }
  ],
  "GEO_LAT": "44.392663",
  "GEO_LONG": "26.089659"
}

📨 Suport & contact tehnic

Pentru detalii suplimentare contactați departamentul tehnic Imopedia.ro la support@imopedia.ro. End-pointul de test rămâne http://syncapi.imopedia.ro/api2/sync.wsdl.

⚠️ Secțiuni depreciate

Observații Ucraina (deprecated)

Pentru ofertele cu regim special pentru Refugiații din Ucraina utilizați câmpurile de mai jos (detalii în acest document):

Lista completă a câmpurilor poate fi regăsită aici: campuri & nomenclatoar.

Exemplu PHP pentru câmpurile prezentate mai sus:

$info['PRET_TEXT_DISCOUNT'] = 'Capacitate 4 persoane, disponibil de la 1 aprilie, pe o perioada de min. 2 luni. ..';
$info['T_I_PRET_DISCOUNT'] = 200;
$info['T_H_PRET_DISCOUNT'] = null;
$info['TAGURI'] = json_encode(['Ucraina']);
Nume câmp Tip Explicație
TAGURI string Un array encodat JSON cu diverse taguri disponibile. Taguri posibile: “Ucraina”.
PRET_TEXT_DISCOUNT string Text cu detalii și condiții în legătură cu prețurile cu discount.
T_I_PRET_DISCOUNT float Preț de închiriere cu discount.
T_H_PRET_DISCOUNT float Preț regim hotelier cu discount.