Adres bazowy: https://doomio.cz/api/v1. Wysyłaj swój klucz wyłącznie z serwera przez HTTPS, w nagłówku Authorization: Bearer <key>. Klucze działają niezależnie od sesji przeglądarki. Wybierz dostęp tylko do odczytu albo do odczytu i zapisu; klucze można unieważnić na koncie. Klucz może uzyskiwać dostęp tylko do Twoich własnych ofert lub ofert Twojej bieżącej agencji. Odejście z agencji, dezaktywacja konta, wygaśnięcie lub unieważnienie wyłączają go.

1. Utwórz wersję roboczą

Każda nowa oferta wymaga stałego externalId z Twojego CRM, unikalnego w obrębie Twojego konta osobistego lub agencji. Duplikat zwraca 409; pobierz istniejącą ofertę i PATCH ją. Identyfikatory pozostają zarezerwowane, gdy oferta zostanie wycofana.

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
  }'

Odpowiedź jest w 201 Created, {"data": {...}}, wraz z identyfikatorem oferty, nagłówkiem Location i ETag. Treść podawana jest w sourceLocale; istniejący proces tłumaczenia przygotowuje pozostałe języki witryny.

2. Prześlij zdjęcia i opublikuj

curl https://doomio.cz/api/v1/properties/123/images \
  -H "Authorization: Bearer $DOOMIO_API_KEY" -F '[email protected]'

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

Przesyłaj JPEG, PNG lub WebP, maksymalnie 8 MiB i 40 megapikseli na obraz, maksymalnie 30 obrazów. Zdjęcia przechodzą tę samą weryfikację co przesyłane przez witrynę. Publikacja wymaga tytułu, adresu, kraju, typu nieruchomości, co najmniej jednego zatwierdzonego zdjęcia oraz uprawnienia do publikacji. Oferty agencji podlegają istniejącym zasadom widoczności agencji; oferty prywatne wymagają aktywnej publikacji zakupionej na koncie Doomio. Oferty promocyjne zachowują swoje istniejące limity i potwierdzenie uprawnień. Klucze API nie kupują planów ani promocji społecznościowych.

Sprawdź publiclyVisible, status i photoReviewError w odpowiedzi. Wygasła oferta albo nieudana weryfikacja zdjęcia nie są publicznie widoczne. DELETE wycofuje ofertę do wersji roboczej; zachowuje jej identyfikator i historię. Usunięcie ostatniego zdjęcia również wycofuje ofertę.

Endpointy

Pola i odpowiedzi

Pola zapisywalne: title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone. externalId jest przypisywany przy tworzeniu. Nieznane pola zwracają 422. Zobacz OpenAPI, aby poznać dokładne granice i obsługiwane kraje/języki. Ceny są ciągami dziesiętnymi, powierzchnie są w metrach kwadratowych, współrzędne są numerycznym WGS84. Wartości walut: CZK, EUR, USD, GBP, PLN. Typy: apartment, house, land, commercial, other, development. Transakcje: sale, rent.

Listy zwracają {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}. Powtarzaj z ?after=123; nextAfter: null oznacza koniec. Możesz pobrać ofertę z CRM za pomocą ?externalId=CRM-12345.

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"}'

Opcjonalny If-Match w PATCH, publish, withdraw i operacjach na obrazach zapobiega zastąpieniu oferty zmienionej od czasu Twojego ostatniego GET. Niedopasowanie zwraca 412; pobierz ofertę i rozwiąż konflikt. Maksymalny rozmiar żądania JSON: 128 KiB. Limit: 120 uwierzytelnionych żądań na minutę na konto/agencję łącznie dla wszystkich jej kluczy; nadmiarowe żądania zwracają 429 i Retry-After: 60. Sprawdzaj X-RateLimit-Remaining. Dostęp przeglądarkowy między originami nie jest wymagany: integracje powinny działać na Twoim serwerze.

Błędy używają {"error":{"code":"validation_failed","message":"..."}}. Statusy: 400 malformed request, 401 missing/invalid/expired key, 403 read-only key or publication entitlement missing, 404 listing/image outside your scope or absent, 405 method, 409 duplicate externalId, 412 stale ETag, 413 oversized upload/body, 415 Content-Type, 422 invalid fields/photo/publishing validation, 429 rate limit, 500 temporary server error. Każda odpowiedź zawiera X-Request-ID; podaj go, zgłaszając błąd, nigdy nie podawaj swojego tajnego klucza.

Zainstaluj klienta

Wymaga Python 3.10 lub nowszego, bez pakietów firm trzecich. Pobierz klienta i plik klucza .env, przechowuj oba poza publicznym katalogiem WWW, a następnie uruchom:

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 jest tablicą obiektów ofert w formacie tworzenia. sync wyszukuje zewnętrzne identyfikatory, tworzy brakujące wersje robocze i aktualizuje istniejące oferty. Nie usuwa ofert nieobecnych w pliku, nie przesyła zdjęć automatycznie ani ich nie publikuje. upload/publish/withdraw to jawne polecenia. To ogólny klient integracji JSON; istniejące produkty CRM nadal potrzebują własnego mapowania pól lub konektora.