Logo
Integrações e API

API para Incorporadoras

Documentação completa da API Vember para o segmento de Incorporação (DEVELOPER) — guia de integração para desenvolvedores e IAs externas

Leitura de ~13 min

API para Incorporadoras (Segmento DEVELOPER)

Esta página documenta toda a superfície pública da API Vember para empresas do segmento de Incorporação (construtoras, incorporadoras, loteadoras). É um guia voltado a desenvolvedores e a outras IAs que precisam gerar código para se integrar à plataforma.

Diferença crítica entre segmentos: DEVELOPER é Incorporadora (gerencia empreendimentos, unidades e tipologias) — não confundir com REAL_ESTATE (imobiliária que comercializa imóveis de terceiros). Toda esta documentação assume businessSegment = DEVELOPER.

Visão Geral da Plataforma

A Vember oferece três superfícies de API que podem ser combinadas:

| Superfície | Protocolo | Autenticação | Para que serve | | -------------------------- | -------------------- | ----------------------------- | ----------------------------------------------------------------------------- | | REST v1 | HTTP/JSON | Bearer API Key (vmb_live_*) | Captura de leads, CRUD de clientes, envio de mensagens WhatsApp | | MCP | HTTP/JSON-RPC (MCP) | Bearer MCP Token | Assistentes de IA (Claude.ai, ChatGPT) lendo dados da loja com permissão fina | | Forms Pública | HTTP/JSON | Sem auth (slug do form) | Captura de formulários públicos com unit_selector (empreendimento+unidade) | | Webhooks de Automação | HTTP (entrada) | Token de workflow | Disparar workflows da Vember a partir de sistemas externos |

Base URL de produção: https://app.vember.com.br

Modelo de dados central: tudo na Vember pertence a uma Store (loja). Uma Store contém: WhatsApps conectados, clientes, conversas, produtos (empreendimentos), unidades, tipologias, formulários, automações, dados financeiros (ERP) e contratos.

Como gerar credenciais

1. Chave da API REST v1

  1. Acessar Loja → API Pública no app
  2. Clicar em Nova chave de API
  3. Escolher a conexão WhatsApp vinculada
  4. (Opcional) Definir limite por minuto e validade
  5. Copiar e guardar a chave — ela só é mostrada uma única vez (formato vmb_live_…)

2. Token MCP (para IAs como Claude.ai)

  1. Acessar Loja → Conectores → Claude.ai Cowork
  2. Clicar em Gerar novo token
  3. Configurar URL no cliente MCP: https://app.vember.com.br/api/mcp
  4. As permissões do token = permissões do membro que o criou

3. Sem credencial (formulários públicos)

Formulários publicados como públicos podem ser submetidos por qualquer pessoa via POST /api/v1/forms/submit desde que o storeId + slug sejam válidos e o form esteja ativo.

Conceitos do Domínio de Incorporação

Para integrar corretamente, é preciso entender estes objetos:

| Conceito | Modelo Prisma | Descrição | | ------------------------- | --------------------- | -------------------------------------------------------------------------- | | Empreendimento | Product | Obra/condomínio. Contém terreno, registro de incorporação, totais, prazos | | Unidade | ProductUnit | Apartamento, lote, sala — identificada por bloco, andar, posição | | Tipologia | UnitTypology | Classificação reutilizável (dormitórios, banheiros, área, preço-base) | | Plano de Parcelamento | ErpInstallmentPlan | Plano de pagamento de uma venda (entrada, parcelas, índice de correção) | | Parcela | ErpCharge | Cobrança individual (vencimento, valor original, corrigido, multa, juros) | | Comissão | ErpCommission | Comissão de venda (corretora, percentual, etapas de pagamento) | | Orçamento de Obra | ErpBudget | Orçamento por empreendimento/fase (planejado × executado, BDI) | | Estudo de Viabilidade | ErpViabilityStudy | Indicadores: TIR, VPL, payback, VGV projetado | | Simulação | PaymentSimulation | Template de condição de pagamento (tranches, entrada, juros) | | Cliente | Customer | Único por telefone dentro da Store | | Lead | Customer + leadStatus | Cliente em fase de qualificação |

