Documentación para desarrolladores · JSON REST API v1

Para agencias inmobiliarias y clientes particulares: cree una clave en su cuenta y conecte su CRM o sitio web. La API acepta y devuelve JSON. Los nuevos anuncios se crean como borradores; las fotos y la publicación tienen endpoints separados.

Crear una clave API OpenAPI 3.1 JSON Descargar el cliente de Python

URL base: https://doomio.cz/api/v1. Envíe su clave solo desde su servidor por HTTPS, en el encabezado Authorization: Bearer <key>. Las claves funcionan de forma independiente de las sesiones del navegador. Seleccione acceso de solo lectura o de lectura/escritura; revoque las claves en su cuenta. Una clave solo puede acceder a sus propios anuncios o a los anuncios de su agencia actual. Dejar la agencia, la desactivación de la cuenta, el vencimiento o la revocación la deshabilita.

1. Crear un borrador

Cada nuevo anuncio necesita un externalId estable de su CRM, único dentro de su cuenta personal o agencia. Un duplicado devuelve 409; recupere el anuncio existente y PATCH. Los identificadores permanecen reservados cuando un anuncio se retira.

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 respuesta es 201 Created, {"data": {...}}, con el ID del anuncio, un encabezado Location y un ETag. El texto se proporciona en sourceLocale; el flujo de traducción existente prepara los demás idiomas del sitio web.

2. Cargar fotos y publicar

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"

Cargue JPEG, PNG o WebP, máximo 8 MiB y 40 megapíxeles por imagen, máximo 30 imágenes. Las fotos pasan por la misma revisión que las cargas web. Para publicar se requiere título, dirección, país, tipo de propiedad, al menos una foto aprobada y un derecho de publicación. Los anuncios de agencia siguen las reglas de visibilidad de la agencia existentes; los anuncios personales necesitan una publicación activa comprada en la cuenta de Doomio. Las ofertas promocionales conservan sus límites y la confirmación de derechos existentes. Las claves API no compran planes ni promoción social.

Compruebe publiclyVisible, status y photoReviewError en la respuesta. Un anuncio caducado o una revisión de foto fallida no es visible públicamente. DELETE retira un anuncio a borrador; conserva su ID y su historial. Quitar la última foto también retira el anuncio.

Endpoints

Método y ruta	Comportamiento
`GET /properties`	Sus anuncios, incluidos los borradores. Opcional `limit` (1–100, valor predeterminado 50), `after` (cursor de ID), `externalId`, `status` (borrador/publicado).
`POST /properties`	Crear un borrador. Obligatorio: `externalId`, título, `sourceLocale`, país, tipo, `transactionType`, precio, divisa.
`GET /properties/{id}`	Un anuncio y sus `ETag`.
`PATCH /properties/{id}`	Actualiza los campos proporcionados; los campos omitidos permanecen sin cambios. `externalId` es inmutable. La propiedad, la facturación, la promoción social y la validez no pueden cambiarse a través de este endpoint.
`DELETE /properties/{id}`	Retira el anuncio; las llamadas repetidas son seguras.
`POST /properties/{id}/publish`	Valida y publica; se aplican las reglas de publicación existentes.
`POST /properties/{id}/images`	Carga multipart, campo `file`. Devuelve el anuncio con el ID de la imagen.
`DELETE /properties/{id}/images/{imageId}`	Elimina una de las imágenes de este anuncio.

Campos y respuestas

Campos editables: title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone. externalId se asigna al crear. Los campos desconocidos devuelven 422. Consulte OpenAPI para conocer los límites exactos y los países/idiomas compatibles. Los precios son cadenas decimales, las superficies son metros cuadrados, las coordenadas son WGS84 numéricos. Valores de divisa: CZK, EUR, USD, GBP, PLN. Tipos: apartment, house, land, commercial, other, development. Transacciones: sale, rent.

Las listas devuelven {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}. Repita con ?after=123; nextAfter: null significa el final. Puede recuperar un anuncio de 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"}'

If-Match opcional en PATCH, publicar, retirar y operaciones de imagen impide reemplazar un anuncio modificado desde su último GET. Una discrepancia devuelve 412; recupere el anuncio y resuelva el conflicto. Solicitud JSON máxima: 128 KiB. Límite: 120 solicitudes autenticadas por minuto por cuenta/agencia entre todas sus claves; las solicitudes en exceso devuelven 429 y Retry-After: 60. Inspeccione X-RateLimit-Remaining. No se requiere acceso de navegador entre orígenes: las integraciones deben estar en su servidor.

Los errores usan {"error":{"code":"validation_failed","message":"..."}}. Estados: 400 solicitud malformada, 401 clave ausente/ inválida/ caducada, 403 clave de solo lectura o falta de derecho de publicación, 404 anuncio/imagen fuera de su ámbito o ausente, 405 método, 409 externalId duplicado, 412 ETag obsoleto, 413 carga/cuerpo demasiado grande, 415 Content-Type, 422 campos no válidos/validación de foto/publicación, 429 límite de frecuencia, 500 error temporal del servidor. Cada respuesta incluye un X-Request-ID; proporciónelo al informar de un error, nunca su clave secreta.

Instalar el cliente

Requiere Python 3.10 o superior, sin paquetes de terceros. Descargue el cliente y el archivo de clave .env, guarde ambos fuera de un directorio web público y luego ejecute:

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 es un array de objetos de anuncio en el formato de creación. sync busca IDs externos, crea borradores faltantes y actualiza los anuncios existentes. No elimina anuncios ausentes del archivo, no carga fotos automáticamente ni los publica. upload/publish/withdraw son comandos explícitos. Este es un cliente genérico de integración JSON; los productos CRM existentes siguen necesitando su propio mapeo de campos o conector.