Fluxo de Integração

Abra um chamado no CRM com um usuário administrador para solicitar seu par API Key + API Secret. Acesse https://crm.keyspot.com.br/support/tickets e informe:

• Nome da empresa parceira
• Caso de uso da integração (portal, CRM, site, etc.)
• IPs de origem das requisições (se aplicável)

Você receberá credenciais com um rate limit configurado de acordo com seu caso de uso.

Enquanto aguarda suas credenciais de produção, use o ambiente de sandbox para desenvolver e testar sua integração. O sandbox vem pré-configurado com dados fictícios.

URL Base Sandbox: https://sandbox-partner-api.keyspot.com.br

Credenciais de teste (prontas para uso):

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

Implemente o fluxo JWT de duas fases:

1. POST /v1/auth/token com headers X-API-Key e X-API-Secret
2. Use o token retornado como Bearer nas rotas protegidas
3. Renove o token antes de expirar (1 hora)

Veja detalhes em Autenticação.

Antes de consumir dados, consulte GET /v1/fields para entender a estrutura de cada entidade:

• properties: imóveis com campos como title, address, pricing, features, photos
• leads: contatos com campos como name, email, phone, status, source

Use também GET /v1/values/{entity}/{field} para descobrir os valores possíveis de cada filtro.

Use GET /v1/properties com os filtros adequados ao seu caso:

• Portal imobiliário: fields=code,title,description,address,pricing,features,photos&status=AVAILABLE
• Dashboard analítico: fields=code,title,status,operationType,createdAt&limit=100
• Sincronização incremental: fields=code,title,status,updatedAt&updatedAfter=2026-03-01T00:00:00Z

Implemente paginação para percorrer todos os resultados.

Conecte seus formulários ao POST /v1/leads. Campos obrigatórios:

• name, email, phone, message

Campos opcionais que enriquecem o lead:

• source: identifique a origem (WEBSITE, PORTAL_VIVAREAL, GOOGLE_ADS, etc.)
• propertyCode: vincule ao imóvel de interesse
• trafficOrigin: rastreie a campanha ou UTM de origem

Antes de ir para produção, revise o checklist de boas práticas:

• Tratamento de todos os códigos de erro
• Renovação automática de token
• Paginação implementada
• Rate limiting respeitado
• Credenciais armazenadas com segurança
• Retry com backoff exponencial