Propiedades

Las propiedades son el núcleo de la plataforma. Pueden ser publicadas por agency_admin, agent, broker o developer, y asignadas a un agente específico.

Estados de una propiedad

Estado (propertyStatus)	Descripción
draft	Borrador, no visible públicamente
published	Publicada y visible
sold	Vendida / arrendada
inactive	Desactivada temporalmente

Estado (listingStatus)	Descripción
active	Disponible para compradores/arrendatarios
inactive	No disponible actualmente
rented	Arrendada

---

Listar propiedades (público)

Solo devuelve propiedades con propertyStatus = published y listingStatus = active.

GET /api/properties

Query params opcionales:

Parámetro	Tipo	Descripción
page	number	Página (default: 1)
limit	number	Resultados por página (default: 10)
listing_type	string	sale o rent
category	string	Casa, Departamento, Terreno, Oficina, etc.
city	string	Filtrar por ciudad
min_price	number	Precio mínimo
max_price	number	Precio máximo
bedrooms	number	Número de recámaras
bathrooms	number	Número de baños
featured	boolean	Solo propiedades destacadas
agent_id	uuid	Propiedades de un agente específico
agency_id	uuid	Propiedades de una agencia específica

Respuesta 200:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "uuid-propiedad",
        "title": "Departamento en Polanco",
        "price": 4500000,
        "currency": "MXN",
        "listingType": "sale",
        "categories": ["Departamento"],
        "bedrooms": 3,
        "bathrooms": 2,
        "constructionArea": 120,
        "city": "Ciudad de México",
        "state": "CDMX",
        "address": "Calle Masaryk 45, Polanco",
        "propertyStatus": "published",
        "listingStatus": "active",
        "isFeatured": false,
        "viewsCount": 148,
        "agentId": "uuid-agente",
        "agencyId": "uuid-agencia",
        "user": { "firstName": "Carlos", "lastName": "Mendoza" },
        "agent": { "company": "Inmobiliaria Centro MX" },
        "assets": [
          {
            "id": "uuid-asset",
            "url": "https://cdn.havi.app/properties/foto1.jpg",
            "type": "image",
            "sortOrder": 1
          }
        ],
        "createdAt": "2026-05-13T10:00:00.000Z"
      }
    ],
    "meta": {
      "total": 250,
      "perPage": 10,
      "currentPage": 1,
      "lastPage": 25
    }
  }
}

---

Buscar propiedades

GET /api/properties/search

Acepta los mismos parámetros que el listado.

---

Detalle de propiedad

GET /api/properties/:id

Incrementa el contador de vistas (viewsCount) en cada llamada.

---

Propiedades similares

GET /api/properties/:id/similar

Devuelve hasta 6 propiedades similares en la misma ciudad y categoría.

---

Crear propiedad

Requiere autenticación

agency_admin, agent, broker o developer.

POST /api/properties
Authorization: Bearer {token}
Content-Type: application/json

Body:

{
  "title": "Departamento en Polanco",
  "description": "Hermoso departamento de 3 recámaras con vista a Masaryk. Acabados de lujo, cocina integral, 2 cajones de estacionamiento.",
  "price": 4500000,
  "currency": "MXN",
  "listingType": "sale",
  "categories": ["Departamento"],
  "bedrooms": 3,
  "bathrooms": 2,
  "halfBaths": 1,
  "parkingSpaces": 2,
  "constructionArea": 120,
  "landArea": 0,
  "yearBuilt": 2021,
  "floors": 1,
  "city": "Ciudad de México",
  "state": "CDMX",
  "zipCode": "11560",
  "address": "Calle Masaryk 45, Polanco",
  "latitude": 19.4313,
  "longitude": -99.1893,
  "amenities": ["gimnasio", "rooftop", "seguridad_24h", "pet_friendly"],
  "agentId": "uuid-del-agente",
  "propertyStatus": "draft",
  "listingStatus": "inactive",
  "isFeatured": false
}

