Operações no Mapaprop — Guia Completo

PARTE 1 — Manual do Usuário

1. O que são as Operações?

Uma operação é o registro de uma transação comercial sobre um imóvel: uma reserva, uma venda, uma locação, uma permuta, ou uma operação caída. É o "o que aconteceu, quando, com quem e a que preço" de cada movimento do imóvel.

Exemplo concreto

Seu corretor María fecha uma reserva de um apartamento por USD 130.000 com sinal de USD 5.000. Uma semana depois, o comprador assina o contrato e a venda é fechada por USD 128.000 (negociou USD 2.000 a menos). O Mapaprop guarda uma única operação que passou por dois estados: primeiro Reservada, depois Vendida. Essa operação fica registrada com: preço de publicação (USD 139.000), oferta do comprador (USD 130.000), sinal (USD 5.000), preço de fechamento (USD 128.000), comprador, proprietário, corretor responsável, filial, datas. Tudo isso alimenta seus relatórios de gestão e seu histórico comercial.

2. Para que serve?

As Operações existem porque, antes, o Mapaprop guardava apenas o estado atual de cada imóvel (vendido, alugado, etc) sem contexto. Com as Operações agora você pode:

3. Como se compõe uma operação

Cada operação tem 4 partes de informação:

3.1 Estado

Indica em que momento do ciclo está a operação. Só pode ser um destes:

⚠️ Uma operação fechada (Vendida / Alugada / etc) NÃO pode ser revertida. Se depois a operação cair, é preciso criar uma operação nova com estado Caída. A fechada fica como histórico.

3.2 Tipo

Indica de que tipo de transação se trata. É derivado automaticamente do tipo de operação que o imóvel cadastrado tiver (Venda, Locação, Temporada, Permuta).

3.3 Dados econômicos

3.4 Participantes

• Vendedor / Proprietário: quem era o dono do imóvel (da sua lista de contatos).
• Comprador / Locatário: quem fez a operação (da sua lista de contatos).
• Corretor responsável: o usuário do Mapaprop que abriu a operação.
• Filial: a filial à qual a operação pertence (é herdada do imóvel).

4. Dois modos para registrar uma operação: Básico e Business

Quando você fecha uma operação a partir da ficha de um imóvel, abre-se a janela "Fechamento de Operação". Ali você pode escolher entre 2 formas de registrá-la:

4.1 Modo Básico

• O que faz? Só muda o estado do imóvel (Reservada / Vendida / Alugada / Suspensa) e opcionalmente registra um preço de fechamento.
• O que NÃO faz? Não guarda contatos, nem comissão, nem histórico detalhado. Não gera operação rastreável nos relatórios.
• Quem usa? Imobiliárias pequenas que só precisam marcar o estado dos seus imóveis sem se preocupar com relatórios de gestão.
• Plano necessário: qualquer um (Free, Plus, Pro+, Business).

4.2 Modo Business (recomendado)

• O que faz? Cria uma operação completa com todos os dados: contatos, oferta, sinal, fechamento, comissão, comentários. Depois aparece em todos os relatórios.
• Plano necessário: Business ou Business Manager (planos 56 e 57).

4.3 Tabela comparativa

💡 Recomendação: se você tem o plano Business, use sempre o modo Business. É a única forma de aproveitar os relatórios de gestão.

4.4 Decisão por plano

5. Como registrar uma operação passo a passo

5.1 Criar uma reserva

1. Entre na ficha do imóvel → botão "Fechamento de Operação".
2. A janela abre. Escolha "Reservada" entre as opções de estado.
3. Se você tem o Business, vai para o wizard por etapas:
   • Estado: você já escolheu Reservada.
   • Tipo de operação (aparece somente ao reservar sobre seus próprios imóveis): você escolhe como se compõe a operação — Ponta única (você representa uma parte), Ponta dupla (você leva vendedor E comprador) ou Co-brokering (o comprador foi trazido por outro corretor do seu escritório ou da sua rede no Mapaprop). Em Ponta dupla e Co-brokering o sistema cria 2 operações vinculadas (ver §7.12). Há ainda uma opção "Operação externa" que leva você a Minhas Operações para registrar uma operação sobre um imóvel que não está no Mapaprop (ver §7.10).
   • Valores: informe a oferta do comprador. Se houve sinal, marque a caixa de seleção e coloque o valor.
   • Participantes: vincule vendedor e comprador a partir dos seus contatos. Você pode escolher um já vinculado ao imóvel, buscá-lo ou criá-lo na hora. Qualquer contato que você vincule aqui também fica vinculado ao imóvel — você vai vê-lo depois na ficha, na aba Contatos (o vendedor como Dono, o comprador como Interessado).
   • Comentários: opcional, para deixar contexto interno.
