API e Homezone për CRM

CRM-ja juaj mund të publikojë pronat e një agjenti në Homezone.al dhe t'i mbajë të përditësuara: t'i krijojë, t'i përditësojë, t'i heqë nga publikimi dhe t'i fshijë. Kjo faqe është për zhvilluesit e CRM-së.

Merrni një token

Agjenti hap Profili → Lidhja me CRM-në, shtyp Krijo token dhe zgjedh çfarë mund të bëjë tokeni dhe sa kohë vlen.
Agjenti e kopjon tokenin te cilësimet e Homezone në CRM-në tuaj.
CRM-ja juaj e dërgon atë me çdo kërkesë. Pronat që krijon i përkasin llogarisë së atij agjenti.

Çdo llogari Homezone ka një token. Kur agjenti krijon një të ri ose e heq, tokeni i vjetër ndalon së punuari menjëherë dhe kërkesat tuaja marrin 401. Marrin 401 edhe kur tokeni skadon, nëse agjenti zgjodhi një datë skadimi. Ruajeni në serverin tuaj si një fjalëkalim, kurrë në një faqe interneti, në një aplikacion apo në një link.

Dërgoni një kërkesë

Të gjitha kërkesat shkojnë te https://apiv2.homezone.al me HTTPS. Kërkesat dhe përgjigjet janë në JSON.

Header	Vlera
`Authorization`	`Bearer` e ndjekur nga tokeni
`X-Finger`	Emri i CRM-së suaj, për shembull `bsp-crm`. Asnjëherë bosh.
`Content-Type`	`application/json`, përveç ngarkimeve (`multipart/form-data`)

Endpoint	Çfarë bën	Leja
`POST /media/upload`	Ngarkon një foto, kur linket e fotove tuaja nuk janë publike.	Të publikojë dhe përditësojë pronat e tua
`POST /property/save`	Krijon ose përditëson një pronë, bashkë me statusin e saj.	Të publikojë dhe përditësojë pronat e tua
`GET /property/load`	Lexon pronat e agjentit.	Të lexojë pronat e tua
`POST /property/delete`	Fshin prona.	Të fshijë pronat e tua

Çdo endpoint kërkon lejen pranë tij, atë që agjenti zgjedh te Profili → Lidhja me CRM-në. Çdo endpoint tjetër përgjigjet me 403. Asnjëri prej tyre nuk e ngjit një pronë sërish në krye të kërkimit: vetëm publikimi i parë i një prone i vendos datën.

Krijoni ose përditësoni një pronë

POST /property/save. Dërgoni gjithë pronën çdo herë, me id-në tuaj te external_id. Ruajtja e parë e krijon pronën; çdo ruajtje e mëpasshme me të njëjtin external_id e përditëson.

curl -X POST https://apiv2.homezone.al/property/save \
  -H "Authorization: Bearer $HOMEZONE_TOKEN" \
  -H "X-Finger: bsp-crm" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "BSP-58412",
    "status": "published",
    "contract_type": "rent",
    "category": "apartment",
    "title": "Apartament 1+1 me qira, Komuna e Parisit",
    "description": "70 m², i mobiluar, me ashensor.",
    "price": 700,
    "currency": "EUR",
    "pay_period": "monthly",
    "bedrooms": 1,
    "bathrooms": 1,
    "size": 70,
    "county": "Tiranë",
    "city": "Tiranë",
    "area": "Komuna e Parisit",
    "contact_name": "Jane Doe",
    "contact_email": "jane@example.com",
    "contact_phone": "+355691234567",
    "assets_url": ["https://cdn.example.com/58412/1.jpg", "https://cdn.example.com/58412/2.jpg"]
  }'

Përgjigjja:

{ "error": "", "errorCode": null, "id": 185276, "url": "https://homezone.al/…", "duplicates": [] }

id është id-ja në Homezone. Ruajeni: duhet për të fshirë pronën.
duplicates rendit pronat e publikuara që duken njësoj (titulli, çmimi, vendndodhja dhe fotoja kryesore). Prona juaj ruhet gjithsesi.
Me "status": "published", një pronë publikohet vetëm nëse ka kategori, qark dhe qytet, përshkrim, të paktën një foto, adresë ose zonë, si dhe emrin, emailin dhe telefonin e kontaktit. Përndryshe ruhet si draft, pa gabim.
Ruajtja nuk e ngjit kurrë një pronë sërish në krye të kërkimit. Vetëm publikimi i saj i parë i vendos datën.

Foto

Dërgojini fotot në njërën nga dy mënyrat. Në të dyja, renditja në listë është renditja e shfaqjes dhe fotoja e parë është kopertina.

Linke, kur fotot tuaja janë publike: vendosini te assets_url. Çdo link duhet të hapet pa hyrë në llogari. Homezone i shkarkon fotot në çdo ruajtje, ndaj një ruajtje mund të zgjasë disa sekonda: prisni 60 sekonda para se ta ndërprisni.
Ngarkime, kur nuk janë publike: ngarkojeni çdo foto një herë (seksioni tjetër) dhe dërgoni id-të te assets: "assets": [{"id": 912345}, {"id": 912346}]. Kështu vepron aplikacioni i Homezone. Ruajini id-të dhe dërgoni të njëjtat në ruajtjet e mëpasshme: asgjë nuk shkarkohet sërish, ndaj ruajtjet mbeten të shpejta.

Dërgoni të gjitha fotot në çdo ruajtje. Një foto që mungon në listë hiqet nga prona dhe id-ja e saj nuk mund të përdoret më: ngarkojeni sërish nëse ju duhet. Një ruajtje pa asnjë foto i mban fotot aktuale, por e ruan pronën si draft.

Ngarkoni një foto

POST /media/upload si multipart/form-data, me të njëjtat header-a Authorization dhe X-Finger.

Fusha	Vlera
`file`	Imazhi, me një emër skedari që mbaron me prapashtesën e tij.
`fileSize`	Madhësia e gjithë skedarit në bajt.
`tempFileName`	Bosh. E përdorin vetëm pjesët e një skedari të madh (më poshtë).

curl -X POST https://apiv2.homezone.al/media/upload \
  -H "Authorization: Bearer $HOMEZONE_TOKEN" \
  -H "X-Finger: bsp-crm" \
  -F "file=@58412-1.jpg" \
  -F "fileSize=834512" \
  -F "tempFileName="

Përgjigjja:

{ "status": 1, "message": "File uploaded", "id": 912345, "thumbUrl": "https://media.homezone.al/…", "path": "2026/11/07/…" }

Dërgojeni çdo skedar me një kërkesë, deri në 50 MB. Një skedar më të madh dërgojeni me pjesë, me radhë, siç bën aplikacioni i Homezone me pjesë 1 MB. Pjesa e parë ka tempFileName bosh, dhe fileSize është gjithmonë madhësia e gjithë skedarit. Çdo përgjigje para të fundit thotë "Chunk uploaded" dhe jep një tempFileName për pjesën tjetër. Përgjigjja e fundit ka id-në.
JPEG, PNG, WebP ose GIF. Çdo lloj tjetër merr përgjigjen 400 UNSUPPORTED_MEDIA.
Një foto e ngarkuar mund të përdoret vetëm në pronat e të njëjtit agjent.
Ngarkoni vetëm fotot që do të ruani: një foto që nuk lidhet kurrë me një pronë mbetet e ruajtur.

Fushat

Fusha	Vlerat	Shënime
`external_id`	tekst	Id-ja juaj. Një ruajtje me një id të njohur përditëson në vend që të krijojë.
`external_url`	link	Prona në faqen tuaj. Opsionale.
`status`	`published`, `draft`	Si parazgjedhje draft.
`contract_type`	`sale`, `rent`
`category`	`apartment`, `house`, `vila`, `studio`, `penthouse`, `development`, `commercial`, `shop`, `store`, `bar`, `bar_restaurant`, `hotel`, `office`, `land`, `park`, `property`	E nevojshme për publikim.
`title`	tekst	Deri në 128 karaktere.
`description`	tekst	E nevojshme për publikim.
`price`	numër
`currency`	`EUR`, `USD`, `ALL`	Si parazgjedhje EUR. ALL ruhet në EUR me 100 lekë për euro.
`pay_period`	`daily`, `weekly`, `monthly`, `yearly`	Vetëm për qira. Si parazgjedhje monthly.
`bedrooms`, `bathrooms`, `floor`	numra
`size`, `land_size`	numra	Në m².
`build_year`	vit	Opsionale.
`facilities`	`cable_tv`, `cable_data`, `central_heating`, `dishwasher`, `dryer`, `washing_machine`, `garden`, `balcony`, `gas_heating`, `internet`, `alarm`, `parking`, `reception`, `wheelchair_access`, `microwave`, `serviced_property`	Një listë.
`has_certificate`, `contact_whatsapp`	`0`, `1`
`energy_class`	`A+`, `A` … `G`, `null`
`energy_indicator`	nga 0 deri në 2000, ose `null`	kWh për m² në vit.
`country`	`AL`
`county`, `city`	tekst	E nevojshme për publikim.
`area`, `address`	tekst	Njëra nga të dyja nevojitet për publikim.
`latitude`, `longitude`	numra
`contract_status`	`available`, `rented`, `sold`, `withdrawn`, `sale_agreed`	Si parazgjedhje available.
`contact_name`, `contact_email`, `contact_phone`	tekst	E nevojshme për një pronë të re dhe për publikim.
`expiry_date`	datë	Si parazgjedhje një vit pas ruajtjes.
`assets_url`	listë linkesh	Foto publike. Shihni Foto.
`assets`	listë me `{"id": …}`	Foto të ngarkuara. Shihni Foto.

Një fushë numerike që merr diçka tjetër ruhet si 0. Fushat që i vendos vetë Homezone (user_id, agency_id, publish_date, views e të ngjashme) shpërfillen.

Hiqni një pronë nga publikimi

Hiqeni nga publikimi: ruajeni me "status": "draft". Kur e ruani sërish me "published", ajo rikthehet me datën e vjetër.
E shitur ose e dhënë me qira: ruajeni me "contract_status": "sold" ose "rented".
Fshini: POST /property/delete me id-të e Homezone, [185276, 185277]. Përgjigjja i numëron: {"result": 2}. Një ruajtje e mëvonshme me të njëjtin external_id e rikthen pronën.

Fiton versioni i CRM-së suaj. Ndryshimet e agjentit në Homezone zëvendësohen në ruajtjen e radhës, dhe një pronë e fshirë në Homezone rikthehet në ruajtjen e radhës me external_id-në e saj. Që një pronë të mos shfaqet në Homezone, hiqeni nga publikimi ose fshijeni nga CRM-ja.

Lexoni pronat e agjentit

GET /property/load?externalId=BSP-58412 gjen një pronë sipas id-së suaj.
GET /property/load?status=published&page=1&limit=100 i rendit ato, deri në 200 për faqe. Përgjigjja është {"properties": [...], "total": 120}.

Gabimet

Përgjigjja	Pse	Çfarë të bëni
`401`	Tokeni është hequr, zëvendësuar ose ka skaduar, ose llogaria është mbyllur.	Kërkojini agjentit një token të ri. Mos provoni sërish.
`403 domain is not authorized`	Nuk ka token, ose tokeni nuk është krijuar nga Homezone: kontrolloni që të jetë kopjuar i plotë.	Dërgojeni tokenin si <code>Authorization: Bearer</code>.
`403 Missing fingerprint`	Mungon header-i `X-Finger`.	Shtojeni.
`403 This token is not allowed to do this`	Tokeni nuk ka lejen që kërkon ky endpoint, ose endpoint-i nuk është në këtë faqe.	Kërkojini agjentit një token me atë leje.
`400 UNSUPPORTED_MEDIA`	Një ngarkim që nuk është JPEG, PNG, WebP ose GIF.	Konvertojeni ose lëreni jashtë.
`400 INVALID_CONTACT`	Një pronë e re pa emër, email dhe telefon kontakti.	Dërgoni të treja.
`400`	GET aty ku duhet POST.	Përdorni POST.
`500`	Një problem nga ana jonë.	Provoni sërish më vonë.

Praktika të mira

Ruajeni një pronë vetëm kur diçka ka ndryshuar në CRM.
Dërgoni një kërkesë njëherësh për çdo agjent dhe prisni përgjigjen.
Provoni sërish gabimet e rrjetit dhe 500 pas 1, 5 dhe 15 minutash. Mos provoni sërish për 400, 401 ose 403.
Përdoreni çdo external_id vetëm për një pronë dhe mos e ripërdorni kurrë.
Ruajeni id-në e Homezone pranë id-së suaj.