# API de flujo comercial para agentes

Todos los endpoints requieren `Authorization: Bearer <token>` y responden con el sobre estándar de la aplicación (`status`, `data`, `code`).

## Aislamiento por agente

Para usuarios con rol `REAL_ESTATE_AGENT`:

- los prospectos se crean siempre con `lead_agent_id` igual al usuario autenticado;
- no se acepta un `lead_agent_id` enviado por el cliente para suplantar a otro agente;
- los listados, detalles, actualizaciones y eliminaciones de prospectos se limitan al agente autenticado;
- los listados y detalles de citas se limitan a `appointments.lead_agent_id` del agente autenticado;
- acceder directamente al ID de un prospecto o cita de otro agente responde `404`.

Los administradores conservan su alcance global y la inmobiliaria conserva su alcance administrativo por fraccionamiento.

## 1. Registrar prospecto con datos básicos

`POST /api/v1/agent-flow/prospects`

```json
{
  "first_name": "Ana",
  "last_name": "López",
  "phone": "3121234567",
  "email": "ana@example.com",
  "source": "WhatsApp",
  "notes": "Solicitó información de lotes"
}
```

Son obligatorios `first_name` y `phone`. La respuesta incluye `profile_complete: false` y `next_action: schedule_appointment` cuando todavía no se han capturado los datos necesarios para apartar.

## 2. Agendar visita

`POST /api/v1/agent-flow/prospects/{prospecto}/appointments`

```json
{
  "development_id": 15,
  "appointment_date": "2026-07-25T11:30:00-06:00",
  "sale_closer_agent_id": 8,
  "notes": "Visita a la casa muestra"
}
```

El nombre, teléfono, correo y agente se toman del prospecto. El endpoint valida que el prospecto pertenezca al agente y que el fraccionamiento pertenezca a su inmobiliaria.

## 3A. Ver otra propiedad o fraccionamiento

`POST /api/v1/agent-flow/prospects/{prospecto}/interests`

```json
{
  "target_type": "development",
  "target_id": 18,
  "notes": "Prefiere una ubicación al norte"
}
```

`target_type` admite:

- `development`: fraccionamiento;
- `lot`: lote/propiedad dentro de un fraccionamiento;
- `property`: publicación de propiedad.

El interés se registra una sola vez por prospecto y destino; una llamada repetida actualiza las notas sin duplicarlo.

## Consultar estatus de citas

`GET /api/v1/appointment-statuses`

Devuelve los cuatro valores aceptados con su etiqueta de presentación: `scheduled`, `confirmed`, `completed` y `cancelled`.

## Consultar las citas de una fecha

`GET /api/v1/appointments?date=2026-07-25`

La fecha es obligatoria y usa el formato `YYYY-MM-DD`. Para un usuario con rol de agente, el resultado contiene exclusivamente citas cuya fecha corresponda al día solicitado y cuyo `lead_agent_id` sea el del usuario autenticado.

Opcionalmente se puede filtrar también por estatus:

`GET /api/v1/appointments?date=2026-07-25&status=confirmed`

La respuesta incluye la fecha consultada, zona horaria, total de resultados y el arreglo `appointments` ordenado por hora.

## Cambiar estatus de una cita

`PATCH /api/v1/appointment/{cita}/status`

```json
{
  "status": "completed"
}
```

También acepta equivalentes en español como `programada`, `confirmada`, `realizada` y `cancelada`. Un agente sólo puede modificar citas cuyo `lead_agent_id` corresponda a su usuario autenticado.

## 3B. Completar prospecto y apartar lote

`POST /api/v1/agent-flow/prospects/{prospecto}/reservations`

```json
{
  "development_id": 15,
  "lot_ids": [120],
  "reservation_amounts": {
    "120": 10000
  },
  "payment_method": "Transferencia",
  "payment_reference": "SPEI-12345",
  "notes": "Apartado durante visita",
  "prospect": {
    "first_name": "Ana",
    "last_name": "López Pérez",
    "phone": "3121234567",
    "email": "ana@example.com",
    "birth_day": "1990-05-10",
    "birth_place": "Colima",
    "marital_status": "Casada",
    "occupation": "Arquitecta",
    "beneficiary": "Luis Pérez",
    "ine_file": "https://archivos.example.com/ine.pdf",
    "address": {
      "street": "Av. Constitución 100",
      "neighborhood": "Centro",
      "zip_code": "28000",
      "country_id": 1,
      "state_id": 6,
      "city_id": 25
    }
  }
}
```

Son obligatorios para completar el perfil: nombre, apellidos, teléfono, correo y calle. El resto de los datos personales se acepta cuando esté disponible. La actualización del prospecto, el cambio de estado de todos los lotes y la creación de pagos se ejecutan en una transacción: si cualquier lote ya no está disponible, no se guarda ningún cambio parcial.

## Endpoints heredados protegidos

También se mantiene el aislamiento del agente en:

- `GET /api/v1/prospects`
- `GET /api/v1/prospect/{id}`
- `POST /api/v1/prospect/{id}/update`
- `DELETE /api/v1/prospect/{id}/delete`
- `GET /api/v1/development/{id}/appointments`
- `GET /api/v1/appointment/{id}`