開発者向けドキュメント · JSON REST API v1

不動産会社と個人のお客様向け: アカウントでキーを作成し、CRM または Web サイトを接続してください。API は JSON を受け取り、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 をアップロードできます。1 枚あたり最大 8 MiB、40 メガピクセル、最大 30 枚です。写真は Web アップロードと同じ審査を通ります。公開には、タイトル、住所、国、物件タイプ、少なくとも 1 枚の承認済み写真、そして公開権限が必要です。代理店の物件は既存の代理店可視性ルールに従います。個人の物件には、Doomio アカウントで購入済みの有効な公開権限が必要です。プロモーションオファーは、既存の上限と権利確認を維持します。API キーではプランやソーシャルプロモーションを購入できません。

レスポンス内の publiclyVisible、status、photoReviewError を確認してください。期限切れの物件や写真審査に失敗した写真は、公開されません。DELETE により物件は下書きに戻ります。ID と履歴は保持されます。最後の写真を削除すると、その物件も下書きに戻ります。

エンドポイント

メソッドとパス	動作
`GET /properties`	あなたの物件一覧。下書きも含みます。任意: `limit` (1〜100、既定 50)、`after` (ID カーソル)、`externalId`、`status` (draft/published)。
`POST /properties`	下書きを作成します。必須: `externalId`、title、`sourceLocale`、country、type、`transactionType`、price、currency。
`GET /properties/{id}`	1 件の物件とその `ETag`。
`PATCH /properties/{id}`	指定したフィールドを更新します。省略されたフィールドは変更されません。`externalId` は変更不可です。所有権、請求、ソーシャルプロモーション、有効性はこのエンドポイントでは変更できません。
`DELETE /properties/{id}`	物件を取り下げます。繰り返し呼び出しても安全です。
`POST /properties/{id}/publish`	検証して公開します。既存の公開ルールが適用されます。
`POST /properties/{id}/images`	Multipart アップロード、フィールド `file`。画像 ID を含む物件を返します。
`DELETE /properties/{id}/images/{imageId}`	この物件の画像の 1 つを削除します。

フィールドとレスポンス

書き込み可能なフィールド: 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"}'

If-Match は、PATCH、公開、取り下げ、画像操作で任意指定できます。これにより、前回の GET 以降に変更された物件を上書きしないようにできます。不一致の場合は 412 が返されます。物件を取得し、競合を解決してください。JSON リクエストの最大サイズは 128 KiB です。制限: 認証済みリクエストは、すべてのキーを合わせてアカウント/代理店ごとに 1 分あたり 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 を検索し、不足している下書きを作成し、既存の物件を更新します。ファイルにない物件を削除したり、写真を自動でアップロードしたり、公開したりはしません。upload/publish/withdraw は明示的なコマンドです。これは汎用の JSON 連携クライアントです。既存の CRM 製品には、引き続き独自のフィールドマッピングまたはコネクタが必要です。