Clientes — Endpoints

Base URL: /api/clients

Permissões: Admin, Broker

---

GET /api/clients

Lista clientes da empresa com paginação.

Query params:

Parâmetro	Tipo	Descrição
page	integer	Página (padrão: 1)
pageSize	integer	Itens por página (padrão: 20)
search	string	Busca por nome, e-mail, CPF/CNPJ
type	string	Filtro: Individual, Company
interest	string	Filtro: Lease, Purchase, Investment

Resposta 200:

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "João da Silva",
      "taxId": "123.456.789-00",
      "type": "Individual",
      "email": "joao@email.com",
      "phone": "(11) 99999-0001",
      "interest": "Lease",
      "source": "Indication",
      "createdAt": "2026-05-01T09:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 87,
  "totalPages": 5,
  "hasNext": true,
  "hasPrevious": false
}

---

GET /api/clients/:id

Retorna detalhes de um cliente, incluindo preferências e histórico.

Resposta 200:

{
  "id": "a1b2c3d4-...",
  "name": "João da Silva",
  "taxId": "123.456.789-00",
  "type": "Individual",
  "email": "joao@email.com",
  "phone": "(11) 99999-0001",
  "interest": "Lease",
  "source": "Indication",
  "preferences": {
    "desiredType": "Apartment",
    "minPrice": 2000.00,
    "maxPrice": 4000.00,
    "minBedrooms": 2,
    "neighborhood": "Centro"
  },
  "address": {
    "street": "Rua Exemplo",
    "number": "10",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01001-000"
  },
  "notes": "Prefere andar alto, aceita condomínio até R$ 500.",
  "createdAt": "2026-05-01T09:00:00Z",
  "updatedAt": "2026-05-10T11:00:00Z"
}

---

POST /api/clients

Cadastra um novo cliente / lead.

Body:

{
  "name": "Maria Oliveira",
  "taxId": "987.654.321-00",
  "type": "Individual",
  "email": "maria@email.com",
  "phone": "(11) 98888-0002",
  "interest": "Purchase",
  "source": "Portal",
  "preferences": {
    "desiredType": "House",
    "minPrice": 300000.00,
    "maxPrice": 600000.00
  },
  "address": {
    "street": "Rua das Acácias",
    "number": "5",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "04001-000"
  },
  "notes": "Quer garagem coberta."
}

Campo	Tipo	Obrigatório
name	string	Sim
email	string	Sim
type	string	Sim
interest	string	Sim

Valores de interest: Lease, Purchase, Investment, Both

Valores de source (origem do lead): Indication, Portal, SocialMedia, DirectContact, Other

Resposta 201: Objeto completo do cliente.

Erros:

• 409 — CPF/CNPJ já cadastrado

---

PUT /api/clients/:id

Atualiza os dados de um cliente.

Body: Mesma estrutura do POST.

Resposta 200: Objeto atualizado.

---

DELETE /api/clients/:id

Remove o cliente (soft delete).

Permissões: Admin

Resposta 204: Sem conteúdo.

Erros:

• 400 — Cliente possui contratos ativos