Pular para o conteúdo
Docs
API Conhecer a Zariv

Guia: montar um site com a API

Arquitetura recomendada, páginas que quase todo site precisa e um exemplo completo de busca e de formulário de contato.

#Arquitetura recomendada

A API foi feita para ser chamada pelo servidor do site. O visitante conversa com o seu site; o seu site conversa com a Zariv. Assim a chave não aparece no navegador e você controla o cache.

Fluxo
Visitante  →  Seu site (servidor)  →  API da Zariv
                    ↑ guarda a chave
                    ↑ guarda respostas em cache

#As páginas de um site de imobiliária

PáginaRotas da API usadas
Início (destaques, banners, busca)GET /imobiliaria, GET /imoveis?destaque=true, GET /localizacoes
Lista de imóveis com filtrosGET /imoveis (com os filtros e pagina)
Página de um imóvelGET /imoveis/slug/{slug} + POST /leads (formulário)
Link compartilhado pelo corretorGET /vitrines/{codigo} + POST /leads com vitrine_codigo
Anunciar meu imóvelPOST /leads com tipo: "captacao"
Imóveis vendidos e alugadosGET /imoveis?situacao=vendido,alugado

#Passo a passo

  1. Gere a chave
    Em Configurações › API & Integrações da Zariv. Guarde em uma variável de ambiente do servidor do site.
  2. Crie um cliente da API
    Uma função que chama a Zariv com a chave, trata erros e guarda respostas em cache (veja o exemplo abaixo).
  3. Monte os filtros com /localizacoes
    Cidades e bairros reais, sem digitação livre.
  4. Liste e abra imóveis
    Use slug nos endereços das páginas, para URLs boas para buscadores.
  5. Envie os contatos
    O formulário do site chama uma rota do seu servidor, que repassa a POST /leads.
  6. Teste ponta a ponta
    Envie um contato de teste e confira que ele chegou ao funil de vendas da Zariv.

#Exemplo: cliente com cache (Node.js)

JavaScript (Node.js 18 ou mais novo)
// zariv.js — roda no servidor do site
const BASE = "https://web.zariv.com.br/api/public/v1";
const cache = new Map(); // caminho -> { quando, dados }

export async function zariv(caminho, { ttlSegundos = 120 } = {}) {
  const guardado = cache.get(caminho);
  if (guardado && Date.now() - guardado.quando < ttlSegundos * 1000) return guardado.dados;

  const r = await fetch(BASE + caminho, {
    headers: { Authorization: `Bearer ${process.env.ZARIV_API_KEY}` },
  });
  if (!r.ok) {
    if (guardado) return guardado.dados; // Zariv com problema: usa o que já tinha
    throw new Error(`Zariv respondeu ${r.status}`);
  }
  const dados = await r.json();
  cache.set(caminho, { quando: Date.now(), dados });
  return dados;
}

export async function enviarContato(contato) {
  const r = await fetch(BASE + "/leads", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ZARIV_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(contato),
  });
  return { ok: r.ok, status: r.status, corpo: await r.json() };
}

#Exemplo: rota de busca no seu servidor (Express)

JavaScript (Express)
import express from "express";
import { zariv, enviarContato } from "./zariv.js";

const app = express();
app.use(express.json());

// O navegador chama /api/imoveis?cidade=Cacoal; o servidor repassa com a chave
app.get("/api/imoveis", async (req, res) => {
  const permitidos = ["cidade", "bairro", "tipo_imovel", "finalidade", "quartos_min", "valor_min", "valor_max", "pagina"];
  const consulta = new URLSearchParams();
  for (const chave of permitidos) if (req.query[chave]) consulta.set(chave, String(req.query[chave]));
  consulta.set("por_pagina", "12");
  try {
    res.json(await zariv("/imoveis?" + consulta));
  } catch {
    res.status(502).json({ error: "Não foi possível carregar os imóveis agora." });
  }
});

app.post("/api/contato", async (req, res) => {
  const { nome, telefone, email, imovel_id, mensagem } = req.body || {};
  if (!nome || !telefone) return res.status(400).json({ error: "Informe nome e telefone." });
  const r = await enviarContato({ nome, telefone, email, imovel_id, mensagem });
  res.status(r.ok ? 200 : 502).json(r.corpo);
});

app.listen(3000);

#SEO e desempenho

  • Use o slug nos endereços e o titulo e a descricao do imóvel nas tags da página.
  • Gere as páginas no servidor (ou pré-gere) para que buscadores e redes sociais vejam o conteúdo.
  • Use seo_titulo_padrao e seo_descricao_padrao de imobiliária nas páginas sem texto próprio.
  • Carregue fotos com loading="lazy", exceto a primeira da página.

#Antes de publicar

  • A chave está só no servidor, em variável de ambiente.
  • As respostas estão em cache e o site aguenta a Zariv ficar um instante fora do ar.
  • O formulário tem validação e proteção contra robôs.
  • Existe uma página amigável para imóvel não encontrado (404).
  • Você testou um contato de ponta a ponta e viu o lead chegar no funil.