# Keyspot Partner API

## Guias

- [Introdução](https://developers.keyspot.com.br/comece-aqui/introducao.md): Descubra o que é a Keyspot Partner API, entenda o ecossistema Keyspot e veja como nossa API pode acelerar sua integração.
- [Quickstart](https://developers.keyspot.com.br/comece-aqui/quickstart.md): Faça sua primeira chamada à Keyspot Partner API em 5 minutos. Obtenha credenciais, gere um token e consulte imóveis.
- [Autenticação](https://developers.keyspot.com.br/comece-aqui/autenticacao.md): Entenda o fluxo de autenticação JWT de duas fases da Keyspot Partner API, com exemplos de código e boas práticas de segurança.
- [Fluxo de Integração](https://developers.keyspot.com.br/guias/fluxo-integracao.md): Guia passo a passo para integrar sua aplicação com a Keyspot Partner API, do planejamento à produção.
- [Boas Práticas](https://developers.keyspot.com.br/guias/boas-praticas.md): Recomendações de paginação, tratamento de erros, retry com backoff exponencial, rate limiting e checklist de produção para a Keyspot Partner API.
- [Dicionário de Dados](https://developers.keyspot.com.br/referencia/dicionario-dados.md): Referência completa de todas as entidades, campos, tipos e enumerações disponíveis na Keyspot Partner API.
- [Erros Comuns](https://developers.keyspot.com.br/operacao/erros-comuns.md): Diagnóstico e resolução dos erros mais frequentes ao integrar com a Keyspot Partner API.
- [Suporte](https://developers.keyspot.com.br/operacao/suporte.md): Canais de suporte e como obter ajuda para integrar com a Keyspot Partner API.

## API Reference

- [Visão Geral da API](https://developers.keyspot.com.br/api-reference/introducao.md): Visão geral da Keyspot Partner API: base URL, autenticação, formato de respostas, paginação e rate limiting.
- [Verificar status da API](https://developers.keyspot.com.br/api-reference/get-health.md): Retorna o status de funcionamento da API. Não requer autenticação.
- [Gerar token de acesso](https://developers.keyspot.com.br/api-reference/post-v1-auth-token.md): Fase 1 da autenticação. Envia as credenciais do parceiro via headers `X-API-Key` e `X-API-Secret` e recebe um token JWT válido por 1 hora.

O token retornado deve ser utilizado como `Bearer` no header `Authorization` de todas as rotas protegidas.
- [Listar imóveis](https://developers.keyspot.com.br/api-reference/get-v1-properties.md): Retorna uma lista paginada de imóveis publicados. Você controla quais campos são retornados através do parâmetro `fields` (obrigatório).

Campos simples como `title`, `status` retornam valores diretos. Campos agrupados como `address`, `features`, `pricing` retornam objetos com sub-campos.

Suporta filtros por status, tipo de operação, tipo de imóvel e datas de criação/atualização.
- [Listar leads](https://developers.keyspot.com.br/api-reference/get-v1-leads.md): Retorna uma lista paginada de leads. Você controla quais campos são retornados através do parâmetro `fields` (obrigatório).

Suporta filtros por status e datas de criação/atualização.
- [Criar lead](https://developers.keyspot.com.br/api-reference/post-v1-leads.md): Cria um novo lead no sistema. Campos obrigatórios: `name`, `email`, `phone` e `message`.

Se `propertyCode` for informado e o imóvel existir, o lead será vinculado automaticamente ao imóvel. Se `interestedPropertyTitle` não for informado, será preenchido com o título do imóvel encontrado.

O lead é criado com status `NEW_LEAD` e prioridade `MEDIUM` por padrão.
- [Listar campos disponíveis](https://developers.keyspot.com.br/api-reference/get-v1-fields.md): Retorna todos os campos disponíveis para as entidades `properties` e `leads`. Use este endpoint para descobrir quais campos podem ser solicitados no parâmetro `fields` dos endpoints de listagem.

Campos podem ser simples (retornam valor direto) ou agrupados (retornam objeto com sub-campos).
- [Obter valores distintos de um campo](https://developers.keyspot.com.br/api-reference/get-v1-values-entity-field.md): Retorna os valores distintos disponíveis para um campo específico de uma entidade. Útil para popular filtros e selects na sua aplicação.

**Campos consultáveis:**
- `properties`: `status`, `operationType`, `propertyType`, `highlight`
- `leads`: `status`, `source`, `priority`

## Collections

- [Postman Collection](https://developers.keyspot.com.br/collections/index.md): Importe a Postman Collection da Keyspot Partner API para testar todos os endpoints rapidamente.

## Changelog

- [Histórico de Versões](https://developers.keyspot.com.br/changelog.md): Changelog da Keyspot Partner API com todas as alterações, novas funcionalidades e correções.