# Viniun — API do site da imobiliária

> API REST (JSON) para criar o site de uma imobiliária em qualquer plataforma e integrar com o
> CRM Viniun: imóveis publicados com filtros e paginação, ficha completa com fotos e JSON-LD,
> dados da imobiliária, bairros, edifícios, construtoras e envio de contatos (leads) para o funil.

Base: https://novo.viniun.com.br/api/v1/site-api
OpenAPI 3.1: https://novo.viniun.com.br/api/v1/site-api/openapi.json
Documentação: https://novo.viniun.com.br/docs/site-api

## Autenticação
- Chave da imobiliária em `Authorization: Bearer vk_…`, `X-Api-Key: vk_…` ou `?chave=vk_…`.
- Chave pública (`vk_pub_…`, permissão `site:publico`): pode ficar no navegador; só lê o que o site mostra e envia formulários.
- Chave secreta: só no servidor. Com cabeçalho Origin de domínio não cadastrado → 403.

## Endpoints
- GET /imobiliaria — nome, logo, cores, contatos, redes, CRECI, textos, SEO, script de rastreio
- GET /imoveis — busca com filtros: finalidade, tipo, tipos, cidade, bairro, q, codigo, preco_min, preco_max, dormitorios_min (quartos_min), suites_min, banheiros_min, vagas_min, area_min, area_max, condominio_max, entrada_max, parcela_max, mcmv, direto_construtora, financiamento, destaque, lancamento, airbnb, edificio, construtora, ordem (recentes|menor-valor|maior-valor|maior-area), page, por_pagina (máx. 50)
- GET /imoveis/filtros — opções dos seletores (tipos, finalidades, cidades, bairros)
- GET /imoveis/slugs — todos os slugs + data de atualização (sitemap, SSG)
- GET /imoveis/{slug} — ficha completa (fotos thumb/media/grande, características, valores, mapa, seo.json_ld)
- GET /imoveis/codigo/{codigo} — ficha pelo código de referência
- GET /bairros, /bairros/{slug} — bairros com imóveis e o texto do guia
- GET /edificios, /edificios/{slug} — condomínios e seus imóveis
- GET /construtoras, /construtoras/{slug}
- POST /leads — {nome, telefone, email?, mensagem?, imovel_slug? | imovel_codigo?, origem?, utm?, pagina?, referrer?, cookie_id?, data_preferida?, periodo?, extras?} → 201 {ok, lead_id, mensagem}
- POST /buscas-salvas — {nome, telefone, filtros:{tipo, bairro, finalidade, dormitorios_min, preco_max}}
- GET /vagas — vagas abertas (trabalhe conosco): slug, titulo, cidade, salario?, curriculo/video = nao|opcional|obrigatorio, video_max_segundos
- GET /vagas/{slug} — a vaga + `perguntas` (questionário montado pela imobiliária no construtor de formulários: nome, label, tipo, obrigatorio, opcoes, condicao)
- POST /vagas/{slug}/candidaturas — multipart: nome, telefone, email?, cidade?, uf?, creci?, portfolio?, curriculo (arquivo, até 10 MB), respostas (JSON {nome_da_pergunta: valor}), video_token? → 201 {ok, mensagem}
- POST /vagas/{slug}/video {tamanho, tipo, segundos} → {upload_id, parte_bytes, partes}; POST /vagas/{slug}/video/{upload_id}/parte (multipart indice + parte); POST /vagas/{slug}/video/{upload_id}/concluir → {video_token}

Origens aceitas em /leads: site, faleconosco, maisinfo, ligacoes, encomenda, agendamento, avaliacao, financiamento, permuta, sob_medida, desbloqueio, cadastro_imovel, whatsapp_site, trabalhe_conosco, satisfacao, corretor_parceiro, placa.

## Regras para o site
- Uma página por imóvel em /imoveis/{slug}, com title/description de `seo`, og:image e o `seo.json_ld` num <script type="application/ld+json"> (acrescente "url").
- sitemap.xml com a home, a busca e todas as páginas de /imoveis/slugs; robots.txt apontando para ele.
- Formulários SEMPRE em POST /leads, com um campo escondido `website` vazio (anti-robô) e as UTMs da URL.
- Exceção: candidatura a vaga vai em POST /vagas/{slug}/candidaturas (vira candidato no RH, não lead). Monte as perguntas a partir de GET /vagas/{slug} → perguntas — nunca fixe as perguntas no código.
- Cole o script de `GET /imobiliaria` → rastreio.script em todas as páginas e mande `cookie_id: window.viniunRastreio?.id` no lead.
- Coordenada com `aproximado: true`: mostre círculo da região, nunca alfinete; endereço só se `endereco_completo`.
- Nada de telefone de corretor: o contato é o da imobiliária (`contato.whatsapp`).
- Faça cache (5 a 10 min) e trate 404 (imóvel saiu do ar) com uma busca parecida.