기본 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 megapixels, 최대 30 images입니다. 사진은 웹 업로드와 동일한 검토를 거칩니다. 게시하려면 제목, 주소, 국가, 부동산 유형, 승인된 사진 1장 이상, 그리고 게시 권한이 필요합니다. 중개업소 매물은 기존 중개업소 공개 규칙을 따르며, 개인 매물은 Doomio 계정에서 활성 게시 상품이 필요합니다. 프로모션 오퍼는 기존 한도와 권한 확인을 그대로 유지합니다. API 키로는 요금제나 소셜 프로모션을 구매할 수 없습니다.

응답에서 publiclyVisible, status, photoReviewError를 확인하세요. 만료된 매물이나 사진 검토 실패 항목은 공개적으로 보이지 않습니다. DELETE은 매물을 초안으로 철회하며, ID와 기록은 유지됩니다. 마지막 사진을 삭제해도 매물은 철회됩니다.

엔드포인트

필드 및 응답

수정 가능한 필드: 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, publish, withdraw, image 작업에서 선택적으로 사용되는 If-Match는 마지막 GET 이후 변경된 매물을 덮어쓰지 않도록 합니다. 불일치가 발생하면 412가 반환되며, 매물을 다시 조회해 충돌을 해결하세요. 최대 JSON 요청 크기: 128 KiB. 제한: 모든 키를 합산하여 계정/중개업소당 인증된 요청 120/minute; 초과 요청은 429와 Retry-After: 60를 반환합니다. X-RateLimit-Remaining를 확인하세요. 교차 출처 브라우저 접근은 필요하지 않습니다. 통합은 서버에서 수행해야 합니다.

오류는 {"error":{"code":"validation_failed","message":"..."}}를 사용합니다. 상태: 400 형식이 잘못된 요청, 401 누락/유효하지 않음/만료된 키, 403 읽기 전용 키 또는 게시 권한 없음, 404 범위 밖이거나 존재하지 않는 매물/이미지, 405 method, 409 중복 externalId, 412 오래된 ETag, 413 크기 초과 업로드/본문, 415 Content-Type, 422 유효하지 않은 필드/사진/게시 검증, 429 rate limit, 500 일시적인 서버 오류. 모든 응답에는 X-Request-ID가 포함됩니다. 오류를 신고할 때는 비밀 키가 아니라 이 값을 제공하세요.

클라이언트 설치

Python 3.10 이상이 필요하며, 서드파티 패키지는 필요하지 않습니다. 클라이언트와 .env 키 파일을 다운로드한 뒤, 둘 다 공개 웹 디렉터리 밖에 보관하고 다음을 실행하세요:

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 제품은 여전히 자체 필드 매핑 또는 커넥터가 필요합니다.