4. Clique em Salvar Operação.

O imóvel fica marcado como Reservada e aparece um chip vermelho "Operação em andamento" na sua ficha.

5.2 Fechar a operação (Vendida / Alugada / etc)

Há 2 formas de chegar ao fechamento:

Opção A — A partir da ficha do imóvel:

1. Clique em "Gerenciar Operação" (botão vermelho). Leva você ao detalhe da operação reservada.
2. Ali você escolhe o estado de destino: Fechar como Vendida / Fechar como Alugada / etc.
3. A janela pede o Preço de fechamento e a Comissão — ambos os campos são obrigatórios ao fechar (as outras seções ficam recolhidas porque você já tinha os dados carregados).
4. Clique em Atualizar Operação.

Opção B — Diretamente a partir da ficha do imóvel:

1. Clique em "Fechamento de Operação".
2. Você escolhe o estado terminal diretamente (ex: Vendida).
3. A janela abre com os dados da reserva pré-carregados. Você completa o fechamento e a comissão.
4. Salvar.

Depois do fechamento:

• A operação fica com estado terminal e data de fechamento.
• O imóvel fica marcado como Vendida (ou Alugada se foi locação / temporada / permuta).
• É registrado no histórico de preços do imóvel.
• Aparece no relatório de "Minhas Operações" do corretor que fechou.

5.3 Cancelar uma reserva (Caída)

Quando uma reserva não se concretiza:

1. A partir da ficha do imóvel → "Gerenciar Operação" → estado Caída.
2. Ou a partir do detalhe da operação → botão vermelho "Cancelar reserva".
3. Salvar.

A operação passa a Caída (não pode ser revertida), o imóvel volta a Disponível automaticamente, e fica registrada como caída nos relatórios (contribui para a "taxa de queda" do corretor).

5.4 Editar enquanto a operação está em andamento

Enquanto a operação estiver Reservada você pode corrigir seus dados sem mudar o estado. Há dois caminhos:

• A partir do detalhe da operação (/deals/[id]) → botão "Editar": abre uma janela para ajustar oferta e moeda, sinal, contatos (vendedor / comprador) e comentários. A comissão não é tocada aqui — é carregada apenas ao fechar. Este botão é para administradores da conta.
• A partir da ficha do imóvel → "Gerenciar Operação": a janela abre com seções recolhíveis (Estado / Valores / Participantes / Comentários) para editar o que precisar.

💡 Antes só era possível editar uma reserva em "Gerenciar Operação" na ficha do imóvel. Desde 2026-08 também há um botão "Editar" diretamente no detalhe da operação, para não ter que voltar ao imóvel.

5.5 Voltar um imóvel para "Disponível"

Se um imóvel está reservado e o cliente mudou de ideia sem formalizar a queda, você NÃO pode mandá-lo direto para Disponível enquanto ele tiver uma operação em andamento. O Mapaprop bloqueia você com uma mensagem:

"Há uma operação reservada em andamento. Para mudar o estado do imóvel você precisa resolvê-la em Gerenciar Operação ou marcá-la como Caída."

Dois caminhos:

• Clique em "Marcar como caída" a partir da mensagem de bloqueio → cancela a reserva e libera o imóvel com um único clique.
• Clique em "Gerenciar Operação" → resolver manualmente (fechamento concretizado ou queda).

Isso evita que fiquem operações órfãs (reservadas no sistema mas o imóvel já foi colocado à venda de novo).

5.6 Mudar o estado de um imóvel já vendido/alugado

Se o imóvel está vendido (operação fechada) e você quer voltar a colocá-lo à venda, você pode:

1. Marcá-lo como Disponível a partir da ficha (isso NÃO afeta a operação fechada — ela continua ali como histórico).
2. Criar uma nova operação quando chegar outra reserva. O histórico ficará com: deal antigo (vendido) + deal novo (reservado/fechado/caído).

6. Os 6 relatórios de operações

Todos acessíveis a partir do menu Painel → Relatórios.

6.1 Todas as operações (/deals)

Listagem completa e filtrável de todas as operações da sua conta.