Comportamiento al asignar agente:

• Si incluyes agentId, la propiedad queda asignada a ese agente y a su agencia automáticamente.
• Si el usuario autenticado tiene rol agent y no especificas agentId, se asigna a sí mismo.

Respuesta 201:

{
  "success": true,
  "data": {
    "id": "uuid-propiedad",
    "title": "Departamento en Polanco",
    "propertyStatus": "draft",
    "listingStatus": "inactive",
    "agentId": "uuid-agente",
    "agencyId": "uuid-agencia",
    "userId": "uuid-usuario"
  }
}

---

Subir imágenes (URL pre-firmada S3)

El proceso de subida de imágenes se hace en dos pasos: obtener URLs pre-firmadas y subir directamente a S3.

Paso 1 — Solicitar URLs pre-firmadas:

POST /api/upload/presigned
Authorization: Bearer {token}
Content-Type: application/json

{
  "files": [
    { "filename": "fachada.jpg", "contentType": "image/jpeg" },
    { "filename": "sala.jpg",    "contentType": "image/jpeg" },
    { "filename": "recamara.jpg","contentType": "image/jpeg" }
  ],
  "propertyId": "uuid-propiedad"
}

Respuesta:

{
  "success": true,
  "data": [
    {
      "filename": "fachada.jpg",
      "uploadUrl": "https://s3.amazonaws.com/bucket/...",
      "publicUrl": "https://cdn.havi.app/properties/fachada.jpg"
    }
  ]
}

Paso 2 — Subir cada archivo directamente a S3:

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'image/jpeg' },
  body: fileBlob
})

---

Publicar propiedad

Cambia el estado de borrador a publicado:

PUT /api/properties/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "propertyStatus": "published",
  "listingStatus": "active"
}

---

Actualizar propiedad

PUT /api/properties/:id
Authorization: Bearer {token}
Content-Type: application/json

Acepta los mismos campos que la creación. Todos son opcionales.

---

Asignar agente a propiedad

PUT /api/properties/:id/assign-agent
Authorization: Bearer {token}
Content-Type: application/json

{
  "agentId": "uuid-del-agente"
}

Respuesta 200:

{
  "success": true,
  "message": "Agent assigned successfully",
  "data": {
    "id": "uuid-propiedad",
    "agentId": "uuid-agente",
    "agencyId": "uuid-agencia"
  }
}

---

Eliminar propiedad

DELETE /api/properties/:id
Authorization: Bearer {token}

---

Mis propiedades

GET /api/my-properties
Authorization: Bearer {token}

Incluye propiedades en todos los estados (drafts, publicadas, inactivas).

---

Campos de propiedad

Campo	Tipo	Requerido	Descripción
title	string	Sí	Título de la propiedad
description	string	No	Descripción detallada
price	number	Sí	Precio
currency	string	No	MXN (default), USD, COP, PEN, CLP
listingType	string	Sí	sale o rent
categories	array	Sí	["Casa", "Departamento", "Terreno", "Oficina", ...]
bedrooms	number	No	Número de recámaras
bathrooms	number	No	Baños completos
halfBaths	number	No	Medios baños
parkingSpaces	number	No	Cajones de estacionamiento
constructionArea	number	No	Área construida en m²
landArea	number	No	Área de terreno en m²
yearBuilt	number	No	Año de construcción
floors	number	No	Número de pisos
city	string	No	Ciudad
state	string	No	Estado/Departamento/Provincia
zipCode	string	No	Código postal
address	string	No	Dirección completa
latitude	number	No	Latitud para mapa
longitude	number	No	Longitud para mapa
amenities	array	No	Lista de amenidades
agentId	uuid	No	Asignar a un agente
propertyStatus	string	No	draft, published, sold, inactive
listingStatus	string	No	active, inactive, rented
isFeatured	boolean	No	Marcar como propiedad destacada