API da conta do FarejaLeads

Leve os dados da sua conta para o seu site, painel ou admin: visitas e funil do CRM, as pessoas que chegaram, as campanhas de anúncios, as auditorias das páginas e as tarefas. JSON, só leitura, com uma chave de API da sua conta.

Use do seu servidor, nunca no navegador. A chave dá acesso aos dados da sua conta. Guarde numa variável de ambiente do servidor (ex.: FAREJALEADS_API_KEY), chame a API de lá e mande ao navegador só o que a página precisa mostrar. A API não libera CORS: o navegador de outro domínio não consegue chamá-la. Nunca ponha a chave na URL, no repositório ou num app.

1. A chave

Crie em Minha conta → Chaves de API: um nome, o que a chave pode ler (os escopos) e, se quiser, só alguns sites do CRM e uma validade. A chave (fl_live_…) aparece uma vez só; na lista fica o começo dela, quando foi usada pela última vez e de que país. Vazou? Revogue na mesma tela e crie outra: para de valer na hora.

Authorization: Bearer fl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Escopos

  • crm:leitura: CRM: sites, resumo, pessoas, jornada e funil.
  • anuncios:leitura: Anúncios: campanhas com gasto, impressões, cliques e eventos.
  • auditorias:leitura: Auditorias: notas e histórico.
  • tarefas:leitura: Tarefas: os tickets do quadro.

Uma chave com sites escolhidos só vê esses sites no CRM, as campanhas cujo link é desses domínios e as auditorias dessas páginas.

3. Rotas

Base: https://farejaleads.com/api/v1. O site aceita o domínio (editaisdobrasil.com) ou o site_id; com um site só na chave, pode ficar de fora. Número sem dado (sem eventos na janela, passo que o CRM não mede, campanha ainda não lida) vem null, não 0.

GET /sites · crm:leitura
Parâmetros: —
Os sites do CRM que a chave enxerga: site_id, nome, domínios.
GET /crm/resumo · crm:leitura
Parâmetros: site (domínio ou site_id), dias (1–90, padrão 30)
visitantes, leads, clientes e porOrigem [{origem, visitantes, leads, clientes}] da janela; e o resumo completo (7 e 30 dias, receita, total) e a jornada por estágio.
GET /crm/pessoas · crm:leitura
Parâmetros: site, estagio (visitante, engajado, lead, cliente, cancelou), desde (ISO 8601), limite (1–200, padrão 50), cursor
pessoas [{id, rotulo, estagio, origem, ultimaVez, jornada}] da última visita para trás, e proximo_cursor.
GET /crm/pessoas/{id} · crm:leitura
Parâmetros: site
A jornada da pessoa: atribuição, sessões e os últimos eventos.
GET /crm/funil · crm:leitura
Parâmetros: site, dias (padrão 30)
etapas [{rotulo, pessoas}] do funil declarado do produto, com o evento e quantas vezes; e a jornada por estágio e por origem.
GET /anuncios/campanhas · anuncios:leitura
Parâmetros: produto ou site (domínio do link do anúncio)
campanhas [{nome, status, gasto, impressoes, cliques, evento, conversoes}], com o evento pelo rótulo do funil declarado.
GET /auditorias · auditorias:leitura
Parâmetros: site (domínio), alvo (URL), limite (1–200, padrão 20)
auditorias [{pagina, nota, delta, motivos[], em}] (mais novas primeiro) e a série de notas por alvo.
GET /tarefas · tarefas:leitura
Parâmetros: estado (a_fazer, fazendo, bloqueada, feito)
Os tickets do quadro de tarefas e a contagem por coluna.

4. Exemplos

curl:

curl -s "https://farejaleads.com/api/v1/crm/resumo?site=meusite.com.br&dias=7" \
  -H "Authorization: Bearer $FAREJALEADS_API_KEY"

fetch, no servidor (Node, Next.js route handler, Cloudflare Worker):

const r = await fetch("https://farejaleads.com/api/v1/crm/pessoas?site=meusite.com.br&limite=20", {
  headers: { Authorization: `Bearer ${process.env.FAREJALEADS_API_KEY}` },
});
if (!r.ok) throw new Error((await r.json()).detail);
const { pessoas, proximo_cursor } = await r.json();
// Próxima página: ...&cursor=${proximo_cursor}

Resposta de /crm/resumo (resumida):

{
  "site": "meusite.com.br",
  "dias": 7,
  "visitantes": 1240,
  "leads": 86,
  "clientes": 9,
  "porOrigem": [{ "origem": "Google (orgânico)", "visitantes": 610, "leads": 40, "clientes": 4 }]
}

5. Limites e erros

60 requisições por minuto por chave. Toda resposta traz RateLimit, RateLimit-Policy e X-RateLimit-*; no 429, espere o Retry-After. Para um painel, guarde a resposta em cache por alguns minutos.

Erros em application/problem+json (RFC 9457), com code estável: nao_autenticado (401: sem chave, chave desconhecida, revogada ou vencida), sem_escopo e site_nao_permitido (403), parametro_invalido e chave_na_url (400), nao_encontrado (404), limite_excedido (429). A lista completa está em /developers.

{
 "status": 403,
 "code": "sem_escopo",
 "detail": "Esta rota pede o escopo anuncios:leitura; a chave tem: crm:leitura.",
 "hint": "Crie uma chave com o escopo pedido no detail (Minha conta → Chaves de API)."
}