• Filtros: período (de/até), tipo de operação, estado, ponta (vendedora/compradora — ver §7.9), origem (própria/externa/excluída — ver §7.11), filial, corretor.
• Mini-cards no topo com 12 KPIs ao vivo (ver §6.7) que respeitam os filtros aplicados.
• Tabela com colunas: Id (o número da operação, ex. #1234, com link direto ao detalhe), Imóvel, Agente / Filial (o corretor responsável e sua filial), Contato, Tipo, Ponta (badge verde Vendedora / roxo Compradora / cinza Ambas), Origem (badge cinza 🏠 Própria / roxo 🔗 Externa / vermelho 🗑️ Excluída), Estado, Oferta, Fechamento, Comissão, Data. Uma linha também pode mostrar um ícone de alerta quando a operação faz parte de um par vinculado com uma anomalia (ver §7.12).
• Chips de filtros ativos com X para remover individualmente.
• Botão "+ Adicionar operação" (admins): cria operação manual sem imóvel associado (ver §7.10).
• Exportar para CSV para análise externa (respeita os filtros).
• Mobile: cards em vez de tabela.
• Quem vê: admins (main / manager). Os vendors são redirecionados automaticamente para "Minhas Operações".

6.2 Minhas Operações (/deals/my-deals)

Dashboard pessoal do corretor. Pensado para que cada vendedor meça sua performance.

• Identificação da sua filial no topo (logo ou ícone + nome + endereço + contato).
• KPIs: reservas abertas, fechadas no período, comissões ARS, comissões USD.
• Taxas: fechamento e queda.
• Listas rápidas: reservas abertas + últimos fechamentos com clique para ver o detalhe.
• Botão "+ Adicionar operação": permite registrar uma operação manual sobre um imóvel externo (ver seção 7.10).
• Quem vê: todos. Os vendors veem só o que é deles automaticamente.

6.3 Imobiliária (/deals/business)

Estatísticas consolidadas da sua imobiliária com ranking de corretores.

• Identificação do seu escritório no topo (logo + nome + dados do customer).
• KPIs globais: reservas, fechamentos, comissões, taxas.
• Ranking de corretores: tabela ordenada por fechamentos com volume e taxa de fechamento.
• Distribuição por tipo de operação: barras visuais (venda / locação / etc).
• Fechamentos por mês: tabela de evolução temporal.
• Quem vê: admins (main / manager / adminMain). Os vendors não.

6.4 Rede (/deals/network)

Visão cross-office para gestores de redes de franquias. Disponível somente no plano BusinessManager.

• KPIs agregados de toda a rede.
• Ranking de franquias: tabela com drill-down (clique em uma franquia leva você à "Imobiliária" dela).
• Quem vê: apenas customer:manager (BusinessManager) + admin:main (suporte Mapaprop).

6.5 Captações (/deals/captations)

Relatório de imóveis aprovados pela moderação e pendentes no período.

• Captações aprovadas: quantos imóveis novos passaram pelo controle de moderação.
• Pendentes: quantos estão aguardando aprovação.
• Efetividade: % de captações que terminaram em fechamento (cálculo aproximado).
• Fechamentos do período: para contraste.
• Tabela: detalhe por imóvel.
• Quem vê: todos os perfis.

ℹ️ Nota sobre efetividade: o cálculo é aproximado — divide os fechamentos do período pelas captações do período sem verificar se os fechamentos correspondem realmente aos imóveis captados. É um guia, não um funil exato.

6.6 Margem de Negociação (/deals/brecha)

Três métricas-chave da sua negociação:

• Publicação para oferta: quanto menos os compradores oferecem em relação ao preço publicado (em média).
• Oferta para fechamento: quanto se ajusta entre a oferta inicial e o fechamento.
• Desconto final total: a margem entre publicação e fechamento. É medido direto (publicação contra fechamento), não é a subtração dos dois indicadores anteriores.
• Sinal médio: % do fechamento que é cobrado como sinal.

A tela explica isso sozinha:

• Cada indicador mostra sobre quantas operações foi calculado.
• Um detalhe por operação lista quais operações alimentam cada número (e marca as que não contribuem, por exemplo por ter oferta e fechamento em moedas distintas).
• O botão "Apenas dados completos" recalcula os três indicadores usando unicamente as operações com publicação + oferta + fechamento na mesma moeda → assim os três números ficam sobre o mesmo grupo e aí sim são comparáveis entre si.
• Quem vê: admins (main / manager / adminMain). Os vendors não (é informação estratégica de gestão). No dashboard da imobiliária há um acesso direto "Ver análise de margem".

6.7 Mini-cards de KPIs (em todos os relatórios)

No topo de cada listagem de operações (/deals, my-deals, branch, network) há uma grade de 12 mini-cards com métricas ao vivo. Todas respeitam os filtros aplicados (período, filial, etc.). Cada card tem tooltip ao passar o mouse com a fórmula exata do cálculo.

Linha 1 — Volume e contagens:

Linha 2 — Performance + mix (só aparece se houver deals fechados):

💡 A linha 2 é nova (maio de 2026). Se o período não tiver fechamentos, só é exibida a linha 1.

7. Regras importantes

7.1 Uma única reserva por imóvel

Cada imóvel pode ter uma única operação em estado Reservada ao mesmo tempo. Se você tentar criar uma segunda reserva, o sistema usa a existente.

7.2 As operações nunca são excluídas

Política firme. Uma vez criada uma operação, ela fica no sistema para sempre. Motivos:

• As migrações de plano não afetam seu histórico (se você passa de Business para Free e volta, recupera tudo).
• Os relatórios de gestão precisam de séries temporais longas.
• Auditoria comercial completa.

Se você cadastrou uma operação por engano, pode mudá-la para o estado Caída com um comentário esclarecedor. Não há exclusão física.

7.3 Estados terminais não são reabertos

Uma vez que uma operação passa para Vendida / Alugada / Caída / etc, esse estado fica fixo. Se você precisa registrar uma nova negociação sobre o mesmo imóvel, cria uma operação nova.

7.4 Os imóveis excluídos conservam suas operações

Se você exclui um imóvel do sistema, as operações associadas não são excluídas. Ficam acessíveis a partir da listagem global com um snapshot dos dados básicos do imóvel (endereço, código, zona) mas marcadas como "(excluída)".

7.5 Margem de negociação: preencha sempre o preço de fechamento

Para que a margem funcione bem, garanta que você sempre preencha o campo "Preço de fechamento" ao fechar uma operação (é obrigatório no modo Business). O preço de oferta é opcional mas recomendado.

7.6 Operação em andamento bloqueia mudanças de estado do imóvel

Se um imóvel tem uma reserva ativa, você não pode mudar seu estado para Disponível ou Suspensa sem antes resolver a reserva (fechá-la como Vendida/Alugada/etc ou marcá-la como Caída). O sistema avisa você com uma mensagem e oferece marcá-la como caída com um único clique.

7.7 O tipo de operação é derivado do tipo do imóvel

Quando você cria uma nova operação sobre um imóvel de locação, a operação nasce com o tipo "Locação" automaticamente. Você não precisa escolhê-lo. Se o imóvel é de venda, nasce como "Venda". Isso evita inconsistências entre o tipo de imóvel e o tipo de operação.

7.8 Todo fechamento nasce a partir de uma reserva

Regra: você não pode fechar uma operação como Vendida / Alugada / Permutada / Locação por temporada diretamente sobre um imóvel que está Disponível ou Suspenso. Primeiro você precisa criar uma Reserva, e a partir dela fechá-la.

Por quê: a reserva é o momento em que se registra a oferta, o sinal (se houver), os participantes (vendedor + comprador) e a cotação do dólar na abertura. Sem essa informação a operação fechada fica incompleta e se perde rastreabilidade para os relatórios (margem de negociação, comissões, captações, etc).

Como funciona na UI:

• No modal "Fechamento de Operação" sobre um imóvel disponível ou suspenso, os cards de estados terminais (Vendida / Permutada / etc) aparecem desabilitados em cinza.
• Você só pode clicar em Reservada ou Suspensa a partir de um imóvel disponível.
• Uma vez criada a reserva, você vai para Ver Operação (/deals/[id]) e a partir dali encontra o botão "Fechar como X" (Vendida / Alugada / Permutada / Temporada).

Exceção possível (em avaliação): locação por temporada poderia permitir fechamento direto no futuro porque costuma fechar rápido sem negociação prévia. Por enquanto a regra se aplica universalmente. Essa decisão fica anotada no roadmap do produto.

Se você precisa registrar um fechamento sobre uma operação que já aconteceu "fora do sistema" (ex: você cadastra uma venda histórica para relatórios): crie a reserva com dados mínimos (oferta = preço de fechamento, sinal 0) e depois feche-a como Vendida. O processo é de 2 cliques.

7.9 Ponta vendedora vs compradora (pd_side)

Cada operação tem um campo ponta (pd_side) que indica o papel da sua imobiliária naquela transação:

Como é atribuído automaticamente ao criar:

• Modal aberto a partir da ficha de um imóvel da sua conta (ou do seu corretor) → a operação nasce como seller_side.
• Modal aberto como operação manual sem imóvel (imóvel externo) → a operação nasce como buyer_side.

Não é necessário que o usuário escolha a ponta: o sistema a infere do contexto. Se no futuro você precisar registrar ambas as pontas, esse fluxo ficará disponível.

Onde você vê isso na UI: na página /deals/[id] há um chip que mostra "Ponta vendedora", "Ponta compradora" ou "Ambas as pontas" conforme o valor do campo.

Comissão por ponta (implementado em 2026-07-30): quando uma operação tem dois corretores (um co-brokering) ou quando um mesmo escritório leva as duas pontas (par direto ponta-dupla), o sistema cria duas operações vinculadas — uma por ponta — e cada uma leva sua própria comissão. A comissão é carregada ao fechar cada ponta (Vendida/Alugada), nunca ao reservar, e cada ponta é fechada separadamente. Nos relatórios, o par conta como uma operação (o volume não é duplicado), mas as duas comissões somam. Ver §7.11.

7.10 Operação manual com imóvel externo

Quando usar: quando o imóvel que você está trabalhando não está cadastrado na sua conta Mapaprop. Por exemplo:

• Você leva um comprador para ver um imóvel de outra imobiliária.
• Você trabalha em cobrokerage informal com um colega e quer deixar rastro da operação.
• Você registra uma venda histórica de um imóvel que nunca foi publicado na sua plataforma.

Como criar uma operação manual:

O botão abre o mesmo modal de operação, mas em modo "manual" (sem imóvel da conta vinculado).

💡 Você também chega a partir de um imóvel: se você está registrando uma operação sobre um dos seus imóveis e na etapa "Tipo de operação" percebe que na verdade a operação é sobre outro imóvel que não está no Mapaprop, escolha a opção "Operação externa". Ela leva você direto a Minhas Operações, onde você a registra com o botão "+ Adicionar operação". Existe para que essa opção esteja à vista e não seja preciso saber de antemão onde as operações externas são carregadas.

Como o modal aparece em modo manual:

• Header: ícone roxo 🔗 + título "Operação Externa" + badge roxo "Ponta compradora".
• Banner explicativo roxo no topo: "Operação sobre um imóvel que não está no Mapaprop. Você é ponta compradora..."

O que o modal pede — campos obrigatórios marcados com *:

1. Tipo de operação (4 botões tipo card com ícone):
   • 🏷️ Venda
   • 🔑 Locação
   • 📅 Locação por Temporada
   • 🔄 Permuta

   Os labels e a ordem vêm do sistema multi-país (mesmo seletor que você vê ao cadastrar um imóvel). Se no futuro o Mapaprop operar em outros países, os labels são traduzidos automaticamente.

2. Endereço do imóvel (input de texto livre, máx 255 caracteres). Exemplo: "Av. Cabildo 1234, CABA". Serve para identificar a operação em listagens e relatórios — sem isso o deal fica como "Sem endereço registrado".
3. Filial ⚠️ (obrigatória a partir de 2026-05-29 para Admin / Main / Manager): a que filial da sua imobiliária a operação corresponde. Se você não a escolher, o botão "Próximo" fica desabilitado. Para vendor sua filial é atribuída automaticamente e este campo não aparece.
4. Estado (cards): só aparecem Reservada e os terminais (Vendida / Alugada / etc conforme o tipo escolhido). Os cards Disponível e Suspensa são ocultados: não se aplicam a imóveis externos.
5. Oferta e valores: igual à operação normal (oferta, sinal/reserva, fechamento, comissão). Lembre-se de que ao fechar (Vendida/Alugada) a comissão é obrigatória (ver §5.2).
6. Participantes: seletor de contatos para Vendedor/Proprietário (a contraparte, costuma ser um corretor ou o dono direto) e Comprador/Locatário (seu cliente). Ambos opcionais mas recomendados para rastreabilidade. Em modo externo o "vendedor" é carregado como contato local sem se vincular formalmente a um imóvel (não há imóvel no sistema).
7. Comentários: campo livre.

Limitações conforme o perfil:

Caso de uso típico para o vendor: "Acompanhei um comprador para ver um apartamento de outra imobiliária, ele ficou interessado, reservei de maneira informal. Quero deixar rastro para não perder a operação." → crie uma operação manual Reservada a partir de "Minhas Operações". Quando a operação se concretizar, avise seu admin para que ele a feche como Vendida ou Alugada.

Dica: se a contraparte é outra imobiliária ou um corretor colega, você pode cadastrar esse contato com o tipo "Broker" (ver seção 8.5) e vinculá-lo ao campo Vendedor da operação. Assim você tem rastreabilidade de com quem trabalhou o cobrokerage.

7.11 Origem da operação: Própria / Externa / Co-brokering / Ponta dupla / Excluída

Cada operação tem um campo "Origem" que a classifica. As origens Co-brokering e Ponta dupla marcam a ponta compradora de uma operação vinculada (ver §7.12). Permite filtrar e entender num relance que tipo de operação você está olhando.

Filtrar por origem: em /deals o dropdown "Origem" tem 4 opções: Todas / Própria / Externa / Excluída. Útil para:

• Ver só operações manuais do período (origem Externa) e medir seu volume de cobrokerage informal.
• Auditar operações órfãs (origem Excluída) e decidir se você as limpa ou conserva.
• Filtrar só operações internas (origem Própria) para relatórios "limpos" sem manuais nem órfãs.

Exemplo concreto:

• Você levou um comprador a um apartamento da Remax em março. Cadastrou uma operação manual a partir de "Minhas Operações" → operação com origem Externa, ponta Compradora.
• Em abril você fechou uma venda do seu imóvel código MP007 com um comprador habitual → origem Própria, ponta Vendedora.
• Em maio você excluiu o imóvel MP007 do catálogo (decidiu não relistá-lo) → a operação de abril muda para origem Excluída automaticamente, mas conserva o código MP007 como dado histórico (snapshot).

💡 A origem é atribuída pelo sistema automaticamente. Não é algo que você carrega manualmente.

7.12 Operações vinculadas: co-brokering e ponta dupla

Às vezes uma operação não é uma só: são duas operações vinculadas, uma para cada ponta (a vendedora e a compradora). Acontece em dois casos:

• Co-brokering — o comprador foi trazido por outro corretor (do seu escritório ou da sua rede no Mapaprop). Cada escritório administra e fecha a sua ponta, com a sua comissão.
• Par direto ponta-dupla — você (um mesmo escritório/corretor) leva as duas pontas: representa o vendedor E o comprador. São criadas igualmente duas operações vinculadas, uma por ponta, cada uma com sua comissão.

Em ambos os casos:

• São criadas 2 operações em /deals, com badge "Co-brokering" (verde) ou "Ponta dupla" (azul), unidas entre si (card "Operação vinculada" no detalhe).
• A comissão de cada ponta é carregada ao fechar essa ponta (Vendida/Alugada), nunca ao reservar.
• Cada ponta é fechada separadamente (uma pode ser fechada e a outra cair). O sistema marca com um ícone de alerta (na listagem /deals e no detalhe /deals/[id]) duas anomalias do par:
  • Estados distintos: uma ponta fechou e a outra caiu.
  • Preços de fechamento distintos: as duas pontas fecharam (Vendida / Alugada) mas com preços de fechamento diferentes. Como é o mesmo imóvel deveria haver um único preço de venda — a comissão sim difere por ponta, o preço de fechamento não. O alerta avisa você para que revise e corrija.
• Nos relatórios, o par conta como uma operação (o volume não é duplicado), mas as duas comissões somam.

Como é criada: ao registrar uma reserva sobre seu imóvel (com Business), o wizard tem uma etapa "Tipo de operação" onde você escolhe:

• Ponta dupla → você leva as duas pontas (vendedor + comprador). O sistema cria automaticamente as 2 operações vinculadas.
• Co-brokering → o comprador foi trazido por outro corretor. Você escolhe a contraparte com um seletor em cascata: escritório → filial → corretor. Você pode escolher um colega do seu próprio escritório ou de qualquer outro escritório da sua rede no Mapaprop (redes tipo MLS fechada), com sua filial e seu corretor. O sistema cria as 2 operações vinculadas.
• Ponta única → é registrada uma única operação (captação ou ponta única, sem vínculo).

A comissão de cada ponta é carregada ao fechar essa ponta, nunca ao reservar. (Antes isso era escolhido com uma caixa "É um co-brokering" na etapa de estado; a partir de 2026-08 é uma etapa própria com as 3 opções.)

8. Casos especiais

8.1 Corretor sem filial atribuída

Se um vendor do sistema não tem filial atribuída, ele pode acessar as Operações mas verá toda a conta (não se aplica o filtro por filial). Recomendação: sempre atribuir filial ao cadastrar o corretor.

8.2 Você desceu do plano Business para Free/Plus

• Suas operações existentes não são excluídas, continuam no sistema.
• Você perde acesso aos relatórios de operações e ao modo Business.
• Você não pode criar operações novas (volta ao modo Básico, que só muda o estado do imóvel).
• Se você volta ao Business, recupera o acesso completo e todas as suas operações históricas.

8.3 Corretor de uma filial olha imóvel de outra

Isso é comum em redes com múltiplas filiais. O corretor:

• Pode ver o histórico de operações de qualquer imóvel da conta (leitura cross-branch).
• Não pode ver o detalhe de operações que não são da sua filial (em vez disso vê "🔒 Nome da outra filial").
• Não pode criar nem fechar operações sobre imóveis de outras filiais.

8.4 Migração de dados antigos sem tipo correto

Se você tem operações cadastradas antes de abril de 2026, o campo "tipo" pode estar como "Venda" mesmo que o imóvel seja de locação (era um bug). Há um script SQL que recalcula os tipos de operações antigas com base no tipo do imóvel. Se você precisa que seja aplicado na sua conta, entre em contato com o suporte.

8.5 Contatos broker (colegas imobiliários)

Quando você cria um contato novo a partir do CRM ou do modal de operação, há um seletor "Tipo de contato" com duas opções:

Casos de uso do tipo Broker:

• Uma imobiliária amiga que traz compradores para imóveis seus (cobrokerage).
• Um colega de outra conta Mapaprop com quem você compartilha operações de vez em quando.
• A contraparte vendedora numa operação manual: o imóvel é deles, você leva o comprador.

Como aparece no CRM: o tag "Broker" aparece automaticamente no filtro de etiquetas do CRM junto com os tags habituais (Locatário, Dono, Interessado, etc). Você pode filtrar todos os seus brokers rapidamente para ver com quem você tem relações ativas.

O tag Broker não substitui os demais. Se um broker também é comprador em alguma operação, ele pode ter ambas as etiquetas (a de Broker atribuída ao criar o contato, e a de Interessado atribuída ao vinculá-lo a um imóvel).

9. Perguntas frequentes

Por que não consigo ver o botão "Fechamento Business"? Seu plano não inclui Operações. Você precisa do Business (serviço 56) ou BusinessManager (serviço 57).

Por que um corretor não vê "Todas as operações" no menu? Por design. Os vendors veem só "Minhas Operações" (sua versão filtrada por sua filial e autoria). A listagem global é para admins.

Por que um indicador de margem me dá 0% ou sem dados? Cada indicador é calculado apenas com as operações que têm os preços que aquele indicador precisa, na mesma moeda: "Publicação para oferta" precisa de publicação + oferta; "Oferta para fechamento" precisa de oferta + fechamento; "Desconto final" precisa de publicação + fechamento. Se nenhuma operação do período tem esses dados (ou estão em moedas distintas), aquele indicador fica sem base. Carregue sempre os 3 preços na mesma moeda para que as operações contribuam para os três. O botão "Apenas dados completos" mostra unicamente essas operações completas.

Posso excluir uma operação cadastrada por engano? Não. Mude-a para o estado Caída com um comentário esclarecedor. As operações nunca são excluídas.

Marco um imóvel como Vendido sem o modo Business. Perco alguma coisa? Sim. A mudança fica no imóvel (estado e preço de fechamento) mas não gera operação rastreável: não aparece nos relatórios, não contribui para a margem, não há registro de comprador/vendedor. Para gestão real, use o modo Business.

Por que o tipo das minhas operações novas diz "Locação" quando crio a partir de um imóvel de locação? É o comportamento esperado: o tipo é derivado do tipo do imóvel. Antes de abril de 2026 todas nasciam como "Venda" (bug), agora é inferido corretamente.

Posso ver operações de imóveis que já apaguei? Sim. Na listagem global aparecem com um snapshot dos dados do imóvel e a nota "(excluída)".

Quando aparece o botão "Marcar como caída" automático? Quando você tenta mudar o estado de um imóvel reservado para Disponível ou Suspenso sem fechar a operação. O sistema detecta e oferece resolver com um clique.

Para que serve o tipo de contato "Broker"? Para distinguir seus colegas imobiliários dos seus clientes finais no CRM. Um broker é alguém com quem você co-trabalha, não um comprador ou proprietário. Ao marcá-lo como Broker ao criar o contato, é atribuída automaticamente a etiqueta "Broker" e ele aparece no filtro de etiquetas do CRM.

Posso criar uma operação se o imóvel não está na minha conta? Sim. É a operação manual (ver seção 7.10). Você a usa quando trabalha como ponta compradora sobre um imóvel de outra imobiliária ou que não está publicado no Mapaprop.

Por que aparece um alerta em um par de operações vinculadas? Em um co-brokering ou ponta-dupla, as duas operações deveriam fechar pelo mesmo preço (é o mesmo imóvel; o que difere por ponta é a comissão, não o preço de fechamento). Se as duas pontas fecharam com preços de fechamento distintos, ou ficaram em estados distintos (uma fechada e a outra caída), o sistema marca a operação com um ícone de alerta na listagem e no detalhe para que você revise.

Em um co-brokering, posso escolher um corretor de outro escritório da minha rede? Sim. Ao montar um co-brokering, o seletor de contraparte desce em cascata escritório → filial → corretor e permite escolher tanto um colega do seu próprio escritório quanto de qualquer outro escritório da sua rede no Mapaprop (redes tipo MLS fechada). Só são mostrados dados públicos do outro escritório (nome, filial, corretor), nunca suas informações privadas.

PARTE 2 — Referência Operacional (suporte / admins de conta)

Esta parte é pensada para suporte do Mapaprop, comercial, e admins de conta que precisam responder consultas de clientes com precisão: quem pode fazer o quê, o que cada plano exige, e como as telas se comportam conforme o perfil.

Para detalhes técnicos (vendor isolation interno, backfills SQL, edge cases com SQL, changelog de commits), ver:

• mapaprop-deals-flow.md — fluxo do código e casos-limite técnicos
• mapaprop-deals-changelog.md — histórico de mudanças por sprint
• mapaprop-deals-architecture.md — decisões de arquitetura

10. Perfis do sistema

O Mapaprop tem 4 perfis de acesso. A coluna "perfil do código" serve apenas para o suporte que precise ler logs ou o sistema interno.

Nesta doc, "admin" sem prefixo significa Admin Principal ou Gestor de Rede (ambos os perfis têm permissões de gestão sobre a conta). "Admin Mapaprop" é chamado explicitamente quando se aplica.

11. Matriz de permissões por ação

Regras-chave:

• O corretor só abre reservas. Não fecha nem cancela — essas decisões são tomadas pelo admin da conta.
• As operações nunca são excluídas (política firme — ver §7.2). Para "anular" usa-se o estado Caída.
• O corretor pode ler o histórico de qualquer filial mas não pode modificar deals fora da sua.

12. Permissões por tela

Hub /stats/deals

Os cards do hub são gateados por perfil:

Os cards aparecem visualmente para todos os planos (incluído o Free), mas ao clicar sem Business é disparado o modal de upgrade.

/deals (Todas as operações)

/deals/my-deals (Minhas Operações)

Para o corretor, ao usar "+ Adicionar operação", o branchId é atribuído automaticamente à sua filial e o estado inicial só pode ser Reservada.

/deals/[id] (Detalhe de uma operação)

Painel "Operações" na ficha de imóvel

O corretor lê o histórico de qualquer imóvel da conta, mas só modifica deals da sua filial.

Modal "Fechamento de Operação"

Quais entry points o abrem e quem os vê?

O que o modal mostra conforme plano e perfil?

Detalhes do comportamento do modal:

• Tags no header: o modal mostra o tipo de operação (Venda/Locação/etc.) e o tipo de imóvel (Apartamento/Casa/etc.) como chips, derivados do imóvel.
• "Oferta de reserva" + "Valor da reserva": ao fechar uma reserva existente, a seção Valores mostra estes 2 campos (com fundo âmbar) como referência.
• "Origem do Comprador": aparece dentro de Valores ao fechar uma operação. É opcional.
• "Fechar como X" abre direto em Valores: ao entrar a partir de um botão de fechamento, a seção Estado fica recolhida (a decisão já foi tomada) e abre-se diretamente Valores para confirmar o preço de fechamento.

Sub-relatórios do hub

my-deals e branch têm uma faixa de identificação no topo:

• my-deals: filial do corretor (logo ou ícone + nome + endereço + contato).
• branch: escritório / customer (logo + nome + dados).

13. Plano necessário

13.1 Sistema completo de Operações

Requer plano Business (serviço 56) ou BusinessManager (serviço 57).

Para Free / Plus / Pro+:

• O menu "Relatórios de Operações" é visível, mas ao clicar é disparado o modal de upgrade.
• O botão "Fechamento Business" no modal de operação é bloqueado com o modal de upgrade.
• O backend rejeita endpoints do módulo de deals.

13.2 Modo Básico do modal

Não requer plano — disponível para todos. É a única função do módulo de operações que é gratuita. Só muda o estado do imóvel (Reservada / Vendida / Alugada / Suspensa) e opcionalmente registra o preço de fechamento. Não gera deal rastreável, não contribui para os relatórios.

13.3 Por que a decisão

O sistema de Operações existe principalmente para gestão comercial profissional: medir performance, ranking, margem. Isso justifica o plano Business. Customers pequenos que só precisam marcar um imóvel como vendido têm o modo Básico.