# API pública da contemplei

Desenvolvedores

Catálogo de cartas de consórcio contempladas em JSON, somente leitura, sem autenticação e com CORS aberto a qualquer origem. Feito para agentes de IA, integrações e quem quer consumir os mesmos dados que o site mostra.

## Especificação e recursos para agentes

openapi.json

[https://contemplei.app/openapi.json](/openapi.json)

Especificação OpenAPI 3 das sete operações públicas, em JSON.

openapi.yaml

[https://contemplei.app/openapi.yaml](/openapi.yaml)

A mesma especificação em YAML.

llms.txt

[https://contemplei.app/llms.txt](/llms.txt)

Resumo do site para LLMs: páginas, quando usar, empresa e API.

llms-full.txt

[https://contemplei.app/llms-full.txt](/llms-full.txt)

Versão completa do llms.txt, com glossário e limitações.

## 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.

Método

Caminho

O que devolve

GET

/v1/anuncios/publico

Catálogo público de cartas contempladas

GET

/v1/anuncios/publico/arena

Arena: cartas à venda em formato de tabela comparativa

GET

/v1/anuncios/publico/indexaveis

Cartas com página pública própria

GET

/v1/anuncios/publico/carta/{seoSlug}

Detalhe de uma carta pelo slug da página

GET

/v1/anuncios/publico/mercado

Ágio de mercado de cartas comparáveis

GET

/v1/anuncios/publico/{externalId}

Resumo público de uma carta pelo identificador

GET

/v1/anuncios/compartilhado/{slug}

Carta por link compartilhado

## 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

A versão vai na URL: todas as operações vivem em /v1/. Dentro de uma versão só entram mudanças compatíveis — campos e filtros novos, opcionais, nunca a remoção ou a mudança de tipo de algo já publicado. Trate campos desconhecidos como opcionais.

Mudanças incompatíveis só entram em uma versão nova (/v2/), com a anterior mantida em paralelo. Antes de desligar uma versão, a contemplei anuncia nesta página e no spec, e envia os headers Deprecation e Sunset nas respostas, com antecedência mínima de 90 dias.

## 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.

[Ver o catálogo](/anuncios/) [Falar com a contemplei](/contato/)