Skip to main content

​
O objeto Contrato

{
  "id": "con789",
  "imovelId": "abc123",
  "locatarioId": "loc456",
  "dataInicio": "2025-02-01",
  "dataFim": "2026-01-31",
  "valorAluguel": 2500,
  "diaVencimento": 5,
  "numeroParcelas": 12,
  "ativo": true,
  "contratoAssinadoKey": "uid123/contratos/con789/contrato.pdf",
  "assinadoEm": "2025-02-01T14:00:00.000Z",
  "userId": "uid_do_usuario",
  "criadoEm": "2025-01-28T10:00:00.000Z",
  "imovel": {
    "id": "abc123",
    "nome": "Apto Centro",
    "endereco": "Rua das Flores, 123",
    "rua": "Rua das Flores",
    "numero": "123",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "estado": "SP"
  },
  "locatario": {
    "id": "loc456",
    "nome": "João da Silva",
    "cpf": "123.456.789-00",
    "email": "joao@email.com",
    "telefone": "(11) 99999-0000"
  }
}

​
Campos calculados no retorno

Todos os endpoints de busca retornam os objetos imovel e locatario embutidos no contrato, populados em paralelo via Promise.all. Nenhuma query extra é necessária no frontend.

​
Criar contrato

A criação é executada em uma Firestore Transaction, garantindo consistência total. Em uma única operação atômica:
  1. Valida que o imóvel existe, pertence ao usuário e está DISPONIVEL
  2. Cria o documento do contrato
  3. Atualiza o status do imóvel para ALUGADO
  4. Gera uma cobrança de caução (se valorCaucao for informado)
  5. Gera automaticamente todas as parcelas de aluguel com base na duração real do contrato
​
imovelId
string
required
ID do imóvel. Deve estar com status: DISPONIVEL.
​
locatarioId
string
required
ID do locatário cadastrado.
​
dataInicio
string
required
Data de início no formato YYYY-MM-DD.
​
dataFim
string
required
Data de término. O número de parcelas é calculado a partir da diferença em meses.
​
valorAluguel
number
required
Valor mensal do aluguel em reais.
​
diaVencimento
number
required
Dia do mês para vencimento das parcelas (ex: 5 para dia 5).
​
valorCaucao
number
Valor do depósito caução. Se informado e maior que zero, cria uma cobrança do tipo CAUCAO com vencimento na dataInicio.
POST /contratos
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "imovelId": "abc123",
  "locatarioId": "loc456",
  "dataInicio": "2025-02-01",
  "dataFim": "2026-01-31",
  "valorAluguel": 2500,
  "diaVencimento": 5,
  "valorCaucao": 5000
}
Resposta 201
{
  "message": "Contrato e parcelas geradas com sucesso.",
  "contratoId": "con789",
  "numeroParcelas": 12
}
Tentativas de criar contrato para um imóvel com status: ALUGADO retornam 400 Bad Request com a mensagem "Este imóvel já está alugado".

​
Listar contratos

Retorna todos os contratos do usuário com imovel e locatario populados. 
GET /contratos
Cookie: imob_session=<session_cookie>

​
Buscar contrato por ID

GET /contratos/:id
Cookie: imob_session=<session_cookie>

​
Enviar contrato por e-mail

Envia o PDF do contrato como anexo para o e-mail do locatário via Brevo. As credenciais do Brevo são lidas de configuracoes_notificacoes do usuário autenticado.
​
pdfBase64
string
required
PDF do contrato codificado em base64.
POST /contratos/:id/enviar-email
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "pdfBase64": "JVBERi0xLjQKJcfs..."
}
Resposta 200
{
  "message": "Contrato enviado para joao@email.com com sucesso."
}
Pré-condições para o envio:
  • Locatário deve ter email cadastrado — caso contrário retorna 422
  • brevoApiKey e brevoEmailRemetente devem estar configurados em Configurações > Notificações — caso contrário retorna 422

​
Registrar contrato assinado (URL)

Salva a URL de um contrato assinado já hospedado (MinIO ou outro storage).
​
contratoAssinadoUrl
string
required
URL pública ou pressinada do PDF assinado.
POST /contratos/:id/upload-assinado
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "contratoAssinadoUrl": "https://..."
}
Para fazer o upload direto do arquivo PDF, use POST /upload/contrato/:contratoId. Esse endpoint salva no MinIO e registra a key automaticamente.

​
Verificar status de encerramento

Retorna um diagnóstico completo sobre as condições para encerrar o contrato — sem fazer nenhuma alteração. 
GET /contratos/:id/status-encerramento
Cookie: imob_session=<session_cookie>
Resposta 200
{
  "podeEncerrar": false,
  "alertaEncerramento": true,
  "bloqueios": {
    "vistoriaSaidaPendente": true,
    "pendenciasFinanceiras": 2,
    "imovelId": "abc123"
  },
  "info": {
    "contratoPrazoVencido": true,
    "dataFim": "2026-01-31",
    "semPendencias": false,
    "temVistoriaSaida": false
  }
}

​
Regras de encerramento

CondiçãoObrigatória
Vistoria de saída registradaSim
Parcelas PENDENTE/ATRASADO zeradasSim

​
Encerrar contrato

Encerra o contrato e libera o imóvel para locação. Executa em transaction atômica. 
PATCH /contratos/:id/encerrar
Cookie: imob_session=<session_cookie>
Resposta 200
{
  "message": "Contrato encerrado e imóvel liberado com sucesso.",
  "imovelLiberado": true
}
Erros possíveis:
422 — Vistoria de saída pendente
{
  "error": "Vistoria de saída obrigatória antes de encerrar o contrato.",
  "codigo": "VISTORIA_SAIDA_PENDENTE",
  "imovelId": "abc123"
}
422 — Pendências financeiras
{
  "error": "Existem 2 parcela(s) não quitada(s). Quite todas as pendências antes de encerrar.",
  "codigo": "PENDENCIAS_FINANCEIRAS",
  "pendencias": 2
}