README

自动加载（API）

系统的目的是，让拥有 ingatlan.com "自动加载" 订阅的房地产中介通过接口从自己的记录系统中上传和管理他们的广告。

重要

目前我们不销售 "自动加载" 产品，在开始任何相关开发之前，请访问 ingatlan.com 客户服务联系人。

对于使用 "自动加载" (API) 提交的错误数据（这些数据在机器验证中不会失败）导致出现，供应商不承担责任。使用 "自动加载" 上传广告的客户应了解，如果他们未在自己的系统中修改，则管理员界面上的引用所做的更改将在下一次加载时被覆盖。
如果希望在 ingatlan.com 上上传/删除/修改广告，这不应该在 ingatlan.com 管理系统中完成，而应该在您的系统中更新并通知本地 IT 人员/系统管理员启动加载。
自动加载不处理拍卖、突出显示、引用。这仍然可以在管理员界面上由引用完成。
使用自动加载无法发布 "新建筑" 广告。如果广告以 "conditionType=3" 接收，我们将将其保存为 "conditionType=0" 状态，并通知其进入界面手动设置希望将其设置为新建筑状态的哪些（只能转换他们所购买的新建筑补充件的数量）。如果已经设置了一个广告的状态（并且还有有效的框架），则不会在重新加载时覆盖该广告的状态。

技术信息

API URL: https://api.ingatlan.com

API 遵循标准的 REST 协议，并且需要以 JSON 格式提交数据。JSON 响应遵循 JSend 建议。

用于身份验证的是 JSON Web Token 技术。API 登录令牌的有效期为 1 小时。

API 端点可以在以下地址查看： https://api.ingatlan.com/v1/doc

API nem rendelkezik külön CREATE és UPDATE funkciókkal; PUT kérés esetén, ha az adott azonosítóval már létezik erőforrás, akkor frissíti; ha nem, létrehozza azt.

Regisztráljon a github repository frissítéseire, és új verzió kikerülésekor frissítse a klienst!

Fejlesztés

API ügyfél oldalának beállítása során technikai támogatást nyújtunk.

Ez tartalmazza

teszthozzáférés biztosítása
éles üzembe állításkor előkészületek
ingatlan.com rendszerében már lévő hirdetések megfeleltetése az API-n keresztül beküldöttekkel (kizárólag tökéletesen megegyező adatok esetekben párosíthatók).

Nem tartalmazza

egyedi igények ingatlan.com oldalú fejlesztése
beküldendő paraméterek módosítása
tesztirodák létrehozása az éles rendszerekben
ügyfél oldali hibák debugolása/javítása
éles rendszerbe hibásan küldött hirdetések/adatok visszaállítása

Modern PHP kódoláshoz kiegészítő információk

Adattípusok

Az API két adattípussal dolgozik, ezek a hirdetés és a fotó.

Hirdetés

Minden hirdetésnek rendelkeznie kell egy (partnerenként egyedi) azonosítóval (ownId), csak így tölthető be az ingatlan.com rendszerébe. Ez egy maximum 15 karakter hosszúságú string, amely lehetőség szerint megfelel az alábbi reguláris kifejezésnek: /^[0-9A-Za-z-_]{1,15}$/

A hirdetés paramétereinek listája és magyarázata itt tekinthető meg: https://api.ingatlan.com/v1/doc/fields

A hirdetés paramétereinél értelemszerűen a kötelező mezők kötelezően kitöltendőek a felsorolt értékkészletből. Javasoljuk, hogy az opcionális mezők is kitöltve érkezzenek.** A hibás vagy hiányos paraméterekkel érkező hirdetések nem kerülnek feltöltésre. ** Ha valamely paraméter hiányzik vagy hibás, az API visszajelzi a hibát a JSend ajánlás szerinti formátumban. A lehetséges hibaüzenetek listája is a fenti dokumentációban látható.

A megjegyzés (description) mező kötelező, legalább 5 és legfeljebb 10000 karakter hosszú lehet.

A fűtés (heatingType) mező egy maximum 2 elemű tömb amibe az értékkészlet szerinti fűtéseket lehet megadni. Alapértelmezett értéke 0 és ha 2-nél több elem érkezik benne, akkor az első kettőt menti el. A fűtés kizárólag lakás, ház, nyaraló és intézmény típusoknál adható meg.

Az alábbi mezők nem módosíthatók

listingType
propertyType
city
projectId

Amennyiben ezekbe nem megfelelő adat került, a hirdetés törlés után új sajátId-vel adható fel újra.

Intelligens API

Ha olyan mezőkben is kap adatot, amelyek az adott ingatlantípusnál nem szerepelhetnek, az esetek többségében kijavítja ezeket, 0/NULL értékekre. Ezek megjelenítésére kitérünk a mintakódban.

