Agentes

Un Agente es un perfil inmobiliario vinculado a un usuario con rol agent. Puede pertenecer a una agencia o ser independiente.

Relación Usuario ↔ Agente

Cada agente tiene un User asociado que maneja la autenticación y los datos básicos (nombre, email, password). El modelo Agent contiene el perfil profesional (ciudad, categoría, bio, redes sociales).

Flujo de creación

agency_admin autenticado
      │
      └─ POST /api/agencies/current/agents
              Crea User (role: agent) + perfil Agent
              vinculados a la agencia del admin

---

Listar agentes (público)

GET /api/agents

Query params opcionales:

Parámetro	Tipo	Descripción
page	number	Página (default: 1)
limit	number	Resultados por página (default: 10)
city	string	Filtrar por ciudad
category	string	Filtrar por categoría (Residencial, Comercial, etc.)
search	string	Buscar por nombre o empresa

Respuesta 200:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "uuid-agente",
        "name": "Laura García",
        "email": "laura@inmobiliaria.mx",
        "phone": "+52 55 9876 5432",
        "image": "https://cdn.havi.app/images/laura.jpg",
        "city": "Ciudad de México",
        "company": "Inmobiliaria Centro MX",
        "category": "Residencial",
        "rating": 4.8,
        "propertiesCount": 12,
        "isActive": true,
        "userId": "uuid-usuario",
        "type": "agent_record"
      }
    ],
    "agencies": [ ... ],
    "pagination": {
      "total": 80,
      "perPage": 10,
      "currentPage": 1,
      "lastPage": 8
    }
  }
}

---

Detalle de agente

GET /api/agents/:id

Query params opcionales:

Parámetro	Tipo	Descripción
page	number	Página de propiedades (default: 1)
limit	number	Propiedades por página (default: 10)
type	string	sale o rent

Respuesta 200:

{
  "success": true,
  "data": {
    "agent": {
      "id": "uuid-agente",
      "city": "Ciudad de México",
      "category": "Residencial",
      "company": "Inmobiliaria Centro MX",
      "bio": "Especialista con 8 años de experiencia...",
      "rating": 4.8,
      "reviewsCount": 24,
      "website": "https://laurainmobiliaria.com",
      "socialMedia": { "instagram": "https://instagram.com/laurainmobiliaria" },
      "isActive": true,
      "user": {
        "firstName": "Laura",
        "lastName": "García",
        "email": "laura@inmobiliaria.mx",
        "phone": "+52 55 9876 5432",
        "image": "https://cdn.havi.app/images/laura.jpg"
      },
      "agency": {
        "id": "uuid-agencia",
        "name": "Inmobiliaria Centro MX",
        "logo": "https://cdn.havi.app/logos/logo.png"
      }
    },
    "properties": { ... },
    "propertiesCount": {
      "total": 12,
      "forSale": 8,
      "forRent": 4
    },
    "reviews": [ ... ]
  }
}

---

Crear agente en mi agencia

Requiere autenticación

Solo el agency_admin puede crear agentes. El agente se vincula automáticamente a la agencia del admin autenticado.

POST /api/agencies/current/agents
Authorization: Bearer {token}
Content-Type: application/json

Body:

{
  "firstName": "Laura",
  "lastName": "García",
  "email": "laura@inmobiliaria.mx",
  "password": "AgentPass456!",
  "phone": "+52 55 9876 5432",

  "city": "Ciudad de México",
  "category": "Residencial",
  "company": "Inmobiliaria Centro MX",
  "bio": "Especialista en propiedades residenciales con 8 años de experiencia.",
  "phone1": "+52 55 9876 5432",
  "officePhone": "+52 55 1111 2222",
  "website": "https://laurainmobiliaria.com",
  "memberSince": "2018-01-15",
  "socialMedia": {
    "instagram": "https://instagram.com/laurainmobiliaria",
    "linkedin": "https://linkedin.com/in/lauragarcia"
  }
}

Campos requeridos: firstName, lastName, email, password

Respuesta 201:

{
  "status": "success",
  "message": "Agent created successfully",
  "data": {
    "id": "uuid-agente",
    "userId": "uuid-usuario-creado",
    "agencyId": "uuid-agencia",
    "city": "Ciudad de México",
    "category": "Residencial",
    "isActive": true,
    "user": {
      "id": "uuid-usuario-creado",
      "firstName": "Laura",
      "lastName": "García",
      "email": "laura@inmobiliaria.mx",
      "role": "agent"
    },
    "agency": {
      "id": "uuid-agencia",
      "name": "Inmobiliaria Centro MX"
    }
  }
}

INFO

Si el email ya está registrado, obtendrás un error 400 con código EMAIL_ALREADY_EXISTS.

---

Listar agentes de mi agencia

GET /api/agencies/current/agents
Authorization: Bearer {token del agency_admin}

Incluye propertiesCount por agente.

---

Actualizar agente

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

Body (todos los campos son opcionales):

{
  "firstName": "Laura",
  "lastName": "García Soto",
  "phone": "+52 55 0000 1111",
  "city": "Guadalajara",
  "category": "Comercial",
  "bio": "Nueva bio actualizada.",
  "isActive": true
}

---

Eliminar agente

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

WARNING

Al eliminar un agente, sus propiedades asignadas quedan sin agente (agent_id = null) pero no son eliminadas.

---

Agencia de mi perfil (para agentes)

GET /api/agent/my-agency
Authorization: Bearer {token del agente}

Devuelve la agencia a la que pertenece el agente autenticado.

Respuesta 200:

{
  "status": "success",
  "data": {
    "id": "uuid-agencia",
    "name": "Inmobiliaria Centro MX",
    "logo": "https://cdn.havi.app/logos/logo.png",
    "city": "Ciudad de México"
  }
}

---

Campos del perfil de agente

Campo	Tipo	Descripción
image	string	URL de foto de perfil
city	string	Ciudad de operación
category	string	Especialización (Residencial, Comercial, Industrial, etc.)
company	string	Nombre de empresa o agencia
bio	string	Descripción profesional
phone1	string	Teléfono principal
phone2	string	Teléfono secundario
officePhone	string	Teléfono de oficina
mobilePhone	string	Celular
fax	string	Fax
website	string	Sitio web personal
memberSince	date	Fecha de inicio en la industria
brokerAddress	string	Dirección de la oficina
socialMedia	object	Redes sociales {facebook, instagram, linkedin, twitter}
rating	number	Calificación promedio (0-5)
reviewsCount	number	Número de reseñas
isActive	boolean	Si el agente está activo en la plataforma