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 a URL no cliente MCP: https://app.vember.com.br/api/mcp/{storeId} (a URL exata, já com o ID da loja, é exibida na tela de Conectores). A URL legada https://app.vember.com.br/api/mcp continua funcionando, mas a forma por loja é a recomendada — permite conectar várias lojas ao mesmo tempo.
  4. As permissões do token = permissões do membro que o criou; o token só funciona na URL da própria loja

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/{storeId} (stateless HTTP, JSON-RPC 2.0) — a URL da loja aparece em Loja → Conectores; POST /api/mcp (legado) segue aceito 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