A hirdetések egyik legfontosabb jellemzője az elhelyezkedés, ezért az API minden esetben ellenőrzi a feltöltött adatokat. A pontatlanul megadott címeket a rendszer megpróbálja valós elhelyezkedési adatokra javítani, de az esetleges hibás megjelenésért a Szolgáltató nem vállal felelősséget.

A városok és városrészek listája megtekinthető az alábbi tömörített állományban.

Az Automata Betöltés használatakor, a fentiekben jelzett tömörített állományokban található elhelyezkedési adatokat fogadjuk el. Amennyiben pl. "nem megfelelő városrész" hibát tapasztalunk, a fentiekben lévőre kell azt az ügyfél oldalán javítani. Amennyiben az ingatlan.com térképadatbázisában hibát talál, kérjük jelezze felénk.

Fotó

Minden fotónak rendelkeznie kell egy (hirdetésenként egyedi) azonosítóval, csak így tölthető be az ingatlan.com rendszerébe. Ez egy maximum 32 karakter hosszúságú string, amely lehetőség szerint megfelel az alábbi reguláris kifejezésnek: /^[0-9A-Za-z-_]{1,32}$/

A fotó tömb kulcsai kép feltöltéskor

ownId: csak válaszban, a kép sajátId-ja
title: a kép felirata, string(100)
labelId: 图片标签的标识符，可选。可能的图片标签可在以下文件中找到：https://github.com/ingatlancom/api-client/blob/master/lib/ApiClient/Enum/PhotoLabelEnum.php。
order: 排序值，整数
imageData: 仅在请求中，图片文件的内容，base64编码

如果客户提供的图片不可用，将返回错误信息。ingatlan.com系统中最多可以上传30张图片，这同样适用于自动加载。

在查询图片时，数组中还包含以下键

md5Hash: 上传的、调整大小的图片MD5哈希值，我们可以用这个值来检查客户端在后续上传时是否需要重新发送图片
hasForbiddenWatermarkOrLogo: 图片是否符合服务条款中的描述（不能包含水印、标志或标签（除平面图上的标记外））。如果此处值为true，则表示自2017年11月15日起，我们不向搜索者展示该图片。在这种情况下，请上传图片的原始、未修改版本。如果原始图片中也存在true值，请登录到我们的管理界面，在广告编辑页面使用标记不合规的旗帜图标报告错误操作。然后我们的审核员将检查并处理该图片。

参考文献管理

参考文献的数据需要在“ingatlanreferensek kezelése”菜单下的office操作界面中记录。如果通过agentId发送的广告在相应的参考文献数据页面上以“saját id”的形式列出，则系统可以将广告分配给参考文献。使用不符合id发送的广告将转交给办公室管理员。如果没有填写agentId，则无法将广告分配给参考文献。填写agentId是参考文献和办公室的责任。

如果您使用自动加载，请勿在办公室之间移动参考文献或广告。在这种情况下，请联系ingatlan.com的联系人员，并请求技术支持。

ingatlan.com API客户端

https://github.com/ingatlancom/api-client

该客户端是一个PHP composer 包，除了展示API调用外，还包括多个实用功能的实现

广告同步
最优图片同步，包括缩放

安装

安装composer。（更多信息： https://composer.php.ac.cn/doc/）
创建一个包含以下内容的composer.json文件

{
    "require": {
        "ingatlancom/apiclient": "~3.0"
    }
}

使用以下命令启动安装

php composer.phar install

下载的包将放置在vendor文件夹中

使用

要使用客户端，需要用户名和密码，这些可以从ingatlan.com联系人员那里获得。

API客户端使用JWT令牌进行身份验证。成功认证后，客户端将获得一个令牌。将此令牌存储在一个Stash Pool中，以便每次调用之前无需登录。实例化池

$driver = new Stash\Driver\FileSystem(['path' => '/tmp/ingatlancom/']);
$pool = new Stash\Pool($driver);

（将"/tmp/ingatlancom"替换为您可以在服务器上存储临时文件的那个目录。）

实例化API客户端

$apiUrl = 'https://api.ingatlan.com';
$apiClient = new \IngatlanCom\ApiClient\ApiClient($apiUrl, $pool);

（在加载到生产系统时，$apiUrl的值为"https://api.ingatlan.com"。）

$apiClient->login('username', 'password');

以下操作只能在调用登录后执行。

上传广告

在$ad数组中指定广告的参数。（可提交字段的详细说明可在以下链接查看：https://api.ingatlan.com/v1/doc/parameters）

$ad = [
    'ownId'           => 'x149395',
    'listingType'     => 1,
    'propertyType'    => 1,
    'propertySubtype' => 2,
    'priceHuf'        => 17500000
     ...
];
$apiClient->putAd($ad);

查询广告

查询x149395 saját id广告

$ad = $apiClient->getAd('x149395');

如果调用成功，$ad变量将包含广告的值。

删除广告

删除x149395的自己的广告

$apiClient->deleteAd('x149395');

（实际上广告不会被删除，只会状态变为“删除但保留”。

查询办公室所有广告的ID

$ids = $apiClient->getAdIds();

成功调用时，$ids将是一个包含已上传广告ID的数组。

同步广告

syncAds()函数将从您系统中的ingatlan.com服务器上删除不再显示的广告。

在$ads数组中列出系统中的广告的自己的ID。

$ads = [
    'hirdetes1',
    'hirdetes2'
    ...
];
$ids = $apiClient->syncAds($ads);

同步图片

同步x149395自己的ID的广告的图片

use IngatlanCom\ApiClient\Enum\PhotoLabelEnum;

$photos = [
    [
        'ownId'    => 'kep1',
        'order'    => 1,
        'title'    => 'Képfelirat 1',
        'location' => 'http://lorempixel.com/800/600/city/1/',
        'labelId'  => PhotoLabelEnum::KORNYEK
    ],
    [
        'ownId'    => 'kep2',
        'order'    => 2,
        'title'    => 'Képfelirat 2',
        'location' => 'http://lorempixel.com/800/600/city/2/',
    ]
];
$ids = $apiClient->syncPhotos(
    'x149395',
    $photos,
    $forceImageDataUpdate,
    $uploadedPhotos,
    $paralellDownload
);

$photos

$photos数组中应有要上传的图片的数据。在调用syncPhotos()函数时，可以使用“location”键来指定图片数据。在此处需要提供图片文件的路径，可以是计算机上可访问的文件，也可以是URL。客户端将根据location字段读取图片文件，在必要时对其进行缩放，并在上传时以“imageData”形式发送图片内容。

$forceImageUpdate

默认情况下，syncPhotos()方法根据图片的md5哈希值判断图片是否已更改，并决定是否需要重新上传到ingatlan.com服务器。在syncPhotos()方法的第三个参数中可以关闭此检查，以便客户端始终上传广告的图片。

$uploadedPhotos

在$uploadedPhotos参数数组中应指定服务器上的图片。如果不知道这一点，最好将此参数设置为null，客户端将自动从服务器上检索图片。

$paralellDownload

在syncPhotos()方法的第五个参数中可以设置，如果合作伙伴的图片通过http协议下载，客户端将逐个或并行下载。默认情况下，此功能是关闭的，但如果合作伙伴的服务器没有问题，则可以启用。

图片的缩放是在客户端完成的，因此需要使用Imagick或GD PHP扩展。

上传图片

在$photoData数组中提供图片数据。有关图片数组值的详细信息，请参阅此处。

（在调用putPhoto()时，与syncPhotos()不同，不允许使用"location"键来指定图片数据。此处只能通过imageData键发送图片的base64编码内容。）

$photoData = [
    'ownId'    => 'kep3',
    'order'    => 3,
    'title'    => 'Képfelirat 3',
    'labelId'  => null,
    'imageData' => file_get_contents('kepem.jpg')
];
$ids = $apiClient->putPhoto('x149395', $photoData);

上传多个图片

在图片上传中提供多个图片。

$ids = $apiClient->putPhotosMulti('x149395', $photos);

删除图片

在x149395自己的ID的广告中删除kep123自己的ID的图片。

$ids = $apiClient->deletePhoto('x149395', 'kep123');

删除多个图片

在$photoIds数组中指定要删除的图片的自己的ID。

在x149395自己的ID的广告中删除图片

$photoIds = ['kep1', 'kep2'];
$ids = $apiClient->deletePhotosMulti('x149395', $photoIds);

查询广告图片

查询x149395自己的ID的广告的图片

$photos = $apiClient->getPhotos('x149395');

成功调用时，$photos将是一个包含广告图片数据的数组。

排序广告图片

在x149395自己的ID的广告中对图片进行排序

$photoOrder = ['kep1', 'kep2', 'kep3'];
$ids = $apiClient->putPhotoOrder('x149395', $photoOrder);

在$photoOrder数组中，图片的自己的ID应按照所需顺序排列。

检查API状态

可以通过调用checkApiStatus()函数来查询API状态。如果所有子系统都运行正常，则该函数返回true，如果由于某种错误原因加载失败，则返回false。即使客户端有问题（例如没有互联网连接，客户端无法连接到服务器），也返回false。

$isOk = $apiClient->checkApiStatus();

示例代码

一个示例可以在example/example.php文件中看到。示例代码仅供参考，不强制使用。

ingatlancom / apiclient

维护者

详细信息