开发者文档 · JSON REST API v1

面向房地产中介和个人客户：在您的账户中创建密钥，并连接您的 CRM 或网站。API 接受并返回 JSON。新房源会先创建为草稿；照片和发布有独立的端点。

创建 API 密钥 OpenAPI 3.1 JSON 下载 Python 客户端

基础 URL：https://doomio.cz/api/v1。仅可通过 HTTPS 从您的服务器在 Authorization: Bearer <key> 请求头中发送密钥。密钥独立于浏览器会话工作。请选择只读或读写访问权限；可在您的账户中撤销密钥。密钥只能访问您的个人房源或您当前中介机构的房源。离开中介机构、账户停用、到期或撤销都会使其失效。

1. 创建草稿

每个新房源都需要来自您的 CRM 的稳定 externalId，且在您的个人账户或中介机构内必须唯一。重复会返回 409；请获取现有房源并将其 PATCH。当房源被撤下时，ID 仍会保留。

curl https://doomio.cz/api/v1/properties \
  -H "Authorization: Bearer $DOOMIO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "externalId": "CRM-12345",
    "title": "Apartment in Valencia",
    "description": "A bright two-bedroom apartment near the park.",
    "sourceLocale": "en",
    "country": "es", "city": "Valencia",
    "address": "Valencia, Spain",
    "type": "apartment", "transactionType": "sale",
    "price": "245000.00", "currency": "EUR",
    "bedrooms": 2, "usableArea": 78.5
  }'

响应为 201 Created、{"data": {...}}，包含房源 ID、Location 头和 ETag。文本通过 sourceLocale 提供；现有的翻译工作流会准备网站的其他语言。

2. 上传照片并发布

curl https://doomio.cz/api/v1/properties/123/images \
  -H "Authorization: Bearer $DOOMIO_API_KEY" -F 'file=@living-room.jpg'

curl -X POST https://doomio.cz/api/v1/properties/123/publish \
  -H "Authorization: Bearer $DOOMIO_API_KEY"

支持上传 JPEG、PNG 或 WebP，每张图片最大 8 MiB、40 百万像素，最多 30 张图片。照片会经历与网页上传相同的审核。发布需要标题、地址、国家、房产类型、至少一张已批准的照片以及发布权限。中介机构房源遵循现有的中介可见性规则；个人房源需要在 Doomio 账户中购买有效的发布权限。促销优惠保留其现有限制和权利确认。API 密钥不会购买套餐或社交推广。

请检查响应中的 publiclyVisible、status 和 photoReviewError。已过期的房源或未通过照片审核的内容不会公开可见。DELETE 会将房源撤回为草稿；它会保留其 ID 和历史记录。删除最后一张照片也会撤回房源。

端点

方法和路径	行为
`GET /properties`	您的房源，包括草稿。可选 `limit`（1–100，默认 50）、`after`（ID 游标）、`externalId`、`status`（草稿/已发布）。
`POST /properties`	创建草稿。必填：`externalId`、标题、`sourceLocale`、国家、类型、`transactionType`、价格、货币。
`GET /properties/{id}`	单个房源及其 `ETag`。
`PATCH /properties/{id}`	更新提供的字段；未提供的字段保持不变。`externalId` 不可变。所有权、账单、社交推广和有效期不能通过此端点更改。
`DELETE /properties/{id}`	撤回房源；重复调用是安全的。
`POST /properties/{id}/publish`	验证并发布；适用现有发布规则。
`POST /properties/{id}/images`	Multipart 上传，字段 `file`。返回带有图片 ID 的房源。
`DELETE /properties/{id}/images/{imageId}`	删除该房源的一张图片。

字段和响应

可写字段：title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone。externalId 在创建时分配。未知字段会返回 422。有关精确范围和支持的国家/语言，请参见 OpenAPI。价格为十进制字符串，面积以平方米计，坐标为数值型 WGS84。货币值：CZK、EUR、USD、GBP、PLN。类型：apartment, house, land, commercial, other, development。交易：sale, rent。

列表返回 {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}。使用 ?after=123 继续；nextAfter: null 表示结束。您可以使用 ?externalId=CRM-12345 检索 CRM 房源。

curl -X PATCH https://doomio.cz/api/v1/properties/123 \
  -H "Authorization: Bearer $DOOMIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "ETAG-FROM-LAST-GET"' \
  --data '{"price":"239000.00"}'

在 PATCH、发布、撤回和图片操作中使用可选的 If-Match，可防止替换自上次 GET 以来已更改的房源。不匹配会返回 412；请重新获取房源并解决冲突。最大 JSON 请求体：128 KiB。限制：每个账户/中介机构及其所有密钥每分钟 120 个已认证请求；超出请求会返回 429 和 Retry-After: 60。请查看 X-RateLimit-Remaining。无需跨域浏览器访问：集成应放在您的服务器上。

错误使用 {"error":{"code":"validation_failed","message":"..."}}。状态码：400 请求格式错误，401 缺少/无效/已过期的密钥，403 只读密钥或缺少发布权限，404 房源/图片不在您的范围内或不存在，405 方法不允许，409 重复的 externalId，412 过期的 ETag，413 上传/请求体过大，415 Content-Type，422 字段无效/照片/发布校验失败，429 速率限制，500 临时服务器错误。每个响应都包含 X-Request-ID；报告错误时请提供它，不要提供您的密钥。

安装客户端

需要 Python 3.10 或更高版本，不依赖第三方包。下载客户端和 .env 密钥文件，将两者都保存在公共 Web 目录之外，然后运行：

chmod 600 doomio-api-key.env
python3 doomio_client.py --env doomio-api-key.env list
python3 doomio_client.py --env doomio-api-key.env sync listings.json
python3 doomio_client.py --env doomio-api-key.env upload 123 living-room.jpg
python3 doomio_client.py --env doomio-api-key.env publish 123
python3 doomio_client.py --env doomio-api-key.env withdraw 123

listings.json 是一个房源对象数组，格式与创建时相同。sync 会查找外部 ID，创建缺失的草稿并更新现有房源。它不会删除文件中缺失的房源，也不会自动上传照片或发布它们。上传/发布/撤回都是显式命令。这是一个通用的 JSON 集成客户端；现有 CRM 产品仍然需要各自的字段映射或连接器。