Conexão hospedada (white label)

Ofereça "Conectar Instagram" dentro do seu sistema. Cada usuário seu conecta a conta dele por um link assinado, numa página com a sua marca, sem criar conta no CrazyLeads. A conta vira uma fonte no seu projeto, e você lê perfil, posts e métricas pela API.

O modo funciona em projetos liberados pela equipe do CrazyLeads. Você pode configurar tudo antes; os links passam a valer depois da liberação. Para pedir, fale com o suporte.

Como funciona

o fluxo
Seu servidor                    CrazyLeads (seu projeto)                Instagram
────────────                    ────────────────────────                ─────────
gera o link assinado  ───────▶  /h/{projeto}  (página com a sua marca)
(ref = id do usuário)           [Conectar Instagram] ─────────────────▶  login do usuário
                                "Ligar @conta a {sua marca}?"  ◀──────  autorização
                                cria a fonte do Instagram (ref)
◀── volta ao seu return_url ─── ?status=connected&connection_id=…&sig=…
lê os dados pela API v1, filtrando pelo external_ref

Você usa um projeto para todos os seus usuários. Cada conexão guarda o external_ref, que é o id do usuário no seu sistema (opaco para nós), e vira uma fonte comum do projeto. A página mostra a sua marca, com um rodapé discreto "Conexão operada por CrazyLeads". Na tela de permissão do Instagram aparece o app do CrazyLeads: é a Meta que mostra o app que pede o acesso.

O Instagram só libera esta conexão para contas profissionais (Criador de conteúdo ou Comercial). A página explica isso ao usuário antes do botão e mostra como trocar, que é grátis.

Credenciais

Use uma das duas, conforme o seu caso:

API key do projeto (mais simples)

Em Configurações → Desenvolvedores → Chaves do projeto, crie uma chave de escopo global com a permissão hosted_connections:write. Mande-a em Authorization: Bearer dskey_… (ou X-API-Key). Se a chave tiver lista de IPs, ela vale nestas rotas também. Chave revogada deixa de valer em até 1 minuto.

Token de app parceiro (OAuth)

Para quem já tem um app parceiro: peça o escopo hosted_connections:manage na autorização. A pessoa que autoriza precisa poder editar o projeto.

Passo a passo

1

Configure o modo no projeto

Em Configurações → Desenvolvedores → Conexão hospedada: ligue o modo, dê nome, logo e cor à sua marca e cadastre as URLs de retorno (o ret do link precisa ser igual a uma delas, letra por letra). Se for embutir a página num iframe, cadastre a origem do seu site. Cadastre também os IPs do seu servidor. Depois, clique em Gerar segredo e guarde o kid e o segredo no seu servidor: eles aparecem uma vez só.

2

Gere o link no clique do usuário

O link vale por até 10 minutos e uma vez só. Gere no momento em que o usuário clica em "Conectar Instagram" no seu sistema, só para quem está logado como aquele ref, e redirecione na hora. Você pode assinar no seu servidor (sem chamar a API):

Node.js
import crypto from "node:crypto";

// Gere NO SERVIDOR, no clique do usuário. O segredo nunca vai ao navegador.
export function linkDeConexao({ projeto, kid, segredo, ref, ret, ip }) {
  const exp = Math.floor(Date.now() / 1000) + 600; // até 10 minutos
  const nonce = crypto.randomBytes(18).toString("base64url");
  const canonico = ["v1", projeto, "instagram", ref, String(exp), ret ?? "", nonce, kid, ip ?? ""].join("\n");
  const sig = crypto.createHmac("sha256", segredo).update(canonico).digest("base64url");

  const url = new URL(`https://crazyleads.com.br/h/${projeto}`);
  url.searchParams.set("type", "instagram");
  url.searchParams.set("ref", ref);
  url.searchParams.set("exp", String(exp));
  if (ret) url.searchParams.set("ret", ret);
  url.searchParams.set("nonce", nonce);
  url.searchParams.set("kid", kid);
  if (ip) url.searchParams.set("ip", ip);
  url.searchParams.set("sig", sig);
  return url.toString();
}
Python
import base64, hashlib, hmac, secrets, time
from urllib.parse import urlencode

def link_de_conexao(projeto, kid, segredo, ref, ret=None, ip=None):
    exp = int(time.time()) + 600  # até 10 minutos
    nonce = secrets.token_urlsafe(18)
    canonico = "\n".join(["v1", projeto, "instagram", ref, str(exp), ret or "", nonce, kid, ip or ""])
    sig = base64.urlsafe_b64encode(
        hmac.new(segredo.encode(), canonico.encode(), hashlib.sha256).digest()
    ).rstrip(b"=").decode()
    params = {"type": "instagram", "ref": ref, "exp": exp, "nonce": nonce, "kid": kid, "sig": sig}
    if ret: params["ret"] = ret
    if ip: params["ip"] = ip
    return f"https://crazyleads.com.br/h/{projeto}?" + urlencode(params)

A string assinada é, nesta ordem e separada por quebra de linha: v1, uuid do projeto, instagram, ref, exp, ret, nonce, kid e ip. Os campos opcionais vazios entram como texto vazio. A assinatura é HMAC-SHA256 em base64url, sem =.

Ou peça o link pronto à API, sem guardar o segredo:

POST /api/v1/projects/{projeto}/hosted-links
curl -X POST https://crazyleads.com.br/api/v1/projects/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f/hosted-links \
  -H "Authorization: Bearer dskey_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "criador_42", "return_url": "https://app.seusistema.com/instagram/volta"}'

# 201
{ "url": "https://crazyleads.com.br/h/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f?type=instagram&ref=criador_42&…&sig=…",
  "expires_at": "2026-11-16T18:10:00.000Z" }

