Integre o Sparta CRM às suas ferramentas

Introdução

A API do Sparta CRM é REST: você faz requisições HTTPS e recebe JSON em UTF-8. Cada chave de API pertence a uma imobiliária (ou corretor autônomo) e só enxerga os dados dessa conta.

Primeiros passos

1. Entre no CRM como administrador, abra Integrações › Chaves de API e crie uma chave. Ela começa com sbc_ e só aparece uma vez: guarde em local seguro.
2. Teste a conexão consultando os dados da sua conta:

curl https://app.spartabrokercrm.com.br/api/v1/conta \
  -H "Authorization: Bearer sbc_SUA_CHAVE"

{
  "dados": {
    "id": 42,
    "nome": "Imobiliária Exemplo",
    "chave": { "nome": "Meu site", "prefixo": "sbc_8fK2mQ1x", "escopo": "completo" }
  }
}

3. Envie seu primeiro lead com POST /leads. Ele aparece em Clientes e na primeira etapa do funil.

Autenticação

Envie a chave em todas as requisições, no cabeçalho Authorization:

Authorization: Bearer sbc_SUA_CHAVE

Também é aceito o cabeçalho X-Api-Key: sbc_SUA_CHAVE. Somente no endpoint de leads a chave pode ir na própria URL (?token=sbc_...), para ferramentas que não permitem configurar cabeçalhos.

Tipos de chave

Respostas e erros

Respostas de sucesso trazem o conteúdo em dados. Listas trazem também meta com a paginação. Datas são enviadas em UTC no formato ISO 8601 (2026-10-01T15:30:00Z).

Em caso de erro, a resposta traz um objeto erro com um codigo estável (para o seu sistema tratar) e uma mensagem em português. Erros de validação listam os problemas por campo:

{
  "erro": {
    "codigo": "dados_invalidos",
    "mensagem": "Alguns campos estão inválidos.",
    "campos": {
      "telefone": ["Informe um telefone brasileiro válido com DDD."]
    }
  }
}

Paginação e sincronização

Todas as listas são paginadas e aceitam estes parâmetros na URL:

"meta": { "pagina": 1, "por_pagina": 25, "total": 312, "ultima_pagina": 13 }

Sincronização incremental

Para manter outro sistema atualizado sem baixar tudo de novo: guarde o atualizado_em do último registro recebido e, na próxima execução, chame a lista com atualizado_desde igual a esse valor, percorrendo as páginas até a última. Sem esse filtro, as listas vêm do mais recente para o mais antigo.

Limites de uso

Cada conta pode fazer até 120 requisições por minuto, somando todas as chaves. As respostas trazem os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining. Ao passar do limite você recebe 429 com Retry-After (em segundos).

No envio de leads em lote, cada requisição aceita até 50 leads.

Leads

O jeito mais simples de colocar contatos no CRM. O lead vira um cliente da categoria Lead com status novo e entra na primeira etapa do funil.

Sem duplicados: se já existe um cliente com o mesmo telefone ou e-mail, o Sparta não cria outro. Ele registra o novo contato no histórico do cliente e responde com "duplicado": true.

Aceita JSON (Content-Type: application/json) ou formulário comum (application/x-www-form-urlencoded). Envie nome e pelo menos telefone ou e-mail.

Qualquer campo também pode ir na URL, por exemplo ?origem=Site, útil quando a ferramenta não deixa personalizar o corpo.

curl -X POST https://app.spartabrokercrm.com.br/api/v1/leads \
  -H "Authorization: Bearer sbc_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Souza",
    "telefone": "(41) 99999-0000",
    "email": "maria@exemplo.com",
    "origem": "Site",
    "mensagem": "Quero agendar uma visita",
    "imovel_id": 12
  }'

// Node.js 18+ (no servidor)
const resposta = await fetch('https://app.spartabrokercrm.com.br/api/v1/leads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.SPARTA_CHAVE,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    nome: 'Maria Souza',
    telefone: '(41) 99999-0000',
    email: 'maria@exemplo.com',
    origem: 'Site',
    mensagem: 'Quero agendar uma visita',
  }),
});
const { dados } = await resposta.json();
console.log(dados.cliente.id, dados.duplicado);

