Skip to main content

​
O objeto Locatário

{
  "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

​
nome
string
required
Nome completo do locatário.
​
cpf
string
required
CPF do locatário. A API rejeita duplicatas por userId + cpf.
​
email
string
E-mail de contato.
​
whatsapp
string
Número com DDD para comunicação via WhatsApp.
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"
}
Resposta 201
{
  "message": "Locatário cadastrado com sucesso",
  "id": "loc456"
}
CPF duplicado para o mesmo userId retorna 409 Conflict.

​
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. 
GET /locatarios
Cookie: imob_session=<session_cookie>

​
Buscar locatário por ID

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. 
GET /locatarios/:id/contratos
Cookie: imob_session=<session_cookie>
Resposta 200
[
  {
    "id": "con789",
    "imovelId": "abc123",
    "imovelNome": "Apto Centro",
    "dataInicio": "2024-02-01",
    "dataFim": "2025-01-31",
    "ativo": false,
    ...
  }
]

​
Atualizar locatário

PATCH /locatarios/:id
Cookie: imob_session=<session_cookie>
Content-Type: application/json

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

​
Deletar locatário

Locatário com contrato ativo não pode ser removido. A API retorna 409 Conflict com mensagem explicativa.
DELETE /locatarios/:id
Cookie: imob_session=<session_cookie>