Versiyalar və API dəyişiklikləri

Son yeniləmə: 2026-11-0612 dəq oxu

Versiya

Əsas versiya yolda göstərilir: /api/v1. v1 daxilində mövcud inteqrasiyaları sındırmırıq. Müqavilənin cari versiyası /openapi.json faylındakı info.version dəyəridir; o, hər dəyişikliklə artır.

Xəbərdarlıqsız nə dəyişə bilər

Bu dəyişikliklər uyğundur və klientiniz onların öhdəsindən gəlməlidir:

yeni əməliyyatlar və alətlər;
sorğunun yeni istəyə bağlı sahələri;
cavabın yeni sahələri;
cavab siyahılarında (statuslar, kodlar) yeni dəyərlər, title daxilində yeni xəta kodları, yeni vebhuk hadisə tipləri;
detail mətninin dəyişməsi;
daha yüksək limitlər.

Klientin yazılması

Cavabın naməlum sahələrinə məhəl qoymayın.
Naməlum siyahı dəyərini, xəta kodunu və ya hadisə tipini xəta kimi deyil, «digər» kimi qəbul edin.
Məntiqi detail mətni üzrə deyil, status, title və code üzrə qurun.
Sahələrin sırasına və ya id-nin uzunluğuna güvənməyin.
Alətin xam status dəyərinə deyil, tapşırığın state dəyərinə güvənin.

Nə sındırıcı dəyişiklik sayılır

Əməliyyatın, sahənin, scope-un və ya hadisənin silinməsi və ya adının dəyişdirilməsi; sorğunun yeni mütləq sahəsi; sahənin tipinin və ya mənasının dəyişməsi; eyni hal üçün status kodunun dəyişməsi; icazəli dəyərlərin daraldılması. v1 daxilində belə dəyişiklikləri xəbərdarlıqsız etmirik: əməliyyat əvvəlcə /openapi.json faylında və bu jurnalda deprecated kimi işarələnir və ən azı 6 ay işləməyə davam edir. İstisna - zəifliyin aradan qaldırılmasıdır.

Cavabı bu sənədlərə uyğunlaşdıran düzəliş sındırıcı dəyişiklik deyil.

Dəyişikliklər jurnalı

2026-11-09 - versiya 1.21

Əlavə edildi:

POST /site/create üçün Prefer: respond-async rejimi: dərhal sorğu tapşırığı ilə 202; GET /site/create/jobs/{id} (pulsuz) result daxilində əvvəlki 200 cavabını verir. Hadisələr site.completed / site.failed. Başlıq olmadan heç nə dəyişmir.
SDK 1.11.0: site.create respondAsync seçimini qəbul edir.

2026-11-08 - versiya 1.20

Əlavə edildi:

POST /draft/extract üçün Prefer: respond-async rejimi: fayllar yüklənir və dərhal sorğu tapşırığı ilə 202 gəlir; GET /draft/extract/jobs/{id} (pulsuz) result daxilində əvvəlki 200 cavabını verir. Hadisələr draft.completed / draft.failed. Başlıq olmadan heç nə dəyişmir.
SDK 1.10.0: draft.extract respondAsync seçimini qəbul edir.

2026-11-08 - versiya 1.19

Əlavə edildi:

review.action_required hadisəsi: hesabatın yoxlanması sənədi oxuyub və POST /valuation/review/jobs/{id}/confirm gözləyir. Hər yoxlama üçün bir dəfə, onun id-si ilə gəlir, Prefer: respond-async ilə işə salındıqda da. Əvvəllər bunu yalnız sorğu ilə öyrənmək olardı.

2026-11-06 - versiya 1.18

Əlavə edildi:

POST /floorplan/create və POST /valuation/review üçün Prefer: respond-async: fayllar qəbul edilir, sonra dərhal sorğu tapşırığı (areq_… kimi jobId) və Location, Retry-After, Preference-Applied başlıqları ilə 202. Status: eyni yolda, GET /floorplan/create/jobs/{id} və GET /valuation/review/jobs/{id} (pulsuz); result başlıqsız sorğudakı ilə eyni 202 gövdəsini ehtiva edir (hesabatın yoxlanması yenə də confirm tələb edir). Başlıq olmadan heç nə dəyişmir.
Xidmətin yenidən başladılması ilə kəsilmiş sorğu tapşırığı code: interrupted ilə failed vəziyyətində bitir: heç bir ödəniş tutulmur və Idempotency-Key azad edilir - eyni sorğunu eyni açarla yenidən göndərin.
SDK 1.9.0: floorplan.create və valuation.review respondAsync parametrini qəbul edir; interrupted sonrası klient eyni formanı eyni açarla özü yenidən göndərir, ən çoxu iki dəfə.

2026-11-05 - versiya 1.17

Əlavə edildi:

POST /valuation/express və POST /valuation/rent üçün Prefer: respond-async: dərhal tapşırıq və Location, Retry-After, Preference-Applied başlıqları ilə 202. Status: GET /valuation/express/jobs/{id} və GET /valuation/rent/jobs/{id} (pulsuz); result sinxron 200 ilə eyni gövdəni, error isə eyni problemi ehtiva edir. Başlıq olmadan çağırışlar sinxron qalır.
Vebhuk hadisələri express.completed, express.failed, rent.completed, rent.failed.
SDK 1.8.0: Idempotency-Key avtomatik yaradılır; bağlantı qırıldıqdan, vaxt bitdikdən, 502, 504, 524 və 409 idempotency_conflict sonrası çağırış eyni açarla təkrarlanır, ən çoxu retryWindowMs (10 dəqiqə) ərzində; respondAsync parametri və jobs.result metodu.

Dəyişdirildi:

524 və ya 504 sonrası Idempotency-Key artıq azad edilmir: iş bitmiş və ödənişi tutulmuş ola bilər. Eyni açarla təkrar sorğu ikinci ödəniş olmadan hazır nəticəni qaytarır, birinci çağırış hələ icra olunarkən isə 409 alır.

2026-10-03 - versiya 1.16

Dəyişdirildi:

429 code daşıyır: minute_limit və ya daily_limit (açarın gündəlik limiti, 00:00 UTC-də sıfırlanır).
Agentlik açarı ilə yazılmış obyekt agentliyə məxsusdur; agentlik obyektlərinin və lidlərinin object.* və lead.* vebhukları agentliyin endpoint-lərinə də çatır.
Obyekt fotoları: kabinetdəki kimi, bütün növlər üçün 50-yə qədər.
SDK 1.7.2: boş axın hissəsi artıq çat hadisəsini bölmür.

Düzəldildi:

PUT /objects/{kind}/{id} elanın moderasiya vəziyyətini, isSold dəyərini və dərcini saxlayır; əvvəllər onları sıfırlayırdı (adi redaktə aktiv elanı dərcdən çıxarırdı).
GET /objects artıq fəaliyyəti dayandırılmış sahiblərin obyektlərini siyahıya salmır; qonaqlardan gizlədilmiş kart id üzrə də göstərilmir.
PATCH /leads/{id}: müqaviləsiz lidin göndəricisi kabinetdə olduğu kimi onun statusunu dəyişə bilər; dəyişiklik və arxiv lidin tarixçəsinə yazılır.

2026-10-03 - versiya 1.15

Dəyişdirildi:

PATCH /leads/{id} (status) və DELETE /leads/{id} kabinet qaydalarına əməl edir: yekunlaşdırma, komissiyanın toplanması, aktiv müqavilə və ya razılaşma - səbəbi code daxilində olan 422. ?expand=history artıq xidməti metaməlumatları (tokenlər, digər istifadəçilərin id-ləri) daşımır.
Çatın pulsuz gündəlik limiti 00:00 UTC-yə qədər Retry-After ilə code: free_daily_limit cavabı verir.
GET /works: previewUrl, link və object.photoUrl GET /artifacts/{path} üçün /files/... yollarıdır; son səhifədə nextCursor null olur.
Lidin yazılması: naməlum sahələr atılır (rədd edilmir); xidmətin tətbiq etdiyi uzunluqlar spesifikasiyadadır; pool: true lidi platformanın puluna verir.
SDK 1.7.1: jobs.wait 429 bitənə qədər gözləyir; chat.stream hissələr arasında bölünmüş CRLF-i emal edir; artifact() signal qəbul edir.