<?php
$ch = curl_init('https://app.spartabrokercrm.com.br/api/v1/leads');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SPARTA_CHAVE'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'nome' => 'Maria Souza',
        'telefone' => '(41) 99999-0000',
        'email' => 'maria@exemplo.com',
        'origem' => 'Site',
    ]),
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 201 novo, 200 duplicado, 422 inválido

{
  "dados": {
    "cliente": {
      "id": 1587,
      "nome": "Maria Souza",
      "telefone": "41999990000",
      "email": "maria@exemplo.com",
      "categoria": "Lead",
      "origem": "Site",
      "status": "novo",
      "...": "demais campos do cliente"
    },
    "duplicado": false,
    "card_id": 932
  }
}

Vários leads de uma vez

Envie um objeto com a lista em leads (até 50). Este também é o formato que o RD Station envia. A resposta traz um item por lead, na mesma ordem; os que tiverem problema vêm com erro e não impedem os demais.

{
  "origem": "Facebook",
  "leads": [
    { "nome": "Ana Lima", "telefone": "41988887777" },
    { "nome": "Bruno Reis", "email": "bruno@exemplo.com" }
  ]
}

Clientes

Todos os contatos da imobiliária: leads, compradores, vendedores, locatários e investidores.

O objeto cliente

Filtros: busca (nome, e-mail ou telefone), telefone, email, status, origem, categoria, responsavel_id, além dos parâmetros de paginação.

curl "https://app.spartabrokercrm.com.br/api/v1/clientes?status=novo&por_pagina=50" \
  -H "Authorization: Bearer sbc_SUA_CHAVE"

Campos: nome (obrigatório), telefone, email, cpf, categoria, origem, status (padrão novo), historico, cidade, uf, responsavel_id, imovel_id. Para leads de formulários e anúncios prefira POST /leads, que evita duplicados e já coloca no funil.

curl -X PATCH https://app.spartabrokercrm.com.br/api/v1/clientes/1587 \
  -H "Authorization: Bearer sbc_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "status": "qualificado", "responsavel_id": 7 }'

Imóveis

Somente leitura. Útil para exibir os imóveis no site da imobiliária ou enviar para outros sistemas. Faça a consulta pelo seu servidor, nunca pelo navegador, para não expor a chave.

Filtros: busca (nome, bairro ou endereço), cidade, bairro, uf, tipo_imovel, finalidade, tipo_transacao, construtora_id.

{
  "dados": {
    "id": 12,
    "nome": "Residencial Jardim Botânico, apto 3 quartos",
    "preco": 685000.00,
    "finalidade": "Residencial",
    "tipo_transacao": "Venda",
    "tipo_imovel": "Apartamento",
    "endereco": { "logradouro": "Rua Exemplo", "numero": "100", "bairro": "Jardim Botânico", "cidade": "Curitiba", "uf": "PR", "cep": "80210-000", "pais": "Brasil" },
    "construtora": { "id": 3, "nome": "Construtora Exemplo" },
    "foto_capa": "https://app.spartabrokercrm.com.br/img/foto-1.jpg",
    "descricao": "…",
    "video_url": null,
    "fotos": ["https://app.spartabrokercrm.com.br/img/foto-1.jpg"],
    "criado_em": "2026-09-02T13:10:00Z",
    "atualizado_em": "2026-09-30T18:42:11Z"
  }
}

Na lista, cada imóvel vem sem descricao, video_url e fotos (só com foto_capa). preco é numérico, em reais, ou null quando não informado.

Propostas

Somente leitura. Propostas de imóveis na planta e prontos.

Filtros: status (ativa, aceita, recusada), tipo (na_planta, pronto), cliente_id, imovel_id.

Funil de vendas

O funil (kanban) tem etapas personalizadas por imobiliária. Cada cliente no funil é um card.