Status de unidade (UnitStatus): AVAILABLE, RESERVED, SOLD, BLOCKED, UNDER_CONTRACT.

API REST v1 — Endpoints

Todos os endpoints abaixo usam Base URL https://app.vember.com.br e exigem header de autenticação:

Authorization: Bearer vmb_live_SUA_CHAVE

ou

x-api-key: vmb_live_SUA_CHAVE

Todas as respostas seguem o padrão:

{ "success": true,  "data": { ... } }
{ "success": false, "error": { "code": "...", "message": "..." } }

E carregam headers de rate limit:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1715000000
Retry-After: 15        ← apenas em 429

Captura de Leads — ideal para sites e landing pages

POST /api/v1/leads

Body:

{
  "name": "Maria Silva",
  "phone": "51999887766",
  "email": "maria@exemplo.com",
  "customerTypeId": "ckxxxxx",
  "source": "site_institucional",
  "interestedProductId": "cl_empreendimento_id",
  "interestedUnitId": "cl_unidade_id",
  "tags": ["lead-quente", "stand-de-vendas"],
  "customFields": {
    "renda_aproximada": 12000,
    "tem_imovel_para_negociar": true
  },
  "adAttribution": {
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "lancamento-torre-norte",
    "gclid": "Cj0KCQ...",
    "referrer": "https://google.com/search?q=apartamento+porto+alegre"
  },
  "leadStatus": "NEW",
  "leadScore": 80,
  "consentMessageOptIn": true
}

Campos obrigatórios: apenas phone. Demais são opcionais.

Comportamento (upsert inteligente):

  • Se o telefone já existir na Store, atualiza apenas campos vazios e mescla tags.
  • Se não existir, cria o Customer e dispara o gatilho de automação NEW_CUSTOMER.
  • Para cada tag nova adicionada, dispara TAG_ADDED.

Resposta:

{
  "success": true,
  "data": {
    "customerId": "ckabc...",
    "isNew": true,
    "phone": "555199887766",
    "addedTags": ["lead-quente"]
  }
}

Códigos de erro específicos: INVALID_PHONE, INVALID_PRODUCT, INVALID_UNIT, INVALID_CUSTOMER_TYPE.

Clientes — CRUD completo

| Método | Endpoint | Função | | ------ | ------------------------------------------------ | ------------------------------------- | | POST | /api/v1/customers | Criar cliente (com customerTypeId) | | GET | /api/v1/customers | Listar (filtros + paginação cursor) | | GET | /api/v1/customers/{id} | Detalhe completo | | POST | /api/v1/customers/{id}/tags | Adicionar tag | | DELETE | /api/v1/customers/{id}/tags/{tag} | Remover tag | | POST | /api/v1/customers/{id}/notes | Anexar anotação datada | | POST | /api/v1/customers/{id}/pause-ai | Pausar IA (com motivo e resumeAt) | | POST | /api/v1/customers/{id}/block | Bloquear/desbloquear | | POST | /api/v1/customers/{id}/archive | Arquivar |

Filtros úteis em GET /api/v1/customers (querystring):

?search=maria
&leadStatus=QUALIFIED
&customerTypeId=ck...
&source=google_ads
&tags=lead-quente,stand
&createdFrom=2026-01-01
&createdTo=2026-05-18
&cursor=ckxxx
&limit=50

Tipos de cliente disponíveis na Store (para popular customerTypeId):

GET /api/v1/customer-types → retorna lista de { id, name, customerCount, hasPrompt }.

Envio de Mensagens WhatsApp

POST /api/v1/messages/send

{
  "name": "João Comprador",
  "number": "51999887766",
  "message": "Olá! Recebemos seu interesse no apto 1502 da Torre Norte. Posso agendar uma visita?"
}
  • Sai pelo WhatsApp da conexão vinculada à chave de API.
  • Cria automaticamente o Customer se não existir.
  • Aparece no chat como mensagem enviada manualmente.

