> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patrimonion.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Locatários

> Cadastro e gestão de locatários, com verificação de duplicidade por CPF e histórico de contratos.

## O objeto Locatário

```json theme={null}
{
  "id": "loc456",
  "nome": "João da Silva",
  "cpf": "123.456.789-00",
  "rg": "12.345.678-9",
  "dataNascimento": "1990-05-20",
  "sexo": "Masculino",
  "estadoCivil": "Solteiro",
  "profissao": "Engenheiro",
  "nacionalidade": "Brasileiro(a)",
  "email": "joao@email.com",
  "telefone": "(11) 99999-0000",
  "whatsapp": "(11) 99999-0000",
  "endereco": {
    "cep": "04567-000",
    "rua": "Av. Paulista",
    "numero": "1000",
    "complemento": "",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "estado": "SP"
  },
  "nomeEmergencia": "Maria da Silva",
  "telefoneEmergencia": "(11) 98888-0000",
  "documentos": {},
  "temContratoAtivo": true,
  "userId": "uid_do_usuario",
  "criadoEm": "2025-01-10T14:00:00.000Z"
}
```

### Campo `temContratoAtivo`

Calculado em tempo real na listagem — verifica se existe ao menos um contrato com `ativo: true` para este locatário. Não é persistido no banco.

***

## Criar locatário

<ParamField body="nome" type="string" required>
  Nome completo do locatário.
</ParamField>

<ParamField body="cpf" type="string" required>
  CPF do locatário. A API rejeita duplicatas por `userId + cpf`.
</ParamField>

<ParamField body="email" type="string">
  E-mail de contato.
</ParamField>

<ParamField body="whatsapp" type="string">
  Número com DDD para comunicação via WhatsApp.
</ParamField>

```http theme={null}
POST /locatarios
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "nome": "João da Silva",
  "cpf": "123.456.789-00",
  "email": "joao@email.com",
  "telefone": "(11) 99999-0000",
  "cep": "04567-000",
  "rua": "Av. Paulista",
  "numero": "1000",
  "bairro": "Bela Vista",
  "cidade": "São Paulo",
  "estado": "SP"
}
```

```json Resposta 201 theme={null}
{
  "message": "Locatário cadastrado com sucesso",
  "id": "loc456"
}
```

<Warning>
  CPF duplicado para o mesmo `userId` retorna `409 Conflict`.
</Warning>

***

## Listar locatários

Retorna todos os locatários do usuário, ordenados por nome (pt-BR). Inclui o campo `temContratoAtivo` calculado via batch query — sem N+1.

```http theme={null}
GET /locatarios
Cookie: imob_session=<session_cookie>
```

***

## Buscar locatário por ID

```http theme={null}
GET /locatarios/:id
Cookie: imob_session=<session_cookie>
```

***

## Histórico de contratos

Retorna todos os contratos do locatário, enriquecidos com `imovelNome`, ordenados por `criadoEm` decrescente.

```http theme={null}
GET /locatarios/:id/contratos
Cookie: imob_session=<session_cookie>
```

```json Resposta 200 theme={null}
[
  {
    "id": "con789",
    "imovelId": "abc123",
    "imovelNome": "Apto Centro",
    "dataInicio": "2024-02-01",
    "dataFim": "2025-01-31",
    "ativo": false,
    ...
  }
]
```

***

## Atualizar locatário

```http theme={null}
PATCH /locatarios/:id
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "telefone": "(11) 98765-4321",
  "profissao": "Arquiteto"
}
```

***

## Deletar locatário

<Warning>
  Locatário com contrato ativo **não pode ser removido**. A API retorna `409 Conflict` com mensagem explicativa.
</Warning>

```http theme={null}
DELETE /locatarios/:id
Cookie: imob_session=<session_cookie>
```