REST API v1

REAL NOW · API Pública

API REST autenticada por token Bearer. Inteligência de mercado agregada + inventário de corretores verificado + briefings de IA. Respostas em JSON, limites de taxa por nível.

Autenticação

Todos os endpoints requerem um token Bearer no Authorization header:

# Request
curl -H "Authorization: Bearer rn_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://realnow.com/api/v1/health

Como obter uma chave:

Enterprise users: autoatendimento em configurações da conta.
PRO users: contate o administrador para emitir uma chave em seu nome.
Free users: O acesso à API requer o nível PRO+.

Chaves em texto simples são mostradas UMA VEZ na criação. Armazene-as em um gerenciador de segredos — elas não podem ser recuperadas depois. Se perdidas, revogue e crie uma nova.

Limites de taxa

Por chave, por hora. Contadores são reiniciados no início de cada hora UTC.

Nível	Limite por hora	Diário ~
free	—	Sem acesso à API
pro	100	~2,400
enterprise	1,000	~24,000
admin	Ilimitado	—

Respostas acima do limite retornam HTTP 429 com retry_after_seconds.

Formato de erro

{
  "ok": false,
  "error": "rate_limit",
  "message": "Hourly rate limit reached (100 req/h for tier pro).",
  "limit": 100,
  "used": 100,
  "retry_after_seconds": 1842
}

Códigos de erro comuns:

auth_required — 401, missing key
invalid_key — 401, key revoked or owner inactive
scope_denied — 403, key lacks the required scope
rate_limit — 429, hourly limit hit
not_found — 404, no such resource

Endpoints

GET /api/v1/health escopo: read

Verifique se a chave funciona + veja seu nível.

curl -H "Authorization: Bearer $RN_KEY" \
  https://realnow.com/api/v1/health
# {"ok":true,"service":"real-now-api","version":"v1","tier":"pro",...}

GET /api/v1/zones escopo: read

Estatísticas de mercado agregadas por zona em todos os 8 países da LATAM (GT, SV, HN, CR, BZ, DO, PA, BR). Use ?country=XX para filtrar.

Parâmetro	Tipo	Padrão	Descrição
`country`	string	GT	Código do país

curl -H "Authorization: Bearer $RN_KEY" \
  https://realnow.com/api/v1/zones
# {"ok":true,"count":25,"zones":[
#   {"zone":"Zona 1","median_ppm2_usd":1340.5,"n_active":420,"median_dom":31,...},
#   ...
# ]}

GET /api/v1/zone/{slug} escopo: read

Visão detalhada de uma zona: medianas por tipo de propriedade + quarto + operação, variação de 30 dias, mix de fontes.

curl -H "Authorization: Bearer $RN_KEY" \
  https://realnow.com/api/v1/zone/zona-10

GET /api/v1/listings escopo: read

Apenas inventário de corretores verificados (active broker_listings). Dados raspados NUNCA são expostos via API.

Parâmetro	Tipo	Descrição
`zone`	string	Zona N
`country`	string	GT (default)
`operation`	string	Venta \| Renta
`property_type`	string	Apartamento, Casa, Terreno, …
`price_min` / `price_max`	number	USD bounds
`limit` / `offset`	int	Paginação — limite de 1-200

curl -H "Authorization: Bearer $RN_KEY" \
  "https://realnow.com/api/v1/listings?zone=Zona+10&operation=Venta&price_max=200000"

GET /api/v1/briefings/personas escopo: read

Liste as 5 personas de IA com seu esquema de entrada + vocabulário de veredicto.

POST /api/v1/briefings/{persona} escopo: write

Gere um briefing de IA. Conta contra a cota mensal do proprietário da chave (igual ao UI da web). Acertos de cache de 24h não consomem cota.

curl -X POST -H "Authorization: Bearer $RN_KEY" \
     -H "Content-Type: application/json" \
     -d '{"zone":"Zona 10","profile":"cash"}' \
     https://realnow.com/api/v1/briefings/inversor
# Returns: {"ok":true,"verdict":"Comprar","confidence":"Alta",
#           "headline":"Zona 10 ofrece yield bruto del 7.0%...",
#           "body_md":"## Veredicto\n**Comprar** · Confianza: Alta\n...",
#           "usage":{"used":3,"quota":20,"unlimited":false}}

Registro de alterações

v1.0 · 2026-05-07 — Lançamento inicial. 6 endpoints. Autenticação por token Bearer. Limites de taxa por nível.