API pública da contemplei

Especificação e recursos para agentes

Endpoints

Sete operações GET sob https://contemplei.app/v1/. Os resumos abaixo são os mesmos publicados na especificação OpenAPI; parâmetros e schemas completos estão no spec.

Exemplo de chamada

Cartas de imóvel com crédito a partir de R$ 200.000, primeira página com 20 itens. Valores monetários são inteiros em centavos (BRL).

curl "https://contemplei.app/v1/anuncios/publico?segmentos=imoveis&creditoMin=20000000&page=1&pageSize=20"

Filtros mais usados

• segmentos — imoveis, moveis ou servicos; aceita lista separada por vírgula.
• creditoMin e creditoMax — faixa do crédito da carta, em centavos.
• entradaMin, entradaMax, parcelaMin e parcelaMax — faixas de entrada e parcela, em centavos.
• administradoraIds — identificadores das administradoras, separados por vírgula.
• ordenarPor e ordem — campo e direção (asc ou desc) da ordenação.
• page e pageSize — paginação; pageSize vai até 100 (padrão 20).

Envelope de resposta

Toda resposta 2xx vem no envelope com as chaves data e meta. Nas listas paginadas (publico, arena e indexaveis) o meta traz total, page e pageSize; nas demais operações traz só success.

Lista paginada

{
  "data": [
    {"id":"5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f","codigo":"IM-1024","seoSlug":"carta-contemplada-imoveis-hs-consorcios-250-mil-1024","segmento":"imoveis","creditoCents":25000000,"entradaCents":6000000,"parcelaSemSeguroCents":185000,"prazoRestanteMeses":120,"administradoraId":"0b1c2d3e-4f5a-4b6c-9d7e-8f9a0b1c2d3e","administradoraNome":"HS Consórcios"}
  ],
  "meta": { "success": true, "total": 42, "page": 1, "pageSize": 20 }
}

Objeto único

{
  "data": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "segmento": "imoveis", "creditoCents": 25000000 },
  "meta": { "success": true }
}

Modelo de erro

Toda resposta 4xx ou 5xx usa o mesmo objeto, sem envelope. O campo code é estável e serve para tratar o erro; message é legível e pode mudar. Guarde o requestId ao reportar um problema — ele também vai no header X-Request-Id.

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "pageSize must not be greater than 100",
  "requestId": "9f1c2a4e-7b3d-4c58-a1e2-0d6f8b9c3e11"
}

Códigos

• 400 BAD_REQUEST — filtro, paginação ou parâmetro inválido (a mensagem lista as violações).
• 404 NOT_FOUND — slug ou identificador sem carta publicada correspondente.
• 422 VALIDATION — regra de negócio violada.
• 429 TOO_MANY_REQUESTS — limite de requisições excedido; veja Retry-After.
• 500 INTERNAL — falha inesperada; tente de novo e informe o requestId ao suporte.

Limite de requisições

O limite é por endereço IP e por janela de tempo (por padrão, 120 requisições por minuto). O valor vigente vem em toda resposta, nos headers padrão do IETF e nos X-RateLimit-* legados:

• RateLimit-Limit — quantidade de requisições permitidas na janela.
• RateLimit-Remaining — quantas ainda cabem na janela atual.
• RateLimit-Reset — segundos até a janela zerar.
• RateLimit-Policy — a política no formato limite;w=segundos.

Ao exceder o limite a API responde 429 com o modelo de erro acima e o header Retry-After em segundos. Respeite o Retry-After e identifique o seu agente no User-Agent.

Versionamento e compatibilidade

CORS e autenticação

As operações desta página não pedem chave nem token, e respondem Access-Control-Allow-Origin: * para GET, HEAD e OPTIONS, então podem ser chamadas direto do navegador. Fazer proposta, anunciar e acompanhar uma negociação exigem conta e ficam fora da API pública.