Campos: external_ref (obrigatório, até 128 caracteres de A-Z a-z 0-9 . _ : -), return_url e ip (opcionais).

3

O usuário conecta

Ele abre o link, entra com o Instagram numa janela e confirma "Ligar @conta a {sua marca}?". Só aí a fonte é criada e começa a coletar (a primeira coleta sai na hora, depois todo dia). Se a mesma conta já estava ligada no projeto, o acesso é renovado na mesma fonte, e um ref diferente transfere a conta para o novo ref.

4

Receba o retorno e confira a assinatura

O usuário volta ao seu return_url com status (connected, cancelled ou error), connection_id, ref, ts, kid e sig. A assinatura usa o mesmo segredo do link, sobre v1, status, connection_id, ref e ts. Confira antes de confiar, ou confirme pela API:

Node.js
import crypto from "node:crypto";

// Na sua URL de retorno: confira a assinatura ANTES de confiar no status.
export function conferirRetorno(url, segredo) {
  const q = new URL(url).searchParams;
  const ts = Number(q.get("ts"));
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 600) return null; // retorno velho
  const canonico = ["v1", q.get("status"), q.get("connection_id") ?? "", q.get("ref"), String(ts)].join("\n");
  const esperado = crypto.createHmac("sha256", segredo).update(canonico).digest("base64url");
  const sig = q.get("sig") ?? "";
  if (sig.length !== esperado.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(esperado))) return null;
  return { status: q.get("status"), connectionId: q.get("connection_id"), ref: q.get("ref") };
}

Página num iframe: em vez de navegar, ela manda postMessage({ type: "crazyleads:conexao-hospedada", url, status, connection_id, ref, ts, kid, sig }) para a origem do retorno e para as origens cadastradas. Confira event.origin e a assinatura do mesmo jeito.

5

Liste e revogue

GET /api/v1/projects/{projeto}/connections
curl "https://crazyleads.com.br/api/v1/projects/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f/connections?external_ref=criador_42" \
  -H "Authorization: Bearer dskey_SUA_CHAVE"

{ "data": [ { "id": "ckx…", "type": "instagram", "external_ref": "criador_42",
              "source_id": "6f1c…", "ig_user_id": "17841400000000001",
              "username": "ana.cria", "status": "ativa",
              "connected_at": "2026-11-16T18:02:11.000Z", "revoked_at": null } ],
  "next_cursor": null }

Filtros: external_ref, status (ativa ou revogada), cursor e limit (1–200). Com o source_id, leia perfil, posts e métricas pelas rotas de Instagram da API v1. Hoje essas rotas de leitura pedem o token de app parceiro, com o escopo instagram_content:read; a API key cobre gerar links, listar e revogar.

DELETE /api/v1/projects/{projeto}/connections/{id}
curl -X DELETE https://crazyleads.com.br/api/v1/projects/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f/connections/ckx… \
  -H "Authorization: Bearer dskey_SUA_CHAVE"

{ "id": "ckx…", "status": "revogada" }

Revogar apaga a fonte e o acesso do usuário, e pode ser repetido sem erro. Se o usuário tirar o app nas configurações do Instagram, a conexão é revogada sozinha. Quando receber uma revogação, apague também a cópia dos dados dele no seu sistema.

Restrição de IP

Há duas camadas, e você pode usar as duas:

  • IPs do seu servidor: a lista do modo (IP ou faixa CIDR, IPv4 e IPv6) vale para as rotas da API acima. A lista da própria API key também vale. Lista vazia aceita qualquer IP.
  • IP do usuário no link (opcional): mande o IP do usuário no parâmetro ip, que entra na assinatura. A página recusa quem abrir de outra rede. Cuidado com celular, que troca de IP entre 4G e Wi-Fi.

Segurança

  • O segredo e a API key ficam só no seu servidor. Nunca os mande ao navegador.
  • Gere o link só para o usuário logado como aquele ref. Quem tem o link liga uma conta àquele ref; por isso ele vale minutos e uma vez só.
  • Confira a assinatura do retorno e o event.origin no iframe.
  • Para trocar o segredo, gere um novo: o anterior continua valendo por 24 h, e o kid diz qual assinou.
  • Link recusado (assinatura, prazo, já usado, IP) mostra sempre a mesma tela, sem dizer o motivo.

Erros e limites

RespostaQuandoO que fazer
401 invalid_tokenAPI key inválida, vencida ou revogada; ou token de app vencido.Gere outra chave ou renove o token.
403 insufficient_scopeA chave não tem hosted_connections:write (ou o app não tem hosted_connections:manage).Edite a permissão da chave.
403 ip_not_allowedO IP do seu servidor está fora da lista do modo ou da lista da própria chave.Inclua o IP/CIDR nas duas listas.
404 not_foundProjeto que não é o da credencial, conexão inexistente ou modo nunca configurado.Confira o uuid do projeto.
409 project_frozenO projeto está congelado (assinatura): gerar link fica parado.Reative o projeto. Listar e revogar continuam.
409 precondition_failedProjeto ainda não liberado, modo desligado ou sem segredo de assinatura.Ligue o modo e gere o segredo; peça a liberação.
400 invalid_requestexternal_ref, return_url ou ip fora do formato; return_url fora da lista do projeto.A mensagem diz o campo.
429 rate_limitedMais de 120 links por minuto pela mesma credencial, ou chamadas demais do mesmo IP.Respeite o Retry-After.
503 unavailableNão deu para apagar a fonte agora ao revogar.Tente de novo; revogar é idempotente.

Os erros seguem as convenções da API. O projeto tem um limite de contas conectadas (200 por padrão; ajuste em Configurações). Passou dele, o usuário vê o aviso e você recebe status=error no retorno.