API do Horos

Coloque leads do seu site, sistema ou automação direto no funil do Horos e receba um aviso no seu sistema sempre que um lead entra, muda de etapa, vira venda ou é arquivado.

• Endereço base: https://horos.sale/api/v1
• Formato: JSON em UTF-8, nos dois sentidos
• O lead entra no funil de quem é dono da chave. Se a chave for de um gestor com fila de distribuição, o lead passa pela fila igual aos leads do Meta Ads
• Telefone repetido não vira lead duplicado: a API devolve 409 se já existe um lead ativo com o número, e reativa o lead se ele estava arquivado

Chave de API

1. No Horos, abra Integrações → API e webhooks (ou o cartão Zapier / Make).
2. Clique em Criar chave. Escolha se ela vale só para você ou para a imobiliária toda (só a diretoria cria chave da imobiliária).
3. Copie a chave na hora: ela começa com hrs_ e aparece uma vez só. O Horos guarda só uma impressão dela.

Mande a chave em todo pedido, em um destes cabeçalhos:

Authorization: Bearer hrs_SUA_CHAVE
# ou
X-Api-Key: hrs_SUA_CHAVE

Respostas e erros

Deu certo: 200 (ou 201 ao criar). Deu errado: o corpo traz error.code e uma mensagem em português.

{ "error": { "code": "duplicate", "message": "Já existe um lead ativo com esse telefone (Maria Souza).", "lead_id": "API1A2B3C" } }

Rotas

Confere se a chave funciona e diz de quem ela é. É o teste de conexão do Zapier e do Make.

curl https://horos.sale/api/v1/me -H "Authorization: Bearer hrs_SUA_CHAVE"

{
  "key": { "name": "Site", "scope": "me", "kind": "api" },
  "user": { "id": "6f1c…", "name": "Ana Corretora" },
  "workspace": { "id": "2a9e…", "name": "Imobiliária Exemplo" }
}

Etapas do funil do dono da chave, na ordem do Kanban. Use o id (ou o nome) ao criar ou mover um lead.

{ "data": [ { "id": "inbox", "name": "Inbox" }, { "id": "contato1", "name": "1º Contato" }, { "id": "fechado", "name": "Fechado" } ] }

Lista os leads, do mais novo para o mais antigo. Só os ativos, a não ser que peça os arquivados.

curl "https://horos.sale/api/v1/leads?phone=11999998888" -H "Authorization: Bearer hrs_SUA_CHAVE"

Um lead pelo id. Devolve o objeto lead.

Cria um lead. Mande pelo menos name, phone ou email; o telefone precisa ter DDD.

curl -X POST https://horos.sale/api/v1/leads \
  -H "Authorization: Bearer hrs_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "phone": "(11) 99999-8888",
    "email": "maria@exemplo.com",
    "region": "Moema",
    "value": 650000,
    "temperature": "hot",
    "notes": "Quer 3 quartos perto do metrô",
    "utm": { "source": "site", "campaign": "lancamento-outubro" }
  }'

Respostas: 201 com o lead criado · 200 com "reactivated": true se o telefone era de um lead arquivado (ele volta para a etapa pedida) · 409 se já existe um lead ativo com esse telefone.

Altera só o que vier no corpo: stage, temperature, value, name, email, region, notes, custom_fields (soma aos que já existem).

curl -X PATCH https://horos.sale/api/v1/leads/API1A2B3C \
  -H "Authorization: Bearer hrs_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{ "stage": "fechado", "value": 640000 }'

O objeto lead

{
  "id": "API1A2B3C",
  "name": "Maria Souza",
  "phone": "11999998888",
  "email": "maria@exemplo.com",
  "region": "Moema",
  "value": 650000,
  "score": 42,
  "temperature": "hot",
  "stage": { "id": "contato1", "name": "1º Contato" },
  "archived": false,
  "origin": "api",
  "owner_id": "6f1c…",
  "utm": { "source": "site", "campaign": "lancamento-outubro" },
  "notes": "Quer 3 quartos perto do metrô",
  "custom_fields": null,
  "created_at": "2026-10-14T13:05:22Z",
  "updated_at": "2026-10-14T13:05:22Z",
  "closed_at": null,
  "url": "https://horos.sale/client?id=API1A2B3C"
}

value vem null quando o lead está arquivado. closed_at é a data da venda. url abre a ficha no Horos (precisa estar logado).

Webhooks

O Horos manda um POST em JSON para o endereço que você cadastrar sempre que acontece um evento. Cadastre em Integrações → API e webhooks → Novo webhook (o botão Testar manda um evento de exemplo) ou por API.

POST https://seu-sistema.com/horos
Content-Type: application/json
X-Horos-Event: lead.stage_changed
X-Horos-Signature: sha256=5f2b…

{
  "id": "18342",
  "event": "lead.stage_changed",
  "created_at": "2026-10-14T13:20:00Z",
  "data": {
    "lead": { …o objeto lead… },
    "previous_stage": { "id": "inbox", "name": "Inbox" }
  }
}

• Responda com qualquer status 2xx em até 10 segundos.
• Se falhar, o Horos tenta de novo depois de 1, 5, 15, 60 e 180 minutos.
• Depois de 50 falhas seguidas o webhook é desligado e você recebe um aviso no Horos (aparece também em Integrações → Situação das integrações).
• O mesmo evento pode chegar mais de uma vez: use o id para não processar duas vezes.

Eventos

Conferir a assinatura

Cada webhook tem um segredo (whsec_…, mostrado ao criar). O cabeçalho X-Horos-Signature é o HMAC-SHA256 do corpo exato do pedido com esse segredo. Confira antes de confiar no conteúdo:

import crypto from 'node:crypto';

// rawBody = o corpo exatamente como chegou (texto), antes de converter para JSON
function horosOk(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header && header.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

import hmac, hashlib

def horos_ok(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header or '', expected)

Assinar webhooks por API

É assim que o Zapier e o Make fazem sozinhos. Útil também para o seu sistema se cadastrar.

O endereço precisa ser https://. Se ele responder 410 Gone, o Horos apaga a assinatura sozinho.

Zapier e Make

1. Em Integrações, abra o cartão Zapier ou Make e crie uma chave.
2. No Zapier/Make, use o app de Webhooks (ou HTTP) apontando para as rotas acima, com o cabeçalho Authorization: Bearer hrs_….
3. Para receber eventos do Horos: crie um gatilho “Catch Hook” (Zapier) ou “Custom webhook” (Make), copie o endereço que ele gera e cadastre em Integrações → Novo webhook.
4. Para mandar leads ao Horos: use a ação “POST” para /v1/leads com os campos do formulário.

Formulário do seu site

Não chame a API direto do navegador (a chave ficaria exposta). Duas opções seguras:

• Sem programar: use o formulário pronto do Horos (no CRM, botão Compartilhar → Compartilhar formulário), ou mande o formulário para o Zapier/Make e de lá para a API.
• Com programação: o formulário envia para o seu servidor, e o servidor chama POST /v1/leads com a chave. Guarde o gclid da URL da página e mande junto para ligar as Conversões do Google Ads.

// No seu servidor (ex.: rota que recebe o formulário)
const r = await fetch('https://horos.sale/api/v1/leads', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.HOROS_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: form.nome, phone: form.telefone, email: form.email, origin: 'site', gclid: form.gclid }),
});
if (r.status === 409) { /* já é lead — tudo bem */ }

Dúvidas ou precisa de algo que a API ainda não faz? Fale com a gente.