Documentação pública da Pulei API

3.1 Links

• Criar: POST /links (campos: longUrl obrigatório; opcionais domainId verificado, slug customizado com domínio, expiresAt, campaignId, UTMs padrão, deep links mobile).
• Listar: GET /links com paginação (page, perPage) e busca (search, source).
• Detalhar: GET /links/{slug}.
• Atualizar: PATCH /links/{slug} (URL de destino, título, domínio, expiração, desabilitar, deep links, campanha).
• Arquivar: DELETE /links/{slug} (desabilita o link).

3.2 Retargeting (Smart Links)

• Regras por país, dispositivo/OS/browser, janela de tempo, quantidade de cliques, fallback de erro e senha.
• Endpoints: GET e PUT /links/{slug}/retargeting.
• As regras são avaliadas em ordem de prioridade; o PUT substitui toda a configuração.
• Body aceita campos singulares (legado) e listas (timeRules, geoRules, deviceRules, clicksRules, errorRules).

3.3 Logs de cliques

• GET /links/{slug}/logs retorna eventos com data/hora, localização aproximada, dispositivo, referer.
• Filtros: range (7d, 30d, mtd, prev_month, ytd), country, city, paginação (page, perPage).

3.4 Analytics agregados

• GET /analytics consolida métricas do time.
• Filtros: range, slug, q (slug ou URL), domain, country, city.
• Retorna resumo, ranking de links, hora do dia, dia da semana, referrers, país, região, dispositivo, browser, OS.

3.5 Exportação de dados (CSV)

• GET /analytics/export gera CSV de cliques com os mesmos filtros de analytics.
• Colunas: slug, long_url, click_at, ip, country, region, city, device, referer.

3.6 Domínios personalizados

• GET /domains lista domínios verificados do time.
• Somente domínios verificados podem receber slugs customizados.

3.7 Campanhas

• POST /campaigns cria campanhas com UTMs padrão.
• GET /campaigns lista as últimas campanhas.
• PATCH /campaigns/{id} atualiza nome/descrição.
• Use campaignId ao criar ou atualizar links para aplicar UTMs automaticamente.

Autenticação base

const API_KEY = process.env.PULEI_API_KEY!;
const BASE_URL = "https://www.pulei.com.br/api/v1";

const authHeaders = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

Links

// Criar um link
await fetch(`${BASE_URL}/links`, {
  method: "POST",
  headers: authHeaders,
  body: JSON.stringify({
    longUrl: "https://meusite.com/oferta",
    domainId: "dominio-verificado-id",
    expiresAt: "2025-12-31T23:59:59Z",
    deepLinkMode: "GENERIC",
    deepLinkTargetScope: "MOBILE_ONLY",
    deepLinkIosUrl: "minhaapp://oferta",
    deepLinkAndroidUrl: "minhaapp://oferta",
    campaignId: "camp-123",
    utm_source: "afiliado",
    utm_medium: "social",
    utm_campaign: "lancamento",
  }),
});

// Listar links do time
const list = await fetch(`${BASE_URL}/links?page=1&perPage=20&search=oferta`, { headers: authHeaders });

// Atualizar um link
await fetch(`${BASE_URL}/links/meu-slug`, {
  method: "PATCH",
  headers: authHeaders,
  body: JSON.stringify({
    longUrl: "https://meusite.com/oferta-atualizada",
    title: "Oferta Black Friday",
    disabled: false,
    disabledUntil: null,
    deepLinkMode: "PER_PLATFORM",
    deepLinkTargetScope: "ALWAYS",
    deepLinkIosUrl: "minhaapp://oferta-ios",
    deepLinkAndroidUrl: "minhaapp://oferta-android",
  }),
});

Retargeting

await fetch(`${BASE_URL}/links/meu-slug/retargeting`, {
  method: "PUT",
  headers: authHeaders,
  body: JSON.stringify({
    timeRules: [
      { startsAt: "2025-11-25T00:00:00Z", targetUrl: "https://meusite.com/pre-black" },
      { startsAt: "2025-11-29T00:00:00Z", targetUrl: "https://meusite.com/black-friday" },
    ],
    geoRules: [
      { country: "BR", targetUrl: "https://meusite.com/br" },
      { country: "US", targetUrl: "https://meusite.com/en" },
    ],
    deviceRules: [
      { device: "MOBILE", targetUrl: "https://m.meusite.com" },
      { device: "DESKTOP", targetUrl: "https://meusite.com/desktop" },
    ],
    clicksRules: [{ threshold: 1000, targetUrl: "https://meusite.com/backup" }],
    errorRules: [{ targetUrl: "https://meusite.com/offline" }],
    passwordRule: { enabled: false },
  }),
});

O PUT sobrescreve toda a configuração de retargeting do link.

Logs e Analytics

// Logs de cliques
await fetch(`${BASE_URL}/links/meu-slug/logs?range=30d&country=BR&page=1&perPage=50`, {
  headers: authHeaders,
});

// Analytics agregados
await fetch(`${BASE_URL}/analytics?range=7d&domain=pulei.com.br&country=BR`, {
  headers: authHeaders,
});

// Exportar CSV
const csv = await fetch(`${BASE_URL}/analytics/export?range=30d&slug=meu-slug`, {
  headers: authHeaders,
});

Domínios e campanhas

// Domínios verificados
await fetch(`${BASE_URL}/domains`, { headers: authHeaders });

// Criar campanha
await fetch(`${BASE_URL}/campaigns`, {
  method: "POST",
  headers: authHeaders,
  body: JSON.stringify({
    name: "Campanha SaaS",
    description: "UTMs padrão para lançamentos",
    defaultUtmSource: "afiliado",
    defaultUtmMedium: "email",
    defaultUtmCampaign: "sprint-1",
  }),
});

// Atualizar campanha
await fetch(`${BASE_URL}/campaigns/camp-123`, {
  method: "PATCH",
  headers: authHeaders,
  body: JSON.stringify({ name: "Campanha SaaS (Q4)" }),
});