Tutorial: como usar a API do site da Viniun

A API do site da Viniun entrega os seus imóveis, os dados da imobiliária e recebe os contatos do formulário em qualquer site: feito por você, por uma agência ou por uma IA como o Lovable. Você vai criar a chave certa, limitar os sites que a usam, testar, buscar imóveis e mandar um contato para o funil. Leva uns 15 minutos, fora a programação.

Quem pode fazer: quem tem permissão de editar o item API & Webhooks (em geral o dono ou o administrador da conta). Quem só tem permissão de ver enxerga as chaves, mas não cria nem revoga. As telas são da conta de demonstração da Viniun, com dados fictícios.

Este é o passo a passo prático. A visão geral de API, webhooks e integrações está no guia API, webhooks e integrações para imobiliária.

O que você precisa antes de começar

• O item API & Webhooks aparecendo no menu Integrações. Se não aparecer, fale com quem administra a conta.
• Imóveis com anúncio publicado: a API só mostra imóvel ativo, disponível ou reservado e publicado.
• O endereço (domínio) onde o site vai ficar, por exemplo www.suaimobiliaria.com.br.
• Alguém para programar o site, ou uma ferramenta de IA que faça isso por você.

Passo 1: abra a tela API & Webhooks

No menu da esquerda, em Integrações, clique em API & Webhooks. A aba Chaves de API lista as chaves da imobiliária, o que cada uma pode fazer e o último uso.

1. API & Webhooks — o item do menu Integrações que abre a tela.
2. Abas — Chaves de API, Webhooks, Receber leads e Crie seu site com IA.
3. Nova chave — abre o formulário para criar uma chave.
4. Chave — o nome, o começo da chave, as permissões e onde ela funciona. "Navegador: bloqueada" quer dizer que só um servidor pode usá-la.
5. Uso e ações — quantas chamadas a chave já fez, quando foi usada pela última vez, o globo (sites que podem usar) e a lixeira (revogar).

Passo 2: crie a chave pública da API do site da Viniun

Um site que roda no navegador do visitante (como os feitos no Lovable) precisa de uma chave que pode ficar à vista no código. Essa é a chave pública, que começa com vk_pub_. Ela só lê o que o site já mostra (imóveis, bairros, dados da imobiliária) e envia os formulários de contato. Clique em Nova chave, dê um nome e marque Site no navegador.

A chave pública não se combina com outras permissões: ao marcá-la, as outras caixas se desmarcam. Em Sites que podem usar no navegador, escreva um domínio por linha. Em branco, qualquer site pode usar a chave; com a lista, um site que copiar a chave é recusado. Use *.lovable.app enquanto o site estiver em teste no Lovable.

1. Para que é esta chave? — um nome que você reconheça depois, como "Site Exemplo (navegador)".
2. Site no navegador — a permissão da chave pública. Fica sozinha, sem outras permissões.
3. Sites que podem usar — os domínios liberados, um por linha. O asterisco vale para qualquer começo: *.lovable.app libera abc.lovable.app.
4. Criar — gera a chave. A pública continua visível nesta tela depois, para você copiar quando precisar.

Atalho: na aba Crie seu site com IA o botão Criar chave pública do site faz o mesmo e já coloca a chave no prompt pronto. Veja em Tutorial: criar site com Lovable.

Passo 3: crie uma chave secreta se o site tiver servidor

Se o site é montado num servidor (Next.js, Astro, PHP, WordPress com código próprio), use uma chave secreta, que começa com vk_. Marque só o que o site precisa: Ler imóveis, Ler dados do site e Criar leads. Deixe os domínios em branco: assim ela só funciona pelo servidor, e qualquer navegador que tentar usá-la recebe recusa.

1. Nome — por exemplo "Servidor do site Exemplo".
2. Permissões — Ler dados do site, Ler imóveis e Criar leads cobrem um site completo. Evite as outras.
3. Dê só o que a integração precisa — chave que faz tudo é a que mais estraga se vazar.
4. Em branco, só pelo servidor — sem domínios, a chave secreta não funciona em navegador nenhum. É o mais seguro.

Guarde a chave secreta na hora. Depois de clicar em Criar, ela aparece uma única vez na janela "Guarde esta chave agora". A Viniun guarda só um resumo dela: se perder, crie outra e revogue a antiga.

Passo 4: limite os sites que podem usar a chave

Quando o site for ao ar no domínio definitivo, clique no globo da chave e deixe só o seu domínio. Na pública, isso impede que outro site use a sua chave. Na secreta, só libere um site se for mesmo necessário: quem abre o site consegue copiá-la.

1. Sites que podem usar — o nome da chave que você está ajustando.
2. Um domínio por linha — por exemplo www.suaimobiliaria.com.br. Tire o *.lovable.app quando o site sair do teste.
3. Aviso — lembra o que acontece com a lista em branco em cada tipo de chave.
4. Salvar — grava a lista. A mudança vale na próxima chamada.

Passo 5: teste a chave e abra a documentação

A documentação completa é pública: novo.viniun.com.br/docs/site-api. Traz cada endereço, filtros, respostas e exemplos. Para uma IA, mande o resumo em llms.txt ou o arquivo OpenAPI. Comece pelo teste da chave, que diz de qual imobiliária ela é (a chave também vai em Authorization: Bearer ou em ?chave=):

curl https://novo.viniun.com.br/api/v1/site-api/ \
  -H "X-Api-Key: vk_pub_SUA_CHAVE"

1. Testar a chave — o primeiro endereço para conferir se a chave está certa.
2. Introduction — o resumo: chaves, permissões, limites e privacidade.
3. Exemplo — o código pronto. Troque YOUR_SECRET_TOKEN pela sua chave.
4. Test Request — testa a chamada ali mesmo, com a sua chave.
5. Open API Client — abre um cliente completo para testar todos os endereços.

Passo 6: busque os imóveis e gere as páginas

A busca usa os mesmos filtros do site da Viniun: finalidade, tipo, cidade, bairro, faixa de preço, quartos, vagas, área e outros. Volta uma página de imóveis com o total e os links da próxima página. No máximo 50 por página.

const API = 'https://novo.viniun.com.br/api/v1/site-api';
const CHAVE = 'vk_pub_SUA_CHAVE';

const r = await fetch(`${API}/imoveis?finalidade=venda&dormitorios_min=2&por_pagina=12`, {
  headers: { 'X-Api-Key': CHAVE },
});
const { data, meta } = await r.json(); // data = imóveis, meta.total = quantos

Para a página de cada imóvel, use a ficha pelo endereço amigável (/imoveis/{slug}) ou pelo código (/imoveis/codigo/{codigo}). A ficha já traz título e descrição para o Google e os dados estruturados. Para o sitemap e para gerar uma página por imóvel na publicação do site, use /imoveis/slugs.

1. Buscar imóveis — a lista com filtros e paginação.
2. Permissão da chave — funciona com a chave pública ou com a secreta que tem "Ler imóveis".
3. Filtros — cada filtro aceito, com explicação. As opções de tipo, cidade e bairro vêm de /imoveis/filtros.
4. Exemplo — o código da chamada.
5. Respostas — 200 deu certo; 401 chave errada; 403 sem permissão ou site não liberado; 429 muitas chamadas.
6. Todos os endereços (sitemap) — a lista de todos os imóveis para o sitemap e para gerar as páginas.

Passo 7: mande os contatos do site para o funil

Todo formulário do site deve ir para /leads. O contato entra no funil, passa pelo rodízio e o corretor é avisado. O mesmo telefone não vira lead repetido: entra como nova atividade no lead aberto. Nome (mínimo 3 letras) e telefone com DDD são obrigatórios.

await fetch(`${API}/leads`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Api-Key': CHAVE },
  body: JSON.stringify({
    origem: 'maisinfo',
    nome: 'Cliente Exemplo',
    telefone: '(13) 99999-0000',
    mensagem: 'Quero mais informações',
    imovel_slug: slugDoImovel,
    pagina: location.href,
    website: '', // campo escondido anti-robô: deixe sempre vazio
  }),
});

1. Enviar contato (lead) — o endereço dos formulários do site.
2. Permissão da chave — a chave pública ou a secreta com "Criar leads".
3. Exemplo — todos os campos aceitos: origem, imóvel, cidade, data preferida para visita e outros.
4. Respostas — 201 lead registrado; 422 falta campo; 429 envio demais.
5. Avise-me (busca salva) — para o botão "me avise quando entrar um imóvel assim".

Quer saber na hora quando um imóvel entra ou sai do ar? Cadastre um webhook: veja o Tutorial: webhooks da Viniun.

Quais são as dicas e os erros mais comuns?

• Chave secreta no navegador: a chamada com origem de um site não liberado volta 403. Use a pública no navegador e a secreta só no servidor.
• Limites por minuto, por chave: pública 1.200 chamadas, só leitura 600 e com escrita 120. Contatos: 5 por minuto por telefone. Se vier 429, espere o tempo do cabeçalho Retry-After.
• Guarde em cache por 5 a 10 minutos. O estoque muda poucas vezes por hora, e o site fica mais rápido.
• Imóvel que saiu do ar responde 404: mostre uma busca parecida em vez de página em branco.
• Mapa: sem a opção "mostrar endereço completo", a localização vem aproximada. Mostre um círculo da região, não um alfinete.
• Chave vazou? Revogue na lixeira da chave. Quem usa perde o acesso na hora; o histórico de uso continua.
• SEO: site que só roda no navegador aparece pior no Google. Peça páginas geradas na publicação (uma por imóvel, a partir de /imoveis/slugs) e sitemap.

Próximos passos

• Tutorial: criar o site da imobiliária com Lovable
• Tutorial: criar o site com ChatGPT e Claude
• Tutorial: hospedar o site na Hostinger ou HostGator
• Tutorial: webhooks da Viniun
• Tutorial: receber leads de site externo
• Prefere não programar? O site pronto da Viniun está em Tutorial: site da imobiliária e nos modelos de site.
• Guia: API, webhooks e integrações para imobiliária