API abbreviatore di URL: integrate URLW nelle vostre applicazioni

L'API REST URLW vi permette di integrare la creazione, la gestione e l'analisi dei link brevi direttamente nelle vostre applicazioni, script o workflow automatizzati. Che stiate costruendo un CRM, una piattaforma di email marketing o uno strumento interno, l'API URLW si integra in poche righe di codice.

Autenticazione tramite chiave API

Tutte le richieste all'API URLW devono essere autenticate tramite una chiave API trasmessa nell'header Authorization. Per ottenere la vostra chiave:

1. Accedete al vostro account URLW
2. Andate in Impostazioni → API
3. Cliccate su "Genera una nuova chiave API"
4. Copiate e conservate questa chiave in un luogo sicuro — verrà mostrata una sola volta

Trasmettete la vostra chiave in ogni richiesta tramite l'header HTTP:

Authorization: Bearer LA_VOSTRA_CHIAVE_API

Non esponete mai la vostra chiave API in codice lato client (JavaScript front-end, applicazioni mobile). Utilizzate sempre un backend intermediario per le chiamate API.

Primi passi: abbreviare un URL con curl

Ecco come creare il vostro primo link breve tramite l'API URLW con il comando curl:

curl -X POST https://urlw.fr/api/v1/links \
-H "Authorization: Bearer LA_VOSTRA_CHIAVE_API" \
-H "Content-Type: application/json" \
-d '{
"url": "https://esempio.com/il-mio-url-di-destinazione-molto-lungo",
"slug": "mio-link",
"domain": "go.vostro-brand.it"
}'

Risposta in caso di successo (HTTP 201):

{
"id": "lnk_abc123",
"short_url": "https://go.vostro-brand.it/mio-link",
"original_url": "https://esempio.com/il-mio-url-di-destinazione-molto-lungo",
"slug": "mio-link",
"clicks": 0,
"created_at": "2025-06-01T10:00:00Z"
}

Endpoint principali dell'API URLW

L'API URLW espone i seguenti endpoint REST:

• POST /api/v1/links — Creare un nuovo link breve
• GET /api/v1/links — Elencare i vostri link (con paginazione)
• GET /api/v1/links/{id} — Recuperare un link tramite il suo identificatore
• PATCH /api/v1/links/{id} — Modificare un link esistente (URL di destinazione, slug, scadenza)
• DELETE /api/v1/links/{id} — Eliminare un link
• GET /api/v1/links/{id}/stats — Ottenere le statistiche di clic di un link
• POST /api/v1/links/batch — Creare più link in una singola richiesta

La documentazione completa, con parametri, codici di risposta ed esempi per ogni endpoint, è disponibile su /it/docs.

Rate limit e buone pratiche

Per garantire la qualità del servizio a tutti gli utenti, l'API URLW applica dei rate limit in base al vostro piano:

• Piano Starter: 60 richieste al minuto
• Piano Pro: 300 richieste al minuto
• Piano Business: 1.000 richieste al minuto

Quando superate il limite, l'API restituisce una risposta HTTP 429 Too Many Requests con un header Retry-After che indica il tempo di attesa. Implementate un meccanismo di retry con backoff esponenziale nelle vostre applicazioni.

Buone pratiche per un'integrazione robusta:

• Utilizzate l'endpoint batch per creare più link in una singola richiesta invece di moltiplicare le chiamate individuali
• Mettete in cache le risposte dell'API lato applicazione per evitare richieste a ogni visualizzazione
• Gestite sistematicamente i codici di errore HTTP (400, 401, 404, 422, 429, 500) nel vostro codice
• Utilizzate i webhook URLW per ricevere notifiche sugli eventi (clic, scadenza) invece di fare polling all'API

Per iniziare a utilizzare l'API, create il vostro account URLW e consultate la documentazione API completa.