Resposta:

{
  "success": true,
  "data": {
    "messageId": "msg_abc",
    "whapiMessageId": "wamid....",
    "conversationId": "conv_...",
    "customerId": "cust_...",
    "phone": "555199887766",
    "chatId": "555199887766@s.whatsapp.net",
    "sentAt": "2026-05-18T12:34:56.789Z"
  }
}

MCP — Acesso para IAs Assistentes

O MCP (Model Context Protocol) permite que assistentes como Claude.ai e ChatGPT Cowork consultem dados da Vember com permissões finas.

Endpoint: POST /api/mcp (stateless HTTP, JSON-RPC 2.0) Autenticação: Authorization: Bearer <token>

Tools específicos para Incorporadoras

Todos os tools abaixo dependem da permissão correspondente do membro que gerou o token.

Empreendimentos

| Tool | Permissão | Retorno | | -------------------------- | -------------------- | ------------------------------------------------------------------------- | | empreendimentos_list | products.view | Lista de produtos com contagem de unidades por status | | empreendimento_get | products.view | Detalhe completo: terreno, registros, prazos, totais, BDI, etc. | | empreendimento_kpis | erp.view_dashboard | KPIs financeiros: VGV, recebível, executado, inadimplência |

Unidades

| Tool | Permissão | Retorno | | ----------------- | --------------- | ------------------------------------------------------------- | | unidades_list | products.view | Lista filtrável (productId, status, typologyId, search) | | unidade_get | products.view | Detalhe: bloco, andar, área privativa/total, preço, status | | tipologias_list | products.view | Tipologias do empreendimento (3 dorm, 2 dorm, etc.) |

Simulações de Pagamento

| Tool | Permissão | Retorno | | ----------------- | ---------- | ------------------------------------------------------ | | simulacoes_list | erp.view | Templates de condição (entrada, parcelas, juros) | | simulacao_get | erp.view | Tranches, totais, validade |

Relatórios Financeiros

| Tool | Permissão | Retorno | | -------------------------- | -------------------- | ---------------------------------------- | | portfolio_dashboard | erp.view_dashboard | Visão geral da carteira | | empreendimento_dashboard | erp.view_dashboard | Painel por empreendimento | | relatorio_dre | erp.view_reports | DRE por empreendimento | | relatorio_aging | erp.view_reports | Aging de parcelas em atraso | | relatorio_vgv | erp.view_reports | VGV (Valor Geral de Vendas) |

Exemplo de chamada MCP (JSON-RPC)

curl -X POST https://app.vember.com.br/api/mcp \
  -H "Authorization: Bearer mcp_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "unidades_list",
      "arguments": {
        "productId": "ckxxxxx",
        "status": "AVAILABLE",
        "limit": 50
      }
    }
  }'

Formulários Públicos com Selector de Unidades

Incorporadoras podem publicar formulários públicos que listam dinamicamente empreendimentos e unidades disponíveis — ideal para "reserva online", "manifestação de interesse" e "agendamento de visita".

Listar empreendimentos e unidades para o formulário

GET /api/forms/units

Querystring:

?formId=ckxxxxx           ← obrigatório (valida acesso ao form)
&productId=ckxxxxx        ← opcional (filtra unidades de 1 empreendimento)
&status=AVAILABLE         ← opcional (AVAILABLE | RESERVED | SOLD | BLOCKED | UNDER_CONTRACT)

Sem productId, retorna lista de empreendimentos com contagem de unidades. Com productId, retorna as unidades daquele empreendimento.

Upload de arquivos do formulário

POST /api/forms/upload (multipart/form-data, max 10 MB)

Aceita: imagens, PDFs, áudio, vídeo. Retorna { url, mimeType, size }.

Submeter o formulário

Submissão de formulários públicos é feita via Server Action interno (submitStoreForm) — para integração externa, o caminho recomendado é:

  1. Renderizar o form usando getPublicForm(storeId, slug)
  2. Enviar a submissão por POST para a URL pública do form na Vember

