Bulk URL Shortener: Importa Link da Google Sheets

L'import in blocco di Elido crea fino a 100 link brevi per lotto da un elenco di righe url, slug, title. Puoi incollare le righe da Google Sheets nella dashboard, caricarle come CSV o chiamare l'API bulk da Apps Script. I tag UTM non sono una colonna di import separata: costruisci l'URL finale con i tag nel foglio, ed Elido lo memorizza come destinazione.

È un perimetro più stretto di quanto promettano alcuni tutorial (compresa una versione precedente di questo), quindi questo articolo si attiene a ciò che il codice fa oggi. Se cercavi una modalità dry run, flag di skip-on-conflict o un upload da 10.000 righe, non esistono ancora; sono tracciati come lavoro pianificato e indicati come tali più sotto.

Per il quadro UTM più ampio, il cornerstone sul tracciamento UTM copre i template e l'inoltro lato server delle conversioni. Questo articolo è la fetta dal foglio ai link brevi.

In sintesi

• Un foglio per campagna. Colonne: final_url (costruita con una formula, UTM inclusi), slug, title.
• Percorso dashboard: New link, poi la scheda Bulk (incolla) o la scheda CSV (carica). Entrambe accettano 100 link per lotto.
• Percorso API: POST /v1/links/bulk con un corpo JSON di fino a 100 elementi. Gli elementi accettano destination_url, slug, title, tags.
• Ogni riga riesce o fallisce da sola. Uno slug già occupato fa fallire solo quella riga.
• Ancora nessun dry run (pianificato). Controlla invece una manciata di righe dopo il primo lotto.

Costruisci il foglio

Elido legge tre cose per link: destinazione, slug, titolo. Tieni le colonne di lavoro a sinistra e una colonna di output a destra.

La formula di final_url fa il lavoro UTM che Elido non fa:

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

Farlo nel foglio ha un vantaggio collaterale: la destinazione che rivedi è la destinazione che parte. Niente viene riscritto a posteriori, e una destinazione che porta già un ? viene estesa con & anziché rotta.

L'indicazione di Google è di impostare sempre utm_source, utm_medium e utm_campaign quando tagghi un URL; senza di essi i report mostrano "(not set)" (guida di Google Analytics, consultata il 2026-10-09). Aggiungi una colonna di controllo come =IF(OR(B2="",C2="",D2=""),"missing UTM","ok") e filtra su di essa prima di esportare. Sostituisce l'avviso di dry run che altri strumenti ti danno.

Percorso 1: incolla nella dashboard (scheda Bulk)

Apri New link e passa a Bulk. L'area di testo accetta un link per riga:

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

Il parser divide ogni riga sulle virgole: la prima parte è l'URL, la seconda lo slug, tutto il resto è il titolo. Le righe vuote e quelle che iniziano con # vengono ignorate. Per i fogli questo ha due conseguenze:

• Le virgole dentro un URL di destinazione rompono la riga. Se un valore UTM contiene una virgola, codificala come %2C (l'ENCODEURL della formula qui sopra lo fa già).
• Incollare da Sheets dà celle separate da tabulazioni, non da virgole. Costruisci una riga unita da virgole per ogni riga in una colonna di supporto, per esempio =E2 & ", " & F2 & ", " & G2, e copia quell'unica colonna.

Dopo l'import la finestra mostra il numero di link creati e quello dei falliti, con ogni riga fallita e il suo motivo espandibili sotto.

Percorso 2: caricamento CSV (scheda CSV)

Scarica il foglio come CSV (File, Scarica, Valori separati da virgola) con le colonne nell'ordine url, slug, title e caricalo nella scheda CSV. Il file viene letto nel tuo browser e inviato nello stesso lotto da 100 link della scheda di incolla. Se la prima riga non inizia con http, viene trattata come intestazione e scartata.

Il lettore CSV è una semplice divisione sulle virgole, non un parser CSV completo. I campi tra virgolette che contengono virgole non vengono compresi, quindi evita virgole nei titoli, altrimenti il titolo viene troncato. Se servono più di 100 righe, dividi il file in blocchi da 100.

Se il brief vive in Excel, come accorciare gli URL in Excel copre i percorsi lì disponibili.

Percorso 3: l'API da Apps Script

Per un foglio che si riempie per tutta la settimana, chiama l'API. L'endpoint è POST https://api.elido.app/v1/links/bulk. Il token è un personal access token o una API key del workspace inviata come Authorization: Bearer ..., e una chiave legata al workspace permette alla chiamata di omettere workspace_id e domain_id (viene usato il dominio predefinito del workspace). L'autenticazione è descritta nella documentazione API alla voce 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"] }
    ]
  }'