{
  "dados": [
    { "id": 1, "nome": "Novo contato", "tipo": "normal", "cor": "#1976d2", "ordem": 1 },
    { "id": 2, "nome": "Análise de crédito", "tipo": "credito", "cor": "#f59e0b", "ordem": 2 },
    { "id": 3, "nome": "Venda concluída", "tipo": "final", "cor": "#16a34a", "ordem": 3 }
  ]
}

Filtros: etapa_id, cliente_id, status_credito. Cada card traz cliente, etapa, status_credito, motivo_reprovacao, valor_proposta, imovel_id, responsavel e observacoes.

Campos: cliente_id (obrigatório), etapa_id (padrão: primeira etapa), valor_proposta, observacoes, imovel_id, responsavel_id. Cada cliente pode ter um card só.

Campos: etapa_id, status_credito (pendente, aprovado, reprovado), motivo_reprovacao (obrigatório ao reprovar), valor_proposta, observacoes.

curl -X PATCH https://app.spartabrokercrm.com.br/api/v1/funil/cards/932 \
  -H "Authorization: Bearer sbc_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "status_credito": "aprovado", "etapa_id": 3 }'

Comissões

Somente leitura. Exige uma chave do tipo Acesso completo + financeiro. Cada comissão traz as parcelas a receber e o rateio entre corretores.

Filtros: status (um ou vários separados por vírgula: prevista, aprovada, parcial, recebida, cancelada, estornada), cliente_id, corretor_id, fechamento_desde, fechamento_ate, além de atualizado_desde e criado_desde.

{
  "dados": {
    "id": 41,
    "status": "parcial",
    "descricao": "Residencial Aurora — apto 1203",
    "tipo_negocio": "venda_planta",
    "valor_negocio": 500000.00,
    "percentual": 6.0,
    "valor_bruto": 30000.00,
    "data_fechamento": "2026-09-20",
    "pagador": { "tipo": "construtora", "nome": "Construtora XYZ" },
    "regra_repasse": "apos_recebimento",
    "cliente": { "id": 812, "nome": "Maria Souza" },
    "parcelas": [
      { "id": 90, "numero": 1, "valor": 10000.00, "vencimento": "2026-10-20", "status": "recebida", "recebido_em": "2026-10-18", "valor_recebido": 10000.00 },
      { "id": 91, "numero": 2, "valor": 20000.00, "vencimento": "2026-11-20", "status": "aberta", "recebido_em": null, "valor_recebido": null }
    ],
    "rateio": [
      { "id": 120, "papel": "vendedor", "beneficiario": "João Lima", "corretor_id": 7, "percentual": 40.0, "valor": 12000.00, "valor_liberado": 4000.00, "valor_pago": 0.00, "status": "liberado" },
      { "id": 121, "papel": "imobiliaria", "beneficiario": "Imobiliária", "corretor_id": null, "percentual": 60.0, "valor": 18000.00, "valor_liberado": 6000.00, "valor_pago": 0.00, "status": "receita" }
    ]
  }
}

Webhooks

Webhooks avisam o seu sistema na hora em que algo acontece no CRM, sem você precisar ficar consultando a API. Cadastre a URL que vai receber os avisos em Integrações › Webhooks e escolha os eventos.

Eventos

Um lead novo gera dois eventos: lead.recebido e cliente.criado (e funil.card_criado, se entrar no funil). Assine só os que você usa.

Formato do envio

O Sparta faz um POST com JSON para a sua URL:

{
  "id": "5f0c1c8e-3a2b-4f7e-9d21-7b8c2a0e4d11",
  "evento": "funil.etapa_alterada",
  "conta_id": 42,
  "criado_em": "2026-10-01T18:20:05Z",
  "dados": {
    "id": 932,
    "cliente": { "id": 1587, "nome": "Maria Souza" },
    "etapa": { "id": 3, "nome": "Proposta", "tipo": "normal", "cor": "#7c3aed", "ordem": 3 },
    "etapa_anterior": { "id": 2, "nome": "Visita", "tipo": "normal", "cor": "#0ea5e9", "ordem": 2 },
    "valor_proposta": 685000,
    "...": "demais campos do card"
  }
}

Entrega

• Responda com qualquer status 2xx em até 5 segundos. Se precisar processar algo demorado, responda primeiro e processe depois.
• Cada evento é enviado uma vez, sem novas tentativas automáticas. O resultado do último envio aparece em Integrações › Webhooks. Para sincronizar o que tiver perdido, use atualizado_desde na API.
• Depois de 20 falhas seguidas o webhook é desativado. Corrija o destino e reative na mesma tela.
• O botão Enviar teste manda um evento webhook.teste para conferir a configuração.
• A URL precisa ser pública e usar as portas 80, 443, 8080 ou 8443. Endereços de rede interna são recusados.

Validar a assinatura

Cada webhook tem um segredo (começa com whsec_), visível em Integrações › Webhooks. A assinatura é um HMAC-SHA256, em hexadecimal, de timestamp + "." + corpo, usando o corpo bruto exatamente como recebido. Confira a assinatura e recuse envios com mais de 5 minutos para evitar reenvios forjados.

const crypto = require('crypto');

// corpoBruto: o corpo como texto, antes de qualquer JSON.parse
function assinaturaValida(corpoBruto, cabecalho, segredo) {
  const partes = Object.fromEntries((cabecalho || '').split(',').map(p => p.split('=')));
  const esperado = Buffer.from(
    crypto.createHmac('sha256', segredo).update(partes.t + '.' + corpoBruto).digest('hex')
  );
  const recebido = Buffer.from(partes.v1 || '');
  const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
  return recente && recebido.length === esperado.length && crypto.timingSafeEqual(recebido, esperado);
}

// Express
app.post('/webhooks/sparta', express.raw({ type: 'application/json' }), (req, res) => {
  if (!assinaturaValida(req.body.toString(), req.get('X-Sparta-Assinatura'), process.env.SPARTA_WEBHOOK_SEGREDO)) {
    return res.sendStatus(401);
  }
  const evento = JSON.parse(req.body);
  res.sendStatus(200);
  // processe evento.evento / evento.dados aqui
});

<?php
$corpo = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SPARTA_ASSINATURA'] ?? ''), $partes);

$timestamp = (int) ($partes['t'] ?? 0);
$esperado = hash_hmac('sha256', $timestamp . '.' . $corpo, getenv('SPARTA_WEBHOOK_SEGREDO'));

if (!hash_equals($esperado, $partes['v1'] ?? '') || abs(time() - $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$evento = json_decode($corpo, true);
http_response_code(200);
// processe $evento['evento'] e $evento['dados'] aqui

Formulário do seu site

Para que o formulário de contato do site mande os leads direto para o funil:

1. Em Integrações › Chaves de API, crie uma chave do tipo Somente receber leads. Como ela só envia leads, pode ficar no código da página.
2. Cole o exemplo abaixo no site, trocando SUA_CHAVE_DE_LEADS pela chave criada. Os nomes dos campos do formulário (nome, telefone, email, mensagem) são os do endpoint de leads.
3. Envie um teste e confira em Clientes.

<form id="contato-sparta">
  <input name="nome" placeholder="Seu nome" required>
  <input name="telefone" placeholder="WhatsApp com DDD" required>
  <input name="email" type="email" placeholder="E-mail">
  <textarea name="mensagem" placeholder="Como podemos ajudar?"></textarea>
  <button type="submit">Quero ser atendido</button>
</form>

<script>
  document.getElementById('contato-sparta').addEventListener('submit', async (e) => {
    e.preventDefault();
    const dados = Object.fromEntries(new FormData(e.target));
    const url = 'https://app.spartabrokercrm.com.br/api/v1/leads?origem=Site&token=SUA_CHAVE_DE_LEADS';
    const r = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(dados),
    });
    alert(r.ok ? 'Recebemos seu contato! Em breve falaremos com você.' : 'Não foi possível enviar. Tente novamente.');
    if (r.ok) e.target.reset();
  });
</script>

Usa WordPress (Contact Form 7, Elementor, RD) ou outra plataforma de formulários? Configure o envio por webhook da própria ferramenta para a URL https://app.spartabrokercrm.com.br/api/v1/leads?origem=Site&token=SUA_CHAVE_DE_LEADS.

Facebook e Instagram Lead Ads

Os formulários de anúncio do Facebook e do Instagram são conectados por uma ferramenta de automação. Exemplo com o Zapier (no Make e no n8n os passos são equivalentes):

1. Crie uma chave Somente receber leads no Sparta.
2. No Zapier, crie um Zap com o gatilho Facebook Lead Ads › New Lead e escolha a página e o formulário do anúncio.
3. Adicione a ação Webhooks by Zapier › POST. Em URL, use https://app.spartabrokercrm.com.br/api/v1/leads?origem=Facebook&token=SUA_CHAVE (troque para origem=Instagram se o anúncio for do Instagram). Em Payload Type, escolha json.
4. Em Data, ligue os campos: nome → nome completo, telefone → telefone, email → e-mail e campanha → nome do formulário ou do anúncio.
5. Teste o Zap e ative. Cada novo lead do anúncio cai no funil em segundos.

No Make: módulo Facebook Lead Ads › Watch Leads seguido de HTTP › Make a request (método POST, corpo JSON). No n8n: Facebook Lead Ads Trigger seguido de HTTP Request.

RD Station Marketing

1. Crie uma chave Somente receber leads no Sparta.
2. No RD Station Marketing, abra a área de Integrações e crie um Webhook.
3. Em URL, informe https://app.spartabrokercrm.com.br/api/v1/leads?origem=Site&token=SUA_CHAVE e escolha o gatilho de conversão (ou de oportunidade, se só quiser leads qualificados).
4. Salve e faça uma conversão de teste numa landing page do RD.

O formato do RD Station (lista em leads, com name, email, mobile_phone e personal_phone) é reconhecido automaticamente.

Portais imobiliários (ZAP, VivaReal e OLX)

Os portais do Grupo OLX podem enviar os contatos dos seus anúncios para uma URL. Para receber esses leads no Sparta:

1. Crie uma chave Somente receber leads no Sparta.
2. No Canal Pro, procure a integração de leads por URL e informe https://app.spartabrokercrm.com.br/api/v1/leads?origem=Portal%20imobili%C3%A1rio&token=SUA_CHAVE. Se não encontrar a opção, peça ao atendimento do Canal Pro a "integração de leads" informando essa URL.
3. Faça um contato de teste em um dos seus anúncios.

Os campos enviados pelos portais (name, email, ddd, phone, message, clientListingId, leadOrigin) são reconhecidos. O código do anúncio fica salvo no histórico do cliente. Outros portais que enviem leads por URL funcionam da mesma forma.

Zapier, Make e n8n

Além de receber leads, as ferramentas de automação podem reagir ao que acontece no CRM e consultar dados.

Quando algo acontecer no Sparta, fazer algo em outra ferramenta

1. Na ferramenta, crie um gatilho do tipo webhook: Webhooks by Zapier › Catch Hook, Webhooks › Custom webhook no Make ou o nó Webhook no n8n. Copie a URL gerada.
2. No Sparta, em Integrações › Webhooks, cole a URL e marque os eventos, por exemplo funil.etapa_alterada.
3. Clique em Enviar teste para a ferramenta reconhecer o formato e monte as ações: avisar a equipe no WhatsApp ou no Slack, preencher uma planilha, enviar e-mail…

Consultar ou alterar dados do Sparta

Crie uma chave de acesso completo e use a ação de requisição HTTP da ferramenta (Webhooks by Zapier › Custom Request, HTTP › Make a request ou HTTP Request no n8n) com o cabeçalho Authorization: Bearer sbc_SUA_CHAVE e os endpoints desta página.

Suporte

Precisa de ajuda para integrar, ou de uma integração que não está aqui? Fale com a gente pelo WhatsApp (41) 99781-8917.

Quando novos campos ou eventos forem adicionados, eles aparecerão nas respostas sem quebrar o que já funciona. Mudanças incompatíveis, se houver, virão numa nova versão (/api/v2).