Agencias

Una Agencia es una inmobiliaria registrada en la plataforma. Cada agencia tiene un usuario administrador (agency_admin) y puede contener múltiples agentes.

Flujo de registro

1. POST /api/auth/register  →  Crear cuenta agency_admin
2. POST /api/agencies        →  Crear la agencia
3. POST /api/agencies/:id/logo  →  Subir logo (opcional)

---

Listar agencias

GET /api/agencies

Query params opcionales:

Parámetro	Tipo	Descripción
page	number	Página (default: 1)
limit	number	Resultados por página (default: 10)
search	string	Buscar por nombre
city	string	Filtrar por ciudad

Respuesta 200:

{
  "status": "success",
  "data": {
    "data": [
      {
        "id": "uuid-agencia",
        "name": "Inmobiliaria Centro MX",
        "logo": "https://cdn.havi.app/uploads/logo.png",
        "email": "contacto@inmobiliariacentro.mx",
        "phone": "+52 55 1234 5678",
        "city": "Ciudad de México",
        "state": "CDMX",
        "isActive": true,
        "admin": {
          "id": "uuid-admin",
          "firstName": "Carlos",
          "lastName": "Mendoza"
        },
        "agents": [ ... ]
      }
    ],
    "meta": {
      "total": 45,
      "perPage": 10,
      "currentPage": 1,
      "lastPage": 5
    }
  }
}

---

Obtener agencia por ID

GET /api/agencies/:id

Respuesta 200:

{
  "status": "success",
  "data": {
    "id": "uuid-agencia",
    "name": "Inmobiliaria Centro MX",
    "logo": "https://cdn.havi.app/uploads/logo.png",
    "description": "Especialistas en bienes raíces.",
    "email": "contacto@inmobiliariacentro.mx",
    "phone": "+52 55 1234 5678",
    "website": "https://inmobiliariacentro.mx",
    "address": "Av. Insurgentes Sur 123",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "06600",
    "socialMedia": {
      "facebook": "https://facebook.com/inmobiliariacentro",
      "instagram": "https://instagram.com/inmobiliariacentro"
    },
    "isActive": true,
    "admin": { ... },
    "agents": [ ... ],
    "createdAt": "2026-05-13T10:00:00.000Z"
  }
}

---

Crear agencia

Requiere autenticación

Authorization: Bearer {token} — el usuario debe tener rol agency_admin o admin.

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

Body:

{
  "name": "Inmobiliaria Centro MX",
  "email": "contacto@inmobiliariacentro.mx",
  "phone": "+52 55 1234 5678",
  "website": "https://inmobiliariacentro.mx",
  "address": "Av. Insurgentes Sur 123",
  "city": "Ciudad de México",
  "state": "CDMX",
  "zipCode": "06600",
  "description": "Especialistas en bienes raíces comerciales y residenciales.",
  "socialMedia": {
    "facebook": "https://facebook.com/inmobiliariacentro",
    "instagram": "https://instagram.com/inmobiliariacentro",
    "linkedin": "https://linkedin.com/company/inmobiliariacentro"
  }
}

Campos requeridos: name

Respuesta 201:

{
  "status": "success",
  "message": "Agency created successfully",
  "data": {
    "id": "uuid-agencia",
    "name": "Inmobiliaria Centro MX",
    "adminUserId": "uuid-admin",
    "isActive": true,
    "createdAt": "2026-05-13T10:00:00.000Z"
  }
}

---

Actualizar agencia

Requiere autenticación

Solo el administrador de la agencia puede actualizar.

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

Body (todos los campos son opcionales):

{
  "name": "Inmobiliaria Centro MX — Actualizado",
  "phone": "+52 55 9999 0000",
  "description": "Nueva descripción de la agencia."
}

---

Subir logo

POST /api/agencies/:id/logo
Authorization: Bearer {token}
Content-Type: multipart/form-data

Form data:

• logo — Archivo de imagen (.jpg, .jpeg, .png, .webp, máx. 5 MB)

Respuesta 200:

{
  "status": "success",
  "message": "Logo uploaded successfully",
  "data": {
    "id": "uuid-agencia",
    "logo": "https://api.havi.app/uploads/cuid-logo.png"
  }
}

---

Eliminar agencia

DANGER

Solo el administrador de la agencia puede eliminarla.

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

Respuesta 200:

{
  "status": "success",
  "message": "Agency deleted successfully"
}

---

Mis agencias

Obtiene las agencias del usuario autenticado.

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

---

Agentes de una agencia (público)

GET /api/agencies/by-admin/:userId/agents

Devuelve la agencia y sus agentes activos a partir del ID del usuario administrador. Útil para páginas públicas de perfil.