{ "openapi": "3.0.3", "info": { "title": "API Imóveis — CRM", "version": "1.0.0", "description": "Acesso externo ao módulo Imóveis (carteira, proprietários, locações e aluguéis, visitas, vistorias, vendas com comissão, captações, indicadores e performance por portal).\n\nAutenticação: chave de API da empresa (Configurações › API) no cabeçalho `Authorization: Bearer ` ou `X-Api-Key`. Limite: 300 requisições/min. Valores em decimal na moeda da empresa; datas AAAA-MM-DD. O imóvel é o mesmo cadastro do catálogo do CRM (products); `property_revision` é o controle de concorrência." }, "servers": [ { "url": "/api/v1/imoveis" } ], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer" } } }, "security": [ { "ApiKey": [] } ], "paths": { "/properties": { "get": { "summary": "Listar imóveis (paginado)", "parameters": [ { "name": "q", "in": "query", "description": "Título, código, bairro, endereço…", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "disponivel|preparacao|reservado|vendido|arquivado|ativos (padrão: todos)", "required": false, "schema": { "type": "string" } }, { "name": "finalidade", "in": "query", "description": "venda|aluguel", "required": false, "schema": { "type": "string" } }, { "name": "tipo", "in": "query", "description": "Tipo do imóvel", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Cidade", "required": false, "schema": { "type": "string" } }, { "name": "occupied", "in": "query", "description": "ocupado|disponivel", "required": false, "schema": { "type": "string" } }, { "name": "published", "in": "query", "description": "1 na vitrine / 0 fora", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "description": "Proprietário (contato)", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "sort", "in": "query", "description": "recente|antigo|preco_asc|preco_desc|nome", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Máx. 60", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Página de imóveis", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pages": { "type": "integer" }, "cities": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "object" } } } } } } } } } }, "post": { "summary": "Cadastrar imóvel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "Título do anúncio; em branco monta com tipo, bairro, quartos e área" }, "price": { "type": "number", "description": "Valor de venda ou do aluguel mensal (conforme finalidade)" }, "cost_price": { "type": "number", "description": "Custo de aquisição (imóvel próprio)" }, "sku": { "type": "string", "description": "Código interno / referência" }, "category": { "type": "string" }, "product_url": { "type": "string" }, "description": { "type": "string" }, "internal_notes": { "type": "string" }, "media_items": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video" ] } } }, "description": "Fotos/vídeos por URL pública; a primeira imagem é a capa" }, "attrs": { "type": "object", "properties": { "tipo": { "type": "string", "description": "Tipo do imóvel" }, "finalidade": { "type": "string", "description": "Finalidade" }, "area_util": { "type": "string", "description": "Área útil (m²)" }, "area_total": { "type": "string", "description": "Área total (m²)" }, "quartos": { "type": "string", "description": "Quartos" }, "suites": { "type": "string", "description": "Suítes" }, "banheiros": { "type": "string", "description": "Banheiros" }, "vagas": { "type": "string", "description": "Vagas" }, "valor_condominio": { "type": "string", "description": "Condomínio mensal" }, "valor_iptu": { "type": "string", "description": "IPTU anual" }, "cep": { "type": "string", "description": "CEP" }, "uf": { "type": "string", "description": "UF" }, "cidade": { "type": "string", "description": "Cidade" }, "bairro": { "type": "string", "description": "Bairro" }, "endereco": { "type": "string", "description": "Logradouro" }, "numero": { "type": "string", "description": "Número" }, "complemento": { "type": "string", "description": "Complemento" }, "andar": { "type": "string", "description": "Andar" }, "mobiliado": { "type": "string", "description": "Mobiliado" }, "aceita_pet": { "type": "string", "description": "Aceita pets" }, "proprietario_contact_id": { "type": "string", "description": "Proprietário" }, "valor_aluguel": { "type": "string", "description": "Valor do aluguel" }, "matricula": { "type": "string", "description": "Matrícula" }, "inscricao_iptu": { "type": "string", "description": "Inscrição IPTU" }, "caracteristicas": { "type": "array", "items": { "type": "string" }, "description": "Características" }, "destaques": { "type": "array", "items": { "type": "string" }, "description": "Destaques" }, "data_captacao": { "type": "string", "description": "Data de captação" }, "exclusividade": { "type": "string", "description": "Exclusividade" }, "comissao_pct": { "type": "string", "description": "Comissão (%)" }, "chaves": { "type": "string", "description": "Chaves" }, "referencia": { "type": "string", "description": "Referência" }, "ano_construcao": { "type": "string", "description": "Ano de construção" }, "posicao_solar": { "type": "string", "description": "Posição solar" }, "ocupacao": { "type": "string", "description": "Ocupação atual" } }, "description": "Características (finalidade: venda|aluguel|venda_aluguel; mobiliado/aceita_pet: sim|nao; proprietario_contact_id: contato do CRM)" }, "is_active": { "type": "boolean" }, "published_on_site": { "type": "boolean" }, "featured": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Ficha do imóvel", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/properties/{id}": { "get": { "summary": "Ficha do imóvel (mídia, proprietário, histórico, publicações, despesas, vistorias, locações, visitas, vendas, negócios)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ficha", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "put": { "summary": "Atualizar imóvel (campos ausentes são mantidos; version opcional)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "Título do anúncio; em branco monta com tipo, bairro, quartos e área" }, "price": { "type": "number", "description": "Valor de venda ou do aluguel mensal (conforme finalidade)" }, "cost_price": { "type": "number", "description": "Custo de aquisição (imóvel próprio)" }, "sku": { "type": "string", "description": "Código interno / referência" }, "category": { "type": "string" }, "product_url": { "type": "string" }, "description": { "type": "string" }, "internal_notes": { "type": "string" }, "media_items": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video" ] } } }, "description": "Fotos/vídeos por URL pública; a primeira imagem é a capa" }, "attrs": { "type": "object", "properties": { "tipo": { "type": "string", "description": "Tipo do imóvel" }, "finalidade": { "type": "string", "description": "Finalidade" }, "area_util": { "type": "string", "description": "Área útil (m²)" }, "area_total": { "type": "string", "description": "Área total (m²)" }, "quartos": { "type": "string", "description": "Quartos" }, "suites": { "type": "string", "description": "Suítes" }, "banheiros": { "type": "string", "description": "Banheiros" }, "vagas": { "type": "string", "description": "Vagas" }, "valor_condominio": { "type": "string", "description": "Condomínio mensal" }, "valor_iptu": { "type": "string", "description": "IPTU anual" }, "cep": { "type": "string", "description": "CEP" }, "uf": { "type": "string", "description": "UF" }, "cidade": { "type": "string", "description": "Cidade" }, "bairro": { "type": "string", "description": "Bairro" }, "endereco": { "type": "string", "description": "Logradouro" }, "numero": { "type": "string", "description": "Número" }, "complemento": { "type": "string", "description": "Complemento" }, "andar": { "type": "string", "description": "Andar" }, "mobiliado": { "type": "string", "description": "Mobiliado" }, "aceita_pet": { "type": "string", "description": "Aceita pets" }, "proprietario_contact_id": { "type": "string", "description": "Proprietário" }, "valor_aluguel": { "type": "string", "description": "Valor do aluguel" }, "matricula": { "type": "string", "description": "Matrícula" }, "inscricao_iptu": { "type": "string", "description": "Inscrição IPTU" }, "caracteristicas": { "type": "array", "items": { "type": "string" }, "description": "Características" }, "destaques": { "type": "array", "items": { "type": "string" }, "description": "Destaques" }, "data_captacao": { "type": "string", "description": "Data de captação" }, "exclusividade": { "type": "string", "description": "Exclusividade" }, "comissao_pct": { "type": "string", "description": "Comissão (%)" }, "chaves": { "type": "string", "description": "Chaves" }, "referencia": { "type": "string", "description": "Referência" }, "ano_construcao": { "type": "string", "description": "Ano de construção" }, "posicao_solar": { "type": "string", "description": "Posição solar" }, "ocupacao": { "type": "string", "description": "Ocupação atual" } }, "description": "Características (finalidade: venda|aluguel|venda_aluguel; mobiliado/aceita_pet: sim|nao; proprietario_contact_id: contato do CRM)" }, "is_active": { "type": "boolean" }, "published_on_site": { "type": "boolean" }, "featured": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Ficha", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "delete": { "summary": "Excluir imóvel (bloqueado se tiver negócios, vendas, locações ou cobranças)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resultado", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/properties/{id}/status": { "post": { "summary": "Mudar situação comercial (histórico preservado)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "disponivel", "preparacao", "reservado", "vendido", "arquivado" ] }, "note": { "type": "string", "description": "Obrigatória ao marcar vendido" }, "valor_venda": { "type": "number" }, "data_venda": { "type": "string", "format": "date" } } } } } }, "responses": { "200": { "description": "Ficha", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/properties/{id}/portals": { "post": { "summary": "Selecionar portais de publicação", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "portals" ], "properties": { "portals": { "type": "array", "items": { "type": "string", "enum": [ "canalpro", "chavesnamao" ] } } } } } } }, "responses": { "200": { "description": "Ficha", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/properties/{id}/expenses": { "get": { "summary": "Despesas do imóvel", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Despesas", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "summary": "Lançar despesa (entra no custo e no Caixa; pode ser repassada ao proprietário)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "descricao", "valor" ], "properties": { "descricao": { "type": "string" }, "categoria": { "type": "string", "enum": [ "manutencao", "reforma", "iptu", "condominio", "documentacao", "limpeza", "anuncio", "outros" ] }, "valor": { "type": "number" }, "data": { "type": "string", "format": "date" }, "repassar_proprietario": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Despesas e margem", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/owners": { "get": { "summary": "Proprietários (contatos ligados a imóveis) com contagem", "responses": { "200": { "description": "Proprietários", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/cep": { "get": { "summary": "Consulta de CEP (ViaCEP) → endereço pronto para o cadastro", "parameters": [ { "name": "cep", "in": "query", "description": "00000-000", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endereço", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/checklist": { "get": { "summary": "Itens do checklist de vistoria da imobiliária (chaves, seções, status, tipos)", "responses": { "200": { "description": "Checklist", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/inspections": { "get": { "summary": "Vistorias", "parameters": [ { "name": "property_id", "in": "query", "description": "Só de um imóvel", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "description": "entrada|saida|captacao|periodica|entrega", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "rascunho|concluida", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Imóvel, bairro, endereço ou cliente", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Vistorias", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "summary": "Registrar vistoria", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "property_id" ], "properties": { "property_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "entrada", "saida", "captacao", "periodica", "entrega" ] }, "status": { "type": "string", "enum": [ "rascunho", "concluida" ] }, "lease_id": { "type": "string", "format": "uuid", "description": "Locação ligada (entrada/saída)" }, "inspection_date": { "type": "string", "format": "date" }, "inspector_name": { "type": "string" }, "client_name": { "type": "string", "description": "Inquilino, comprador ou proprietário" }, "client_document": { "type": "string" }, "client_phone": { "type": "string" }, "client_email": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Chave do item (GET /checklist)" }, "status": { "type": "string", "enum": [ "ok", "attention", "problem", "na" ] }, "notes": { "type": "string" } } } }, "general_notes": { "type": "string" }, "approved": { "type": "boolean" }, "signature_name": { "type": "string" }, "signature": { "type": "string", "description": "data:image/png;base64,… (assinatura)" } } } } } }, "responses": { "200": { "description": "Vistoria", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/inspections/{id}": { "get": { "summary": "Vistoria com itens e fotos", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vistoria", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "put": { "summary": "Alterar vistoria", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "property_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "entrada", "saida", "captacao", "periodica", "entrega" ] }, "status": { "type": "string", "enum": [ "rascunho", "concluida" ] }, "lease_id": { "type": "string", "format": "uuid", "description": "Locação ligada (entrada/saída)" }, "inspection_date": { "type": "string", "format": "date" }, "inspector_name": { "type": "string" }, "client_name": { "type": "string", "description": "Inquilino, comprador ou proprietário" }, "client_document": { "type": "string" }, "client_phone": { "type": "string" }, "client_email": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Chave do item (GET /checklist)" }, "status": { "type": "string", "enum": [ "ok", "attention", "problem", "na" ] }, "notes": { "type": "string" } } } }, "general_notes": { "type": "string" }, "approved": { "type": "boolean" }, "signature_name": { "type": "string" }, "signature": { "type": "string", "description": "data:image/png;base64,… (assinatura)" } } } } } }, "responses": { "200": { "description": "Vistoria", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/inspections/{id}/pdf": { "get": { "summary": "Laudo em PDF", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/leases": { "get": { "summary": "Locações + resumo do mês (aluguéis a receber, atrasados, repasses)", "parameters": [ { "name": "status", "in": "query", "description": "ativo|encerrado|vencendo|inadimplente", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Imóvel ou inquilino", "required": false, "schema": { "type": "string" } }, { "name": "month", "in": "query", "description": "AAAA-MM", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Locações", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "post": { "summary": "Criar locação (imóvel fica ocupado; gera os aluguéis mensais no Caixa)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "property_id", "tenant_name" ], "properties": { "property_id": { "type": "string", "format": "uuid" }, "tenant_name": { "type": "string" }, "tenant_phone": { "type": "string" }, "tenant_email": { "type": "string" }, "tenant_document": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "owner_contact_id": { "type": "string", "format": "uuid", "description": "Proprietário (padrão: o do imóvel)" }, "move_in_date": { "type": "string", "format": "date" }, "contract_start": { "type": "string", "format": "date" }, "contract_end": { "type": "string", "format": "date" }, "rent_value": { "type": "number" }, "due_day": { "type": "integer", "description": "1 a 28" }, "admin_fee_pct": { "type": "number", "description": "Taxa de administração (%)" }, "deposit": { "type": "number" }, "guarantee": { "type": "string", "enum": [ "caucao", "fiador", "seguro_fianca", "titulo", "sem" ] }, "adjustment_index": { "type": "string", "enum": [ "igpm", "ipca", "inpc", "sem" ] }, "generate_payments": { "type": "boolean", "description": "Gerar os aluguéis mensais (padrão true no contrato novo)" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Locação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/leases/{id}": { "get": { "summary": "Locação com aluguéis e vistorias", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Locação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "put": { "summary": "Alterar locação", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "property_id": { "type": "string", "format": "uuid" }, "tenant_name": { "type": "string" }, "tenant_phone": { "type": "string" }, "tenant_email": { "type": "string" }, "tenant_document": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "owner_contact_id": { "type": "string", "format": "uuid", "description": "Proprietário (padrão: o do imóvel)" }, "move_in_date": { "type": "string", "format": "date" }, "contract_start": { "type": "string", "format": "date" }, "contract_end": { "type": "string", "format": "date" }, "rent_value": { "type": "number" }, "due_day": { "type": "integer", "description": "1 a 28" }, "admin_fee_pct": { "type": "number", "description": "Taxa de administração (%)" }, "deposit": { "type": "number" }, "guarantee": { "type": "string", "enum": [ "caucao", "fiador", "seguro_fianca", "titulo", "sem" ] }, "adjustment_index": { "type": "string", "enum": [ "igpm", "ipca", "inpc", "sem" ] }, "generate_payments": { "type": "boolean", "description": "Gerar os aluguéis mensais (padrão true no contrato novo)" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Locação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/leases/{id}/close": { "post": { "summary": "Encerrar locação (imóvel volta a disponível; aluguéis futuros cancelados)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Locação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/rents/{id}/pay": { "post": { "summary": "Receber (ou reabrir com undo) um aluguel", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "paid_at": { "type": "string", "format": "date" }, "forma": { "type": "string" }, "undo": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Locação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/visits": { "get": { "summary": "Visitas", "parameters": [ { "name": "range", "in": "query", "description": "proximas|hoje|semana|passadas|todas", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "agendada|confirmada|realizada|faltou|cancelada", "required": false, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Corretor", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "description": "Imóvel ou visitante", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Visitas", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "summary": "Agendar visita (entra na Agenda do corretor)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "property_id", "date", "time" ], "properties": { "property_id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string", "description": "HH:MM (fuso da empresa)" }, "duration_minutes": { "type": "integer" }, "user_id": { "type": "string", "format": "uuid", "description": "Corretor" }, "contact_id": { "type": "string", "format": "uuid" }, "visitor_name": { "type": "string" }, "visitor_phone": { "type": "string" }, "visitor_email": { "type": "string" }, "deal_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "agendada", "confirmada", "realizada", "faltou", "cancelada" ] }, "interest": { "type": "string", "enum": [ "alto", "medio", "baixo", "sem" ] }, "feedback": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Visita", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/visits/{id}": { "get": { "summary": "Visita", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Visita", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "put": { "summary": "Alterar visita", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "property_id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string", "description": "HH:MM (fuso da empresa)" }, "duration_minutes": { "type": "integer" }, "user_id": { "type": "string", "format": "uuid", "description": "Corretor" }, "contact_id": { "type": "string", "format": "uuid" }, "visitor_name": { "type": "string" }, "visitor_phone": { "type": "string" }, "visitor_email": { "type": "string" }, "deal_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "agendada", "confirmada", "realizada", "faltou", "cancelada" ] }, "interest": { "type": "string", "enum": [ "alto", "medio", "baixo", "sem" ] }, "feedback": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Visita", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/visits/{id}/status": { "post": { "summary": "Confirmar, realizar (com interesse e feedback), faltar ou cancelar", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "agendada", "confirmada", "realizada", "faltou", "cancelada" ] }, "interest": { "type": "string", "enum": [ "alto", "medio", "baixo", "sem" ] }, "feedback": { "type": "string" } } } } } }, "responses": { "200": { "description": "Visita", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/sales": { "get": { "summary": "Vendas + resumo do mês", "parameters": [ { "name": "month", "in": "query", "description": "AAAA-MM", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "concluida|cancelada", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Imóvel, comprador ou nº", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Vendas", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "post": { "summary": "Registrar venda (imóvel vai para vendido; recebimentos no Caixa; comissão do corretor)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "property_id", "price" ], "properties": { "property_id": { "type": "string", "format": "uuid" }, "price": { "type": "number" }, "sale_date": { "type": "string", "format": "date" }, "revenue_mode": { "type": "string", "enum": [ "comissao", "valor" ], "description": "comissao: imóvel de terceiro, a imobiliária recebe a comissão; valor: imóvel próprio, recebe o valor da venda" }, "agency_commission_pct": { "type": "number", "description": "Padrão: comissao_pct do imóvel ou da imobiliária" }, "owner_contact_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid", "description": "Comprador já cadastrado. Alternativa: customer_name + customer_phone cria/encontra o contato." }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "customer_email": { "type": "string" }, "customer_document": { "type": "string" }, "seller_user_id": { "type": "string", "format": "uuid", "description": "Corretor" }, "deal_id": { "type": "string", "format": "uuid" }, "financed_amount": { "type": "number", "description": "Só no modo valor" }, "financed_received": { "type": "boolean" }, "payments": { "type": "array", "description": "Somam o que a imobiliária recebe (comissão, ou venda − financiado); em branco vira um PIX recebido na data", "items": { "type": "object", "properties": { "descricao": { "type": "string" }, "forma": { "type": "string", "enum": [ "pix", "transferencia", "boleto", "cartao_credito", "dinheiro", "cheque", "financiamento", "fgts", "permuta", "outro" ] }, "valor": { "type": "number" }, "vencimento": { "type": "string", "format": "date" }, "pago": { "type": "boolean" } } } }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Venda", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/sales/{id}": { "get": { "summary": "Venda com pagamentos e comissões", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Venda", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/sales/{id}/cancel": { "post": { "summary": "Cancelar venda (imóvel volta a disponível)", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Venda", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/payments/{id}/pay": { "post": { "summary": "Receber (ou reabrir com undo) um pagamento de venda", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "paid_at": { "type": "string", "format": "date" }, "forma": { "type": "string", "enum": [ "pix", "transferencia", "boleto", "cartao_credito", "dinheiro", "cheque", "financiamento", "fgts", "permuta", "outro" ] }, "undo": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Venda", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/captures": { "get": { "summary": "Captações (proprietários que querem vender/alugar; pedidos da vitrine entram sozinhos)", "parameters": [ { "name": "status", "in": "query", "description": "novo|visita|proposta|captado|recusado|abertos", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Nome ou endereço", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Captações", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "summary": "Registrar captação", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "tipo": { "type": "string" }, "finalidade": { "type": "string", "enum": [ "venda", "aluguel", "venda_aluguel" ] }, "endereco": { "type": "string" }, "bairro": { "type": "string" }, "cidade": { "type": "string" }, "uf": { "type": "string" }, "area": { "type": "string" }, "quartos": { "type": "string" }, "asking_price": { "type": "number" }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "novo", "visita", "proposta", "captado", "recusado" ] }, "offer_notes": { "type": "string" }, "assigned_user_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Captação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/captures/{id}": { "get": { "summary": "Captação", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Captação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } }, "put": { "summary": "Alterar captação / registrar proposta", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "tipo": { "type": "string" }, "finalidade": { "type": "string", "enum": [ "venda", "aluguel", "venda_aluguel" ] }, "endereco": { "type": "string" }, "bairro": { "type": "string" }, "cidade": { "type": "string" }, "uf": { "type": "string" }, "area": { "type": "string" }, "quartos": { "type": "string" }, "asking_price": { "type": "number" }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "novo", "visita", "proposta", "captado", "recusado" ] }, "offer_notes": { "type": "string" }, "assigned_user_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Captação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/captures/{id}/accept": { "post": { "summary": "Captar: cria o imóvel na carteira (em preparação) com o proprietário", "parameters": [ { "name": "id", "in": "path", "description": "Identificador (UUID)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "price": { "type": "number" }, "finalidade": { "type": "string" }, "comissao_pct": { "type": "number" }, "exclusividade": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Captação", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/dashboard": { "get": { "summary": "Visão geral (carteira, ocupação, contratos vencendo, aluguéis, vendas, visitas, alertas)", "responses": { "200": { "description": "Indicadores", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/reports": { "get": { "summary": "Relatórios por período", "parameters": [ { "name": "months", "in": "query", "description": "3 a 24 (padrão 12)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Relatórios", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/portals/performance": { "get": { "summary": "Performance por portal (anúncios, leads, ganhos, custo) no mês", "parameters": [ { "name": "month", "in": "query", "description": "AAAA-MM", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Performance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } } } }