Encurtador de URLs em Lote: Importe Links do Google Sheets

A importação em lote do Elido cria até 100 links curtos por lote a partir de uma lista de linhas url, slug, title. Você pode colar as linhas do Google Sheets no painel, enviá-las como CSV ou chamar a API em lote a partir do Apps Script. As tags UTM não são uma coluna de importação separada: você monta a URL final já marcada na planilha, e o Elido a guarda como destino.

Isso é mais restrito do que alguns tutoriais prometem (incluindo uma versão anterior deste), então este post se limita ao que o código faz hoje. Se você veio atrás de um modo dry run, de flags para pular em caso de conflito ou de um upload de 10.000 linhas, isso ainda não existe; está registrado como trabalho planejado e marcado como tal mais abaixo.

Para o quadro mais amplo de UTM, o cornerstone de rastreamento com UTM cobre templates e encaminhamento de conversões no lado do servidor. Este post é a fatia que vai da planilha aos links curtos.

TL;DR

• Uma planilha por campanha. Colunas: final_url (montada com uma fórmula, UTMs incluídos), slug, title.
• Caminho pelo painel: New link, depois a aba Bulk (colar) ou a aba CSV (enviar arquivo). Ambas aceitam 100 links por lote.
• Caminho pela API: POST /v1/links/bulk com um corpo JSON de até 100 itens. Os itens aceitam destination_url, slug, title, tags.
• Cada linha tem sucesso ou falha por conta própria. Um slug já usado faz falhar apenas aquela linha.
• Ainda sem dry run (planejado). Confira algumas linhas depois do primeiro lote.

Monte a planilha

O Elido lê três coisas por link: destino, slug, título. Mantenha as colunas de trabalho à esquerda e uma coluna de saída à direita.

A fórmula de final_url faz o trabalho de UTM que o Elido não faz:

=TRIM(A2) & IF(ISNUMBER(FIND("?", A2)), "&", "?")
  & "utm_source=" & ENCODEURL(B2)
  & "&utm_medium=" & ENCODEURL(C2)
  & "&utm_campaign=" & ENCODEURL(D2)

Fazer isso na planilha tem um benefício colateral: o destino que você revisa é o destino que vai ao ar. Nada é reescrito depois. Um destino que já carrega um ? é estendido com & em vez de quebrado.

A própria orientação do Google é sempre definir utm_source, utm_medium e utm_campaign ao marcar uma URL; sem eles, os relatórios mostram "(not set)" (ajuda do Google Analytics, acessada em 2026-10-09). Adicione uma coluna de verificação como =IF(OR(B2="",C2="",D2=""),"missing UTM","ok") e filtre por ela antes de exportar. Isso substitui o aviso de dry run que outras ferramentas dão.

Caminho 1: colar no painel (aba Bulk)

Abra New link e mude para Bulk. A área de texto aceita um link por linha:

https://shop.example/de?utm_source=newsletter&utm_medium=email&utm_campaign=q2-spring, q2-hero-de, Hero DE
https://shop.example/fr?utm_source=newsletter&utm_medium=email&utm_campaign=q2-spring, q2-hero-fr, Hero FR

O parser divide cada linha nas vírgulas: a primeira parte é a URL, a segunda o slug, e tudo o que vem depois é o título. Linhas em branco e linhas que começam com # são ignoradas. Isso tem duas consequências para planilhas:

• Vírgulas dentro de uma URL de destino quebram a linha. Se um valor de UTM contiver uma vírgula, codifique-a como %2C (o ENCODEURL da fórmula acima já faz isso).
• Colar do Sheets gera células separadas por tabulação, não por vírgulas. Monte uma linha unida por vírgulas para cada linha em uma coluna auxiliar, por exemplo =E2 & ", " & F2 & ", " & G2, e copie essa única coluna.

Depois da importação, a janela mostra o número de links criados e o de falhas, com cada linha que falhou e o motivo expansíveis logo abaixo.

Caminho 2: upload de CSV (aba CSV)

Baixe a planilha como CSV (Arquivo, Fazer download, Valores separados por vírgula) com as colunas na ordem url, slug, title e envie na aba CSV. O arquivo é lido no seu navegador e enviado no mesmo lote de 100 links da aba de colar. Se a primeira linha não começar com http, ela é tratada como cabeçalho e descartada.

O leitor de CSV é uma divisão simples por vírgulas, não um parser de CSV completo. Campos entre aspas que contêm vírgulas não são entendidos, então mantenha os títulos sem vírgulas, ou o título será cortado. Se você precisa de mais de 100 linhas, divida o arquivo em blocos de 100.

Se o briefing mora no Excel, como encurtar URLs no Excel cobre os caminhos por lá.

Caminho 3: a API a partir do Apps Script

Para uma planilha que se enche ao longo da semana, chame a API. O endpoint é POST https://api.elido.app/v1/links/bulk. O token é um personal access token ou uma chave de API do workspace enviada como Authorization: Bearer ..., e uma chave vinculada ao workspace permite que a chamada omita workspace_id e domain_id (o domínio padrão do workspace é usado). A autenticação está descrita na documentação da API, em Authentication.

curl -X POST https://api.elido.app/v1/links/bulk \
  -H "Authorization: Bearer $ELIDO_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      { "destination_url": "https://shop.example/de?utm_source=newsletter&utm_medium=email&utm_campaign=q2-spring",
        "slug": "q2-hero-de", "title": "Hero DE", "tags": ["q2-spring", "email"] }
    ]
  }'

A resposta informa ok, failed e um array items com uma entrada por linha de entrada, em ordem, cada uma marcada como ok ou error. Um slug já usado retorna slug already exists for this domain apenas naquela linha. O cabeçalho Idempotency-Key é respeitado por 24 horas: a mesma chave com o mesmo corpo reproduz a resposta original em vez de criar os links duas vezes (veja Idempotency na documentação da API).

Todo link criado também entra numa fila para uma verificação de segurança assíncrona, então uma importação em lote não espera pelo scanner.

// Google Apps Script: send new sheet rows to Elido's bulk endpoint.
// Trigger: time-driven, hourly. Batches of 100 (the API maximum).
function importNewLinks() {
  const sheet =
    SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Q2 Spring");
  const data = sheet.getDataRange().getValues();
  const h = data[0];
  const urlCol = h.indexOf("final_url");
  const slugCol = h.indexOf("slug");
  const titleCol = h.indexOf("title");
  const doneCol = h.indexOf("short_link");

  const pending = [];
  for (let i = 1; i < data.length && pending.length < 100; i++) {
    if (data[i][urlCol] && !data[i][doneCol]) pending.push(i);
  }
  if (!pending.length) return;

  const links = pending.map((i) => ({
    destination_url: data[i][urlCol],
    slug: data[i][slugCol] || undefined,
    title: data[i][titleCol] || undefined,
  }));

  const resp = UrlFetchApp.fetch("https://api.elido.app/v1/links/bulk", {
    method: "post",
    contentType: "application/json",
    headers: {
      Authorization:
        "Bearer " +
        PropertiesService.getScriptProperties().getProperty("ELIDO_TOKEN"),
    },
    payload: JSON.stringify({ links }),
    muteHttpExceptions: true,
  });
  if (resp.getResponseCode() !== 200) {
    console.error(resp.getContentText());
    return;
  }

  JSON.parse(resp.getContentText()).items.forEach((item) => {
    const row = pending[item.index] + 1;
    const cell = sheet.getRange(row, doneCol + 1);
    cell.setValue(
      item.status === "ok" ? item.link.slug : "ERROR: " + item.error,
    );
  });
}

Notas sobre o script:

• Ele grava de volta o slug (ou o texto do erro), não uma URL completa. Anteponha o seu domínio curto em uma coluna de fórmula se quiser links clicáveis. Linhas com texto de erro em short_link são puladas na próxima execução, então limpe a célula depois de corrigir o slug.
• Mantenha o token nas propriedades do script, não no código.
• Os limites do Apps Script para contas pessoais são 20.000 chamadas de URL Fetch por dia, 6 minutos por execução e 90 minutos de tempo de execução de gatilhos por dia (contas Workspace: 100.000 chamadas, 6 horas) (cotas do Apps Script, acessadas em 2026-10-09). Uma tarefa horária enviando 100 links por chamada fica muito abaixo disso.
• O limite de taxa da API do Elido se aplica por cima, por token e por workspace; veja Rate Limits na documentação da API.

Slugs e tags

Slugs. Coloque um prefixo nos slugs de campanha (q2-, jun26-) para que não colidam com links mais antigos. Uma colisão é informada por linha e o resto do lote passa, então reexecutar a mesma planilha retorna erros para as linhas que já existem em vez de duplicá-las. Deixar o slug em branco faz o Elido gerar um.

Tags. As abas Bulk e CSV do painel não definem tags; a API define, pelo array tags. Tags são strings simples, então uma convenção dimension:value (channel:email) é apenas um hábito de nomenclatura que você impõe na planilha, por exemplo com ="channel:"&C2. Para ver como as campanhas agrupam cliques, veja o recurso de campanhas.

O que ainda não foi construído

Isto foi descrito em uma versão anterior deste post e não existe no produto hoje:

• Uma pré-visualização dry run dos links resolvidos e dos conflitos antes de confirmar. Planejado.
• Modos de conflito (pular, falhar, substituir) para slugs existentes. Planejado; hoje um slug já usado é um erro por linha.
• Colunas de UTM e um template de UTM do workspace aplicado durante a importação. Planejado; use a fórmula da planilha acima.
• Lotes maiores (10.000 linhas) e um upload assíncrono com relatório de status. Planejado; o limite é 100 por requisição.
• Tags diretamente nas abas de importação do painel. Planejado.

Até o dry run existir, confira a primeira e a última linha do primeiro lote no painel antes de publicar os links.

Para onde ir a seguir

Defina primeiro um domínio padrão e a identidade visual com setup-branded-short-links. Para a atribuição depois do clique, rastreamento de conversões no lado do servidor cobre como funciona o encaminhamento de conversões para Meta e GA4; o próprio Elido ainda não encaminha compras para eles. O fluxo do profissional de marketing de ponta a ponta está em solutions/marketers e no recurso de campanhas.

Relacionados no Blog

• Como encurtar URLs no Excel: quatro caminhos que funcionam
• Rastreie parâmetros UTM de ponta a ponta
• Configure links curtos com a sua marca
• Rastreamento de conversões no lado do servidor