Agencias

Una Agencia (oficina) es una inmobiliaria registrada en la plataforma. Cada agencia tiene un owner (el agency_admin que la creó) y puede contener múltiples agentes.

Organización: oficinas y admins

Un usuario agency_admin puede operar como organización multi-oficina:

• Owner / creador: quien crea la agencia con POST /api/agencies. Puede crear varias agencias y conserva el control total de todas ellas.
• Co-admins asignados: el owner puede asignar uno o más usuarios como admins de una agencia (POST /api/agencies/:id/admins). Un co-admin tiene las mismas funciones que el owner pero solo sobre esa oficina (gestionar sus agentes, editar la agencia). No puede ver otras oficinas del owner, crear nuevas agencias ni asignar otros admins.
• Agentes: se crean y se asignan a una oficina mediante agencyId (ver Agentes).

Capacidad	Owner	Co-admin asignado
Crear agencias	✅	❌
Gestionar su oficina (agentes, datos)	✅	✅
Ver/gestionar otras oficinas	✅ (las suyas)	❌
Asignar / quitar co-admins	✅	❌

Flujo de registro

1. POST /api/auth/register        →  Crear cuenta agency_admin (owner)
2. POST /api/agencies             →  Crear la agencia/oficina (1 o más)
3. POST /api/agents               →  Crear agentes y asignarlos (agencyId)
4. POST /api/agencies/:id/admins  →  Asignar co-admins por oficina (opcional)
5. 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"
}

---

Co-admins de una agencia

Permiten gestionar los admins adicionales de una oficina. Solo el owner (o un admin global) puede asignar/quitar admins.

Listar admins

GET /api/agencies/:id/admins
Authorization: Bearer {token}

Respuesta 200:

{
  "status": "success",
  "data": {
    "owner": { "id": "uuid-owner", "firstName": "Carlos", "lastName": "Mendoza", "email": "carlos@..." },
    "assignedAdmins": [
      { "id": "uuid-admin2", "firstName": "Ana", "lastName": "López", "email": "ana@..." }
    ]
  }
}

Asignar co-admin

El usuario se identifica por email o userId (al menos uno). Debe existir previamente. Si su rol no es agency_admin/admin, se promueve a agency_admin automáticamente (necesario para que pueda usar los endpoints de gestión).

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

Body:

{ "email": "ana@inmobiliariacentro.mx" }

Respuesta 200:

{
  "status": "success",
  "message": "Admin asignado correctamente",
  "data": { "agencyId": "uuid-agencia", "userId": "uuid-admin2", "email": "ana@...", "role": "agency_admin" }
}

Errores: 403 si no eres el owner · 404 si el usuario no existe · 400 si el usuario ya es el owner.

Quitar co-admin

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

No se puede quitar al owner de la agencia (400).

---

Mis agencias

Obtiene las agencias que el usuario autenticado puede gestionar: las propias (como owner) y aquellas donde fue asignado como co-admin.

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.