Contratos

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:

Valida que o imóvel existe, pertence ao usuário e está DISPONIVEL
Cria o documento do contrato
Atualiza o status do imóvel para ALUGADO
Gera uma cobrança de caução (se valorCaucao for informado)
Gera automaticamente todas as parcelas de aluguel com base na duração real do contrato

string

required

ID do imóvel. Deve estar com status: DISPONIVEL.

string

required

ID do locatário cadastrado.

string

required

Data de início no formato YYYY-MM-DD.

string

required

Data de término. O número de parcelas é calculado a partir da diferença em meses.

number

required

Valor mensal do aluguel em reais.

number

required

Dia do mês para vencimento das parcelas (ex: 5 para dia 5).

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.

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).

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ção	Obrigatória
Vistoria de saída registrada	Sim
Parcelas `PENDENTE`/`ATRASADO` zeradas	Sim

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
}

Gestão

Financeiro

Vistoria & Inventário

Plataforma

O objeto Contrato

Campos calculados no retorno

Criar contrato

Listar contratos

Buscar contrato por ID

Enviar contrato por e-mail

Registrar contrato assinado (URL)

Verificar status de encerramento

Regras de encerramento

Encerrar contrato

​O objeto Contrato

​Campos calculados no retorno

​Criar contrato

​Listar contratos

​Buscar contrato por ID

​Enviar contrato por e-mail

​Registrar contrato assinado (URL)

​Verificar status de encerramento

​Regras de encerramento

​Encerrar contrato

O objeto Contrato

Campos calculados no retorno

Criar contrato

Listar contratos

Buscar contrato por ID

Enviar contrato por e-mail

Registrar contrato assinado (URL)

Verificar status de encerramento

Regras de encerramento

Encerrar contrato