Comece Aqui

Quickstart

Faça sua primeira chamada à Keyspot Partner API em 5 minutos. Obtenha credenciais, gere um token e consulte imóveis.

Pré-requisitos

Antes de começar, você precisa de:

Um par de credenciais (API Key + API Secret) solicitado via chamado no CRM
Uma ferramenta para fazer requisições HTTP (curl, Postman, ou sua linguagem preferida)

Ainda não tem credenciais? A API Key e o API Secret precisam ser solicitados via chamado no CRM por um usuário administrador. O link para abrir o chamado é: https://crm.keyspot.com.br/support/tickets.

Teste rápido com Sandbox

Você pode começar a testar imediatamente usando o ambiente de sandbox, sem necessidade de solicitar credenciais. O sandbox vem pré-configurado com dados fictícios prontos para uso.

Use as credenciais abaixo em todas as chamadas deste quickstart:

X-API-Key:    ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u
X-API-Secret: ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd

Ambiente	URL Base
Sandbox	`https://sandbox-partner-api.keyspot.com.br`
Produção	`https://partner-api.keyspot.com.br`

As credenciais acima funcionam exclusivamente no ambiente sandbox e serão recusadas em produção. Para produção, solicite suas credenciais via chamado no CRM.

Sua primeira chamada em 5 minutos

Verifique se a API está online

Faça uma chamada ao endpoint de health check (não requer autenticação):

curl https://sandbox-partner-api.keyspot.com.br/health

const response = await fetch("https://sandbox-partner-api.keyspot.com.br/health");
const data = await response.json();
console.log(data);
// { "status": "ok", "timestamp": "2026-03-13T10:00:00.000Z" }

Gere um token de acesso

Envie suas credenciais via headers X-API-Key e X-API-Secret:

curl -X POST https://sandbox-partner-api.keyspot.com.br/v1/auth/token \
  -H "X-API-Key: ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u" \
  -H "X-API-Secret: ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd"

const response = await fetch("https://sandbox-partner-api.keyspot.com.br/v1/auth/token", {
  method: "POST",
  headers: {
    "X-API-Key": "ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u",
    "X-API-Secret": "ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd",
  },
});

const { data } = await response.json();
const token = data.token;
console.log(`Token: ${token}`);
console.log(`Expira em: ${data.expiresIn}s`);

import requests

response = requests.post(
    "https://sandbox-partner-api.keyspot.com.br/v1/auth/token",
    headers={
        "X-API-Key": "ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u",
        "X-API-Secret": "ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd",
    },
)

data = response.json()["data"]
token = data["token"]
print(f"Token: {token}")
print(f"Expira em: {data['expiresIn']}s")

A resposta contém o token JWT válido por 1 hora:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

Liste imóveis disponíveis

Use o token no header Authorization e especifique os campos desejados:

curl https://sandbox-partner-api.keyspot.com.br/v1/properties\?fields\=code,title,status,operationType,pricing\&limit\=5 \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

const response = await fetch(
  "https://sandbox-partner-api.keyspot.com.br/v1/properties?fields=code,title,status,operationType,pricing&limit=5",
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Total de imóveis: ${meta.total}`);
data.forEach((p) => console.log(`${p.code} - ${p.title} (${p.status})`));

import requests

response = requests.get(
    "https://sandbox-partner-api.keyspot.com.br/v1/properties",
    params={
        "fields": "code,title,status,operationType,pricing",
        "limit": 5,
    },
    headers={"Authorization": f"Bearer {token}"},
)

result = response.json()
print(f"Total de imóveis: {result['meta']['total']}")
for p in result["data"]:
    print(f"{p['code']} - {p['title']} ({p['status']})")

Descubra os campos disponíveis

Use o endpoint /v1/fields para ver todos os campos que você pode solicitar:

curl https://sandbox-partner-api.keyspot.com.br/v1/fields \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

const response = await fetch("https://sandbox-partner-api.keyspot.com.br/v1/fields", {
  headers: { Authorization: `Bearer ${token}` },
});

const { data } = await response.json();
console.log("Campos de properties:", Object.keys(data.properties));
console.log("Campos de leads:", Object.keys(data.leads));

response = requests.get(
    "https://sandbox-partner-api.keyspot.com.br/v1/fields",
    headers={"Authorization": f"Bearer {token}"},
)

data = response.json()["data"]
print("Campos de properties:", list(data["properties"].keys()))
print("Campos de leads:", list(data["leads"].keys()))

Crie um lead

Envie os dados de um novo contato interessado:

curl -X POST https://sandbox-partner-api.keyspot.com.br/v1/leads \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "11999999999",
    "message": "Tenho interesse neste imóvel.",
    "source": "WEBSITE",
    "propertyCode": "PROP-001"
  }'

const response = await fetch("https://sandbox-partner-api.keyspot.com.br/v1/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "João Silva",
    email: "joao@example.com",
    phone: "11999999999",
    message: "Tenho interesse neste imóvel.",
    source: "WEBSITE",
    propertyCode: "PROP-001",
  }),
});

const { data } = await response.json();
console.log(`Lead criado: ${data.id} (${data.status})`);

response = requests.post(
    "https://sandbox-partner-api.keyspot.com.br/v1/leads",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "name": "João Silva",
        "email": "joao@example.com",
        "phone": "11999999999",
        "message": "Tenho interesse neste imóvel.",
        "source": "WEBSITE",
        "propertyCode": "PROP-001",
    },
)

data = response.json()["data"]
print(f"Lead criado: {data['id']} ({data['status']})")

Os exemplos acima usam o ambiente sandbox. Quando estiver pronto para produção, basta trocar a URL base para https://partner-api.keyspot.com.br e usar suas credenciais de produção.

Erros comuns no início

Checklist

Credenciais (API Key + API Secret) em mãos
Health check retornando status: ok
Token JWT gerado com sucesso
Primeira listagem de imóveis funcionando
Campos disponíveis consultados via /v1/fields

Próximos passos

Autenticação

Entenda o fluxo JWT em detalhes, incluindo renovação de token e segurança.

Boas Práticas

Paginação, tratamento de erros, retry com backoff exponencial e checklist de produção.

Was this page helpful?

Last updated today

Built with Documentation.AI