Toda submissão dispara o trigger de automação FORM_SUBMITTED com o payload completo dos campos preenchidos, incluindo interestedUnitId quando o campo unit_selector é usado.

Automações: integrar via Webhook

Workflows ativos na Vember podem ser disparados por POST externo quando configurados com o trigger WEBHOOK. Cada workflow gera um token único:

POST https://app.vember.com.br/api/automations/webhook/{workflowToken}
Content-Type: application/json

{
  "anyField": "any value",
  "customerPhone": "51999887766",
  "interestedUnitId": "ck..."
}

O payload inteiro é injetado em {{ trigger.* }} dentro dos nós do workflow. Use isso para: importar leads de plataformas terceiras, sincronizar status de venda com ERP externo, gatilhar ações pós-pagamento, etc.

Sistema de Expressões (para nós de Workflow)

Quando construindo workflows que combinam dados da Vember com sistemas externos, é possível usar expressões {{ }} em qualquer campo de configuração de nó:

{{ trigger.customerPhone }}                  ← campo da entrada
{{ nodes.findCustomer.customerId }}          ← output de nó anterior
{{ trigger.adAttribution.utmCampaign | upper }}  ← com pipe de transformação
{{ formatCurrency(nodes.unit.price) }}       ← função built-in
{{ trigger.area > 100 ? 'grande' : 'compacto' }} ← ternário

Funções disponíveis (60+): upper, lower, trim, replace, formatCurrency, formatPhone, formatDate, addDays, round, min, max, first, last, join, unique, sort, toJSON, fromJSON, etc.

Profundidade máxima de 64 níveis. Sem eval() — interpretação de AST puro e seguro.

Conectores nativos (sem precisar codificar)

Em vez de chamar APIs externas a partir do seu código, você pode usar os conectores integrados da Vember dentro de workflows:

| Conector | Categoria | Ações disponíveis (resumo) | | ----------------------- | --------------- | --------------------------------------------------------- | | Microsoft 365 | Produtividade | SharePoint, Teams, Outlook, Excel, OneDrive, Calendar | | DocuSign | Assinatura | Enviar contrato, consultar status, cancelar | | Mercado Livre | E-commerce | Itens, pedidos, perguntas, mensagens | | Facebook Marketplace | E-commerce | Catálogos, produtos, pedidos |

Tokens OAuth são armazenados criptografados (AES-256-GCM) e renovados automaticamente.

Códigos de Erro (REST v1)

| HTTP | Code | Significado | | ---- | ------------------------- | -------------------------------------------------------- | | 401 | UNAUTHORIZED | API Key ausente, inválida ou revogada | | 422 | VALIDATION_ERROR | Body inválido (ver error.details para campos) | | 422 | INVALID_PHONE | Telefone fora do padrão brasileiro | | 422 | INVALID_PRODUCT | interestedProductId não pertence à Store | | 422 | INVALID_UNIT | interestedUnitId não pertence à Store | | 422 | INVALID_CUSTOMER_TYPE | customerTypeId inexistente | | 422 | INACTIVE_CUSTOMER_TYPE | customerTypeId desativado | | 404 | NOT_FOUND | Cliente/recurso inexistente | | 429 | RATE_LIMITED | Cota de requests/minuto excedida (ver Retry-After) | | 500 | INTERNAL_ERROR | Erro interno (reportar com requestId) |

Boas Práticas para Integrações

  1. Sempre normalizar telefone para o formato Whapi: 12 dígitos 55 + DDD + número. A Vember normaliza, mas enviar já formatado evita erros.
  2. Usar customerTypeId na captura: assim a IA já responde com o prompt personalizado daquele tipo (Ex.: "Lead Quente — Empreendimento Torre Norte").
  3. Enviar adAttribution sempre que disponível: a Vember vincula a campanha do Meta Ads/Google Ads ao cliente, permitindo relatórios de ROI.
  4. Tratar 429 com backoff: usar Retry-After (segundos). Recomendado: backoff exponencial com jitter.
  5. Idempotência: como POST /api/v1/leads faz upsert por telefone, é seguro reenviar a mesma requisição (apenas mescla tags).
  6. Não confiar no app para criar Customer: prefira sempre criar via API antes de enviar mensagem — assim o cliente já entra com o customerType correto.
  7. Para incorporadoras com múltiplas torres/empreendimentos: usar 1 chave de API por canal de marketing (site, stand físico, parceiros) ajuda a separar métricas.