La risposta riporta ok, failed e un array items con una voce per ogni riga di input, in ordine, ciascuna contrassegnata ok o error. Uno slug già occupato restituisce slug already exists for this domain solo su quella riga. L'header Idempotency-Key viene rispettato per 24 ore: la stessa chiave con lo stesso corpo riproduce la risposta originale invece di creare i link due volte (vedi Idempotency nella documentazione API).

Ogni link creato viene inoltre messo in coda per una scansione di sicurezza asincrona, quindi un import in blocco non attende lo 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,
    );
  });
}

Note sullo script:

• Riscrive lo slug (o il testo dell'errore), non un URL completo. Anteponi il tuo dominio breve in una colonna con formula se vuoi link cliccabili. Le righe con un testo di errore in short_link vengono saltate all'esecuzione successiva, quindi svuota la cella dopo aver corretto lo slug.
• Tieni il token nelle proprietà dello script, non nel codice.
• I limiti di Apps Script per gli account consumer sono 20.000 chiamate URL Fetch al giorno, 6 minuti per esecuzione e 90 minuti di runtime dei trigger al giorno (account Workspace: 100.000 chiamate, 6 ore) (quote di Apps Script, consultate il 2026-10-09). Un job orario che invia 100 link per chiamata resta molto al di sotto.
• Il rate limit dell'API di Elido si applica in aggiunta, per token e per workspace; vedi Rate Limits nella documentazione API.

Slug e tag

Slug. Usa un prefisso per gli slug di campagna (q2-, jun26-) così non collidono con link più vecchi. Una collisione viene segnalata per riga e il resto del lotto passa, quindi rieseguire lo stesso foglio restituisce errori per le righe già esistenti anziché duplicarle. Lasciare lo slug vuoto fa sì che Elido ne generi uno.

Tag. Le schede Bulk e CSV della dashboard non impostano i tag; l'API sì, tramite l'array tags. I tag sono semplici stringhe, quindi una convenzione dimension:value (channel:email) è solo un'abitudine di denominazione che applichi nel foglio, per esempio con ="channel:"&C2. Per come le campagne raggruppano i clic, vedi la funzione campagne.

Cosa non è ancora stato costruito

Queste cose erano descritte in una versione precedente di questo articolo e oggi non esistono nel prodotto:

• Un'anteprima dry run dei link risolti e dei conflitti prima della conferma. Pianificata.
• Le modalità di conflitto (skip, fail, replace) per gli slug esistenti. Pianificate; oggi uno slug occupato è un errore per riga.
• Le colonne UTM e un template UTM del workspace applicato durante l'import. Pianificati; usa la formula del foglio qui sopra.
• Lotti più grandi (10.000 righe) e un upload asincrono con report di stato. Pianificati; il limite è 100 per richiesta.
• Tag direttamente nelle schede di import della dashboard. Pianificati.

Finché il dry run non esiste, controlla a campione la prima e l'ultima riga del primo lotto nella dashboard prima di pubblicare i link.

Dove andare dopo

Imposta prima un dominio predefinito e il branding con setup-branded-short-links. Per l'attribuzione dopo il clic, il tracciamento delle conversioni lato server copre come funziona l'inoltro delle conversioni a Meta e GA4; Elido stesso non vi inoltra ancora gli acquisti. Il flusso completo per i marketer è su solutions/marketers e nella funzione campagne.

Altri articoli del blog

• Come accorciare gli URL in Excel: quattro percorsi che funzionano
• Tracciare i parametri UTM end to end
• Configurare link brevi con il tuo brand
• Tracciamento delle conversioni lato server