API e documentação da Chave Direta.
A Chave Direta publica uma API pública, uma especificação OpenAPI 3.1 e arquivos legíveis por máquina para que sistemas e agentes integrem com a plataforma sem raspar HTML.
Base URL e versão
A base versionada é https://chavedireta.com.br/api/v1/public. O prefixo https://chavedireta.com.br/api/public continua respondendo como alias sem versão e sempre aponta para a versão corrente — prefira o caminho versionado.
Toda resposta carrega API-Version: v1. As respostas são application/json em UTF-8, exceto os feeds de portais, que são XML.
As páginas públicas também respondem text/markdown quando a requisição envia Accept: text/markdown, seguindo o acordo do acceptmarkdown.com.
Caminhos inexistentes respondem HTTP 404 de verdade — sob /api, com um corpo JSON estruturado.
Autenticação
Os endpoints sob /api/public são abertos e não exigem credencial. São leituras públicas ou escritas protegidas por captcha e deduplicação.
Os endpoints de cobrança usam um token opaco na própria URL, entregue ao pagador no link de cobrança. Não há chave de API envolvida — trate o token como segredo.
O restante da aplicação (/api/leads, /api/properties, /api/finance) usa sessão autenticada por cookie e pertence ao aplicativo. Não emitimos chave de API self-service hoje; para integração de parceiro, escreva para [email protected].
Endpoints públicos
| Método | Caminho | Descrição |
|---|---|---|
| GET | /api/v1/public/status | Status operacional da API pública e links dos índices. |
| GET | /api/v1/public/plans | Planos e preços publicados na página de preços. |
| GET | /api/v1/public/affiliate/validate?code=CODIGO | Valida um código de indicação e devolve os dias de bônus. |
| POST | /api/v1/public/leads | Registra um lead vindo do site público de um cliente. |
| POST | /api/v1/public/site-analytics | Registra um evento de navegação de um site público. |
| GET | /api/v1/public/charges/{token} | Dados de uma cobrança pelo token público entregue ao pagador. |
| GET | /api/v1/public/charges/{token}/status | Situação de pagamento de uma cobrança, própria para polling. |
| GET | /api/v1/public/integrations/feeds/{providerCode} | Feed XML de imóveis consumido pelos portais parceiros. |
CLI oficial
Para scriptar sem escrever integração, use o CLI publicado no npm. Ele usa o mesmo caminho versionado e imprime o saldo de requisições em stderr.
npx chave-direta status
npx chave-direta plans --audience real_estate --jsonExemplo de requisição
curl -s https://chavedireta.com.br/api/v1/public/status
curl -s "https://chavedireta.com.br/api/v1/public/plans?audience=real_estate"
curl -s -H "Accept: text/markdown" https://chavedireta.com.br/Limite de uso
Toda resposta traz RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset e RateLimit-Policy, para o cliente se auto-regular sem precisar tomar um erro primeiro. Ao estourar o limite a resposta é 429 com Retry-After.
- Leitura pública: 240 requisições por 60s, por IP.
- Escrita de lead: 60 por 60s.
- Telemetria de site: 600 por 60s.
- Feeds de portal: 120 por 60s.
Estabilidade e retirada de operações
A política completa, com o que conta como mudança compatível e como o aviso é entregue, está em /developers/deprecation. É para lá que aponta o header Link: rel="sunset" de toda resposta da API.
A versão vive no caminho da URL. Uma versão maior nova nunca reaproveita um caminho existente: as duas convivem durante todo o período de aviso.
Nenhuma operação é desligada sem no mínimo 180 dias de aviso. O aviso aparece em três lugares ao mesmo tempo: deprecated: true no /openapi.json, o header Deprecation (RFC 9745) e o header Sunset (RFC 8594) com a data de desligamento, na resposta da própria operação.
Formato de erro
Todo erro da API responde JSON com um código estável, a mensagem e uma dica do que fazer em seguida. O campo error permanece como string por compatibilidade.
{
"error": "Cobrança não encontrada.",
"code": "not_found",
"message": "Cobrança não encontrada.",
"hint": "Confira o caminho e os identificadores.",
"status": 404,
"documentation": "https://chavedireta.com.br/developers"
}