Receitas Práticas

Captura de lead com interesse em unidade específica (cURL)

curl -X POST https://app.vember.com.br/api/v1/leads \
  -H "Authorization: Bearer vmb_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Compradora",
    "phone": "51999887766",
    "email": "maria@email.com",
    "interestedProductId": "ck_empreendimento_torre_norte",
    "interestedUnitId": "ck_unidade_apto_1502",
    "source": "landing_page",
    "tags": ["torre-norte", "interesse-cobertura"],
    "adAttribution": {
      "utmSource": "google",
      "utmCampaign": "lancamento-torre-norte-q2-2026",
      "gclid": "Cj0KCQ..."
    },
    "consentMessageOptIn": true
  }'

Listar unidades disponíveis em um empreendimento (Node.js via MCP)

const res = await fetch('https://app.vember.com.br/api/mcp', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mcp_token_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'unidades_list',
      arguments: {
        productId: 'ck_empreendimento_id',
        status: 'AVAILABLE',
        limit: 50,
      },
    },
  }),
});
const { result } = await res.json();
console.log(result.content); // lista de unidades

Enviar mensagem após preencher form do site (Python)

import requests

requests.post(
    "https://app.vember.com.br/api/v1/messages/send",
    headers={
        "Authorization": "Bearer vmb_live_SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "name": "João Cliente",
        "number": "51999887766",
        "message": (
            "Olá, João! 👋 Recebemos seu interesse no apto 1502 da Torre Norte. "
            "Já encaminhei seu cadastro para um consultor — em alguns minutos "
            "alguém te chama por aqui mesmo. Qualquer dúvida, manda mensagem!"
        ),
    },
    timeout=15,
)

Buscar KPIs financeiros de um empreendimento (PHP via MCP)

$ch = curl_init('https://app.vember.com.br/api/mcp');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer mcp_token_xxx',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'jsonrpc' => '2.0',
    'id'      => 1,
    'method'  => 'tools/call',
    'params'  => [
        'name'      => 'empreendimento_kpis',
        'arguments' => ['empreendimentoId' => 'ck_id_aqui'],
    ],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Glossário rápido para IAs externas

  • VGV: Valor Geral de Vendas — soma do preço de todas as unidades de um empreendimento.
  • BDI: Benefícios e Despesas Indiretas — percentual aplicado sobre custos diretos.
  • TIR: Taxa Interna de Retorno do investimento no empreendimento.
  • VPL: Valor Presente Líquido descontado à taxa de atratividade.
  • Tipologia: classificação de unidade reutilizável (ex.: "2 dormitórios, 65 m²").
  • Distrato: rescisão do contrato de compra. Cancela ErpInstallmentPlan e devolve a unidade ao status AVAILABLE.
  • VToken: unidade interna de cobrança = R$ 0,01. Usado para medir consumo de IA, voz e dossiê — não é cobrado em chamadas REST/MCP.

Limites e Restrições

  • Tamanho máximo de mensagem: 4096 caracteres
  • Upload de arquivo (forms): 10 MB
  • Rate limit padrão: 60 req/min por chave (configurável no app)
  • Paginação cursor (limit): máximo 100 itens por página
  • Workflows simultâneos por Store: 10
  • Timeout por nó de workflow: 30 s
  • Timeout total de workflow: 5 min

Suporte & Atualizações

  • Status e novidades da API: página Novidades dentro do app (/patchnotes)
  • Reportar bugs: e-mail de suporte da sua Store
  • Versionamento: a versão atual é v1. Mudanças que quebrem contrato só ocorrem em uma futura v2, mantida em paralelo.
AnteriorAPI Pública