Visao Geral

Visão Geral da API

Visão geral da Keyspot Partner API: base URL, autenticação, formato de respostas, paginação e rate limiting.

Ambientes

A Partner API possui dois ambientes disponíveis:

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

O ambiente de sandbox é destinado a desenvolvedores que desejam testar a integração sem impacto em dados reais. O tenant de sandbox já vem pré-configurado com dados fictícios prontos para uso.

Credenciais de teste (Sandbox)

Use as credenciais abaixo para testar no sandbox sem necessidade de cadastro:

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

Essas chaves funcionam exclusivamente no ambiente sandbox e serão recusadas em produção.

Autenticação

A API utiliza autenticação JWT em duas fases:

Obter token: POST /v1/auth/token com headers X-API-Key e X-API-Secret
Usar token: header Authorization: Bearer SEU_TOKEN em todas as rotas protegidas

O token expira em 1 hora. Veja detalhes em Autenticação.

Formato de respostas

Sucesso (com paginação)

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Sucesso (sem paginação)

{
  "data": { ... }
}

Erro

{
  "error": "Mensagem de erro legível",
  "code": "CODIGO_PROGRAMATICO"
}

Endpoints disponíveis

Método	Endpoint	Descrição	Auth
`GET`	`/health`	Health check	Não
`POST`	`/v1/auth/token`	Gerar token JWT	Não*
`GET`	`/v1/fields`	Listar campos disponíveis	Sim
`GET`	`/v1/values/{entity}/{field}`	Valores distintos de um campo	Sim
`GET`	`/v1/properties`	Listar imóveis	Sim
`GET`	`/v1/leads`	Listar leads	Sim
`POST`	`/v1/leads`	Criar lead	Sim

*O endpoint de token usa X-API-Key e X-API-Secret como headers, não Bearer token.

Seleção de campos

Os endpoints GET /v1/properties e GET /v1/leads exigem o parâmetro fields (obrigatório), que define quais campos são retornados na resposta.

# Retorna apenas code, title e pricing
GET /v1/properties?fields=code,title,pricing

Campos agrupados (como address, features, pricing) retornam todos os seus sub-campos ao serem solicitados.

Paginação

Parâmetro	Tipo	Padrão	Máximo
`page`	integer	1	—
`limit`	integer	20	100

Filtros de data

Disponíveis em GET /v1/properties e GET /v1/leads:

Parâmetro	Descrição
`createdAfter`	Registros criados após esta data (ISO 8601)
`createdBefore`	Registros criados antes desta data
`updatedAfter`	Registros atualizados após esta data
`updatedBefore`	Registros atualizados antes desta data

Rate limiting

Cada cliente tem um limite de requisições por minuto. Os headers de resposta indicam o consumo:

Header	Descrição
`X-RateLimit-Limit`	Limite máximo
`X-RateLimit-Remaining`	Requisições restantes
`Retry-After`	Segundos para aguardar (quando exceder)

Próximos passos

Quickstart

Faça sua primeira chamada em 5 minutos.

Postman Collection

Importe todos os endpoints no Postman.

Was this page helpful?

Last updated today

Built with Documentation.AI