Düzəldildi:

Musiqi önizləməsi: sonu aşan Range - 416 (əvvəllər 404 kimi cavablandırılırdı); fayl xidmətinin nasazlığı 404 deyil, 502-dir.
POST /uploads daxilində 15 MB-dan böyük fayl - 413. Rədd edilmiş strictPhotos elanı yüklənə bilməyən fotoların adlarını göstərir (code: photo_fetch_failed).
Kontent paketinin imtinası form.media.photos sahəsini göstərir. Sandbox: yoxlama istənilən adlı ilk faylı götürür; icarə sətirləri və foto xidmətinin açarları rədd edilmir.

2026-10-03 - versiya 1.14

Dəyişdirildi:

Eyni Idempotency-Key ilə ekspres qiymətləndirmənin təkrarı indi tamamilə pulsuzdur: API çağırışı üçün də ödəniş tutulmur.
GET /works: nextCursor olmayan cursor - 400 (əvvəllər siyahı səssizcə yenidən başlayırdı).
POST /webhooks/{id}/test: siyahıda olmayan eventType - 400 (əvvəllər ümumi test göndərirdi).
Swipe Match: reasonCode yalnız siyahıdakı səbəbləri qəbul edir, xidmətin həmişə tələb etdiyi kimi; lidin kind dəyəri pool ola bilər.
SDK 1.7.0: jobs.wait qırılmış sorğulamadan sağ çıxır; artifact() range qəbul edir; chat.stream CRLF axınlarını oxuyur və hər hadisəyə bir çağırış verir.

Düzəldildi:

Musiqi önizləməsi: bytes=-N son N baytı qaytarır, sonu aşan Range - 416.
Sorğu göndərilməzdən əvvəl bağlantının vaxtının bitməsi Idempotency-Key açarını azad edir.
Sandbox: xidmətin oxuduğu istənilən sahə adı altında video fotoları, sətir kimi göndərilmiş icarə rəqəmləri, göstərilmiş ölçüdə flayer PNG-ləri.

2026-10-03 - versiya 1.13

Əlavə edildi:

GET /works kabinetin hər nəticə üçün göstərdiyini qaytarır: street, streetNumber, previewUrl, link, repeatIndex, error və elan (object).
GET /chat/sessions öz parametrlərini sənədləşdirir: limit, cursor, q, projectId, archivedOnly, sort.
Spesifikasiyada Problem.title range_not_satisfiable dəyərini sadalayır; vebhuk siyahısı requestId daşıyır.
SDK 1.6.1: chat.listSessions siyahı parametrlərini qəbul edir.

Dəyişdirildi:

Spesifikasiya prodakşnın artıq tətbiq etdiyi limitləri göstərir: avatar scriptText 1200 simvola qədər, flayer formats 3-ə qədər və layouts 5-ə qədər, flayer contacts sahələrinin uzunluqları, foto seed 2147483647-yə qədər və foto data daxilində naməlum açarların olmaması.
Ekspres qiymətləndirmə: şlüz yalnız ümumiyyətlə sahəsi və əmlak tipi olmayan sorğunu rədd edir; landPlotArea dəyərinin sayılıb-sayılmamasına xidmət qərar verir (propertyType və ya apartmentType daxilində adı çəkilən torpaq da sayılır).

Düzəldildi:

Sandbox fotoları prodakşndakı kimi rədd edir (25 MB-a qədər JPEG, PNG və ya WebP - JOB_CREATE_FAILED; təmizləmədən kənar maska - MASK_NOT_SUPPORTED) və prodakşnın kəsdiyi və ya əvəz etdiyi şeyləri qəbul edir (video başlığı, səs səviyyəsi, son kadr və yekun ifadə parametrləri, landing səhifənin dili, 20-dən çox kontent fotosu, söz kimi icarə furnished). Hesabat tapşırığı artıq running sonrası pending göstərmir.
Rədd edilmiş endirmə yönləndirməsi vaxtın bitməsi əvəzinə bunu bildirir; fayldan uzun Range suffiksi bütün faylı qaytarır.
SDK 1.6.1: verifyWebhookSignature Node 18-də işləyir.

2026-10-03 - versiya 1.12

Əlavə edildi:

RFC 9457 problemi kimi 416 range_not_satisfiable (əvvəllər boş gövdə ilə gəlirdi).
Foto yaxşılaşdırmanın başladılmasında priceMinor: çağırış üçün tutulan məbləğ, kabinetin göstərdiyi kimi.
SDK 1.6.0: works from/to, chat.history limit/cursor, chat.sendMessage style qəbul edir.

Dəyişdirildi:

GET /match/leads: 50-dən çox limit və ya 1000-dən çox page 400 cavabı verir (heç vaxt kəsilmirdi). POST /match/leads/{id}/events: başqa formatlı Idempotency-Key səssizcə atılmaq əvəzinə 400 olur.
Flayerin rədd etdiyi sahə sahənin adını göstərən 400 validation olur (əvvəllər 422 idi).
Ödənişi eyni Idempotency-Key altında hələ rezerv edilən çağırış - 409 idempotency_conflict (əvvəllər 422 idi).
Ekspres qiymətləndirmə: landPlotArea xidmətdə olduğu kimi yalnız land üçün sahə kimi sayılır.
Vaxtın bitməsi, sıfırlanmış bağlantı və ya cavabın ortasında bağlanmış soket Idempotency-Key açarını tutulmuş saxlayır; yalnız xidmətə heç vaxt çatmamış sorğu onu azad edir.
SDK 1.6.0: yükləmə 503 sonrası heç vaxt təkrarlanmır; hər fasilədən sonra abort dinləyicisi silinir.

Düzəldildi:

PDF və landing səhifə imtinaları səbəbini daşıyır: INSUFFICIENT_FUNDS və ya QUOTA_EXCEEDED ilə 402 (əvvəllər code olmadan 422 idi).
Sandbox prodakşnın rədd etdiyini dəqiq rədd edir: yüklənən faylların tipi və ölçüsü; mətnlər rədd edilmək əvəzinə kəsilir; naməlum video length, aspect və language standart dəyərə qayıdır; flayer kodları böyük-kiçik hərfə həssas deyil; type olmadan qaralama. Vəsait çatışmazlığı simulyasiyası prodakşnın göndərdiyi kod olan INSUFFICIENT_FUNDS cavabı verir.
limit və page diapazona şlüzün özü tərəfindən salınır (GET /chat/history?limit=500 400 cavabı verirdi; limit=0 1 əvəzinə 20 verirdi).

2026-10-03 - versiya 1.11

Əlavə edildi:

Tapşırıq nəticələri kabinetin göstərdiyi sahələri daşıyır: kontent paketi, mətn və video - progress, masterProfile (mətnlərin və səsləndirmənin əsaslandığı süjet planı) və uğursuz tapşırıq üçün error; foto - metadata.error; mərtəbə planı - rooms[].stable, rooms[].placement, sourceFileId.
Brauzerlər (CORS) RateLimit-*, Retry-After, Grem-Sandbox, X-Request-Id və Content-Range başlıqlarını oxuya bilir.

Dəyişdirildi:

Vebhuklar: test açarı yalnız sandbox endpoint-lərini yaradır və idarə edir; onlar yalnız sandbox tapşırıqlarının hadisələrini alır, canlı endpoint-lər isə onları heç vaxt almır.
Diapazondan kənar limit və page 400 əvəzinə diapazona salınır; GET /objects daxilində kind böyük-kiçik hərfə həssas deyil; rooms kəsr ola bilər.
Idempotency-Key API açarına, metoda və faktiki yola aiddir (POST /objects/property və POST /objects/rental fərqli əməliyyatlardır). Vaxt bitdikdən sonra elan və lid yaratma sorğuları, alətlərdə olduğu kimi, açarı 15 dəqiqə saxlayır; xidmətə heç vaxt çatmamış sorğu onu azad edir.
text/generate: customDirection 500 simvola qədər kəsilir.
SDK 1.5.1: yazma əməliyyatında 503 yalnız Idempotency-Key ilə təkrarlanır; 30 saniyədən uzun Retry-After gözlənilmir; maxRetries ən çoxu 10-dur; sizin AbortSignal fasiləni ləğv edir; mesaj id-ləri Node 18-də işləyir.

Düzəldildi:

Sandbox prodakşn kimi işləyir: multipart sahələrinin, kateqoriya üzrə hesabat sahələrinin, ev istiliyi dəyərlərinin, kommersiya apartmentType və komplekslərin yoxlanması; fayllar yalnız tamamlanmış tapşırıqlar üçün, alətin öz yolunda və məlum artefakt id-ləri ilə; Grem-Sandbox açar yoxlamasından əvvəl verilən cavablarda da; Grem-Simulate böyük-kiçik hərfə həssas deyil.
Açar olmadan etibarsız sorğu parametrləri əvvəlcə 401 cavabı verir.
Agent səviyyəli agentlik açarı artıq agentlik səviyyəli açarla başladılmış tapşırıqları oxumur.
Əvvəllər başqa portda saxlanmış vebhuk endpoint-ləri çatdırılmaları almağa davam edir.
Təmin edilə bilməyən Range 404 əvəzinə 416 cavabı verir; 40 MB-a qədər hesabat yoxlaması sənədi qəbul edilir.

2026-10-03 - versiya 1.10

Əlavə edildi:

conflict xəta kodu (409): resurs əməliyyata imkan verməyən vəziyyətdədir (Xətalar).
POST /video/create daxilində videonun yekun ifadə sahələri: ctaMode, ctaIntent, ctaText, ctaMarket; GET /video/endings variantları intent və text daşıyır.
GET /works: from və to filtrləri.
SDK 1.5.0: maxRetries parametri - 429 və 503 Retry-After sonrası təkrarlanır.

Dəyişdirildi:

Sorğu parametrləri yoxlanılır: etibarsız dəyərli məlum parametr sahənin adını göstərən 400 validation olur.
Vebhuklar: yalnız 443 portunda https, URL-də giriş məlumatları olmadan; 11-ci ünvan - 422; agentlik vebhukları yalnız agentlik səviyyəli açarla idarə olunur.
Idempotency-Key API açarına və əməliyyata aiddir; alətin vaxtı bitdikdən sonra açar 15 dəqiqə rezervdə qalır.
Pul imtinaları (kvota, borc, ədalətli istifadə, balans) code ilə 402 insufficient_funds olur.
Agent səviyyəli agentlik açarı yalnız öz tapşırıqlarını və fayllarını görür.
Faylların endirilməsi sorğu limitinə daxil edilir.

Düzəldildi:

Hər xəta, o cümlədən çox böyük və ya səhv formalaşmış gövdə, RFC 9457 application/problem+json kimi gəlir; limiti aşan gövdə - 413 payload_too_large.
Videonun ending sahəsi heç vaxt oxunmurdu; ctaIntent və ya ctaText istifadə edin.
SDK: canlı açarla simulate çağırışı icra etmək əvəzinə xəta atır.

2026-10-03 - versiyalar 1.8-1.9

Əlavə edildi:

Analoq elanlar: ekspres qiymətləndirmədə estimate.analogs, tam hesabatda analogs, icarə qiymətləndirməsində comps - kabinetdə və PDF-də olduğu kimi.
Tamamlanmış tapşırıqların sahələri tam təsvir edilib: hesabat göstəriciləri real adları ilə (potPrice, priceRangeLow, priceRangeHigh, …), yoxlama, mərtəbə planı, foto, flayer, qaralama.
SDK 1.4.0: Analog tipi.

Dəyişdirildi:

Alət cavabları yalnız sənədləşdirilmiş sahələri daşıyır; əvvəllər sızan daxili sahələr artıq qaytarılmır.
GET /tools/status əlçatan olmadığını bildirdiyi alət hər hansı ödəniş tutulmazdan əvvəl 503 service_unavailable cavabı verir (əvvəllər bu, yalnız kontent paketi, mətnlər və video üçün keçərli idi).
Qiymətləndirmə yoxlamasının təsdiq cavabı yalnız tapşırıq sahələrini (jobId, state, status) daşıyır; köhnəlmiş _id orada artıq qaytarılmır.

Düzəldildi:

Avatar video: artifacts endirmə URL-i üçün lazım olan id-ləri sadalayır.
İcarə üçün checkIn/checkOut günün saatları kimi sənədləşdirilib.

2026-10-02 - versiya 1.7

Əlavə edildi:

Sandbox: test açarları (gsk_test) alətləri ödənişsiz simulyasiya edir; Grem-Simulate başlığı nəticəni seçir.
Ekspres qiymətləndirmədə estimate.confidenceScore.

Dəyişdirildi:

Aləti işə salan çağırışlar 60 saniyə əvəzinə 5 dəqiqəyə qədər gözləyir.
Eyni Idempotency-Key ilə təkrarlanan ekspres qiymətləndirmə, vaxt bitdikdən sonra da, ikinci ödəniş olmadan hazır nəticəni qaytarır.

Düzəldildi:

Ekspres qiymətləndirmənin estimate.confidence dəyəri həmişə null idi.
Mərtəbə planı cavabları artıq daxili sahələr daşımır.
kind olmadan GET /objects, həmçinin elanlar və lidlər üçün imtinalar indi səbəbi detail daxilində izah edir.

2026-10-02 - versiya 1.6

Dəyişdirildi:

Hər tapşırıq cavabı eyni jobId sahəsini daşıyır. Alətlərə məxsus id, _id, contentGenJobId adları hələ də qaytarılır və köhnəlmiş sayılır.
SDK 1.2.0: Job.jobId həmişə mövcuddur.

2026-10-02 - versiyalar 1.2-1.5

Əlavə edildi:

GET /voices, GET /avatar/avatars, GET /video/music, GET /video/endings - alətlər üçün id-lər (Arayış məlumatları).
GET /tools/status - alətlərin əlçatanlığı; GET /works - işlərin tarixçəsi.
POST /flyer/create - şəxsi flayer, scope tools:flyer.
POST /valuation/review/jobs/{id}/confirm - hesabat yoxlaması məlumatlarının təsdiqi.
Hər tapşırıq cavabında state sahəsi.
Xətalarda - code və errors sahələri, forbidden, payload_too_large, service_unavailable kodları.
API təsvirində - hər alət üçün tam sorğu və cavab sxemləri, hər növ üzrə elan yazmanın tam müqaviləsi, hər əməliyyatın ödəniş sinfi (x-grem-billing), scope-ların və hadisələrin siyahısı.
scope (elanlar) və pool (lidlər) parametrləri sənədləşdirilib.

Dəyişdirildi:

Çatışmayan məlumatlara görə imtina (məsələn, təsvirsiz və ya şəhərsiz mətnlər) indi səbəb və kodla 422 business_rule olur. Əvvəllər 502 provider_error idi.
Resurs icazələrinə görə imtina indi səbəblə 403 forbidden olur. Əvvəllər 500 idi.
Alətlər üçün test vebhuk çatdırılması realı ilə eyni formadadır: { jobId, status, state }.

Düzəldildi:

Agentlik açarları bütün alətlərlə, çatla və faylların endirilməsi ilə işləyir.
Hesabatın yoxlanması və mərtəbə planı: tapşırığın statusu cavabdakı id üzrə əlçatandır, vebhuklar gəlir.
Kontent paketi, mətn və video fayllarının endirilməsi - yalnız tapşırığın sahibi üçün.

Əlaqəli

Bu məqalə faydalı oldu?