URL base: https://doomio.cz/api/v1. Invia la tua chiave solo dal tuo server tramite HTTPS, nell'intestazione Authorization: Bearer <key>. Le chiavi funzionano indipendentemente dalle sessioni del browser. Seleziona l'accesso in sola lettura o lettura/scrittura; revoca le chiavi nel tuo account. Una chiave può accedere solo ai tuoi annunci personali o agli annunci della tua agenzia corrente. Lasciare l'agenzia, la disattivazione dell'account, la scadenza o la revoca la disabilitano.

1. Crea una bozza

Ogni nuovo annuncio necessita di un externalId stabile dal tuo CRM, univoco all'interno del tuo account personale o della tua agenzia. Un duplicato restituisce 409; recupera l'annuncio esistente e PATCH. Gli ID restano riservati quando un annuncio viene ritirato.

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

La risposta è 201 Created, {"data": {...}}, con l'ID dell'annuncio, un'intestazione Location e un ETag. Il testo viene fornito in sourceLocale; il flusso di traduzione esistente prepara le altre lingue del sito web.

2. Carica le foto e pubblica

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"

Carica JPEG, PNG o WebP, massimo 8 MiB e 40 megapixel per immagine, massimo 30 immagini. Le foto seguono la stessa revisione dei caricamenti web. La pubblicazione richiede titolo, indirizzo, paese, tipo di immobile, almeno una foto approvata e un diritto di pubblicazione. Gli annunci dell'agenzia seguono le regole di visibilità dell'agenzia esistenti; gli annunci personali richiedono una pubblicazione attiva acquistata nell'account Doomio. Le offerte promozionali mantengono i loro limiti e la conferma dei diritti esistenti. Le chiavi API non acquistano piani né promozione sui social.

Controlla publiclyVisible, status e photoReviewError nella risposta. Un annuncio scaduto o una revisione foto non superata non è visibile pubblicamente. DELETE ritira un annuncio in una bozza; ne conserva l'ID e la cronologia. Rimuovere l'ultima foto ritira anche l'annuncio.

Endpoint

Campi e risposte

Campi scrivibili: title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone. externalId viene assegnato alla creazione. I campi sconosciuti restituiscono 422. Vedi OpenAPI per i limiti esatti e i paesi/lingue supportati. I prezzi sono stringhe decimali, le aree sono metri quadrati, le coordinate sono numeriche WGS84. Valori di valuta: CZK, EUR, USD, GBP, PLN. Tipi: apartment, house, land, commercial, other, development. Transazioni: sale, rent.

Gli elenchi restituiscono {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}. Ripeti con ?after=123; nextAfter: null indica la fine. Puoi recuperare un annuncio CRM con ?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"}'

L'If-Match facoltativo su PATCH, publish, withdraw e operazioni sulle immagini impedisce di sostituire un annuncio modificato dall'ultima tua GET. Una mancata corrispondenza restituisce 412; recupera l'annuncio e risolvi il conflitto. Richiesta JSON massima: 128 KiB. Limite: 120 richieste autenticate al minuto per account/agenzia su tutte le sue chiavi; le richieste in eccesso restituiscono 429 e Retry-After: 60. Ispeziona X-RateLimit-Remaining. Non è richiesto l'accesso browser cross-origin: le integrazioni devono risiedere sul tuo server.

Gli errori usano {"error":{"code":"validation_failed","message":"..."}}. Stati: 400 richiesta malformata, 401 chiave mancante/valida/scaduta, 403 chiave in sola lettura o diritto di pubblicazione mancante, 404 annuncio/immagine fuori dal tuo ambito o assente, 405 metodo, 409 duplicato externalId, 412 ETag obsoleto, 413 caricamento/corpo troppo grandi, 415 Content-Type, 422 campi non validi/immagine/pubblicazione non valida, 429 limite di frequenza, 500 errore temporaneo del server. Ogni risposta include un X-Request-ID; forniscilo quando segnali un errore, mai la tua chiave segreta.

Installa il client

Richiede Python 3.10 o più recente, senza pacchetti di terze parti. Scarica il client e il file chiave .env, conserva entrambi al di fuori di una directory web pubblica, quindi esegui:

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 è un array di oggetti annuncio nel formato di creazione. sync cerca gli ID esterni, crea bozze mancanti e aggiorna gli annunci esistenti. Non elimina gli annunci assenti dal file, non carica automaticamente le foto e non li pubblica. upload/publish/withdraw sono comandi espliciti. Questo è un client di integrazione JSON generico; i prodotti CRM esistenti hanno comunque bisogno della propria mappatura dei campi o connettore.