Documentazione dell’API

Iniziare

Tutte le richieste passano dall’URL di base https://shortit.fr/api/v1, in HTTPS. I corpi delle richieste vengono inviati in JSON con l’intestazione Content-Type: application/json e l’intestazione Content-Length (curl le imposta da solo). I campi sono in snake_case, le date in formato ISO 8601 in UTC.

Versione 1. Nella versione 1, un campo non viene mai rimosso, rinominato né cambiato di tipo; possono essere aggiunti campi, quindi ignora quelli che non conosci. Una modifica incompatibile avrebbe un nuovo indirizzo (/api/v2) e la versione 1 resterebbe disponibile. Una richiesta che contiene un campo sconosciuto viene rifiutata (400): è voluto, perché un errore di battitura non passi inosservato.

La specifica OpenAPI, generata dal codice, è pubblica: /api/v1/openapi.json. Nessun indirizzo IP viene mai restituito né conservato.

curl https://shortit.fr/api/v1/me \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "email": "camille@example.com",
  "links": 6,
  "links_limit": 1000
}

Autenticazione

Ogni richiesta deve riportare la tua chiave nell’intestazione Authorization, preceduta da «Bearer ». Una chiave revocata, malformata o assente restituisce un errore 401. Una chiave non viene mai trasmessa nell’indirizzo, e l’API non legge alcun cookie.

Le chiavi si creano in Impostazioni (5 al massimo). Una chiave viene mostrata una sola volta, alla sua creazione: ne viene conservata solo l’impronta. Non scade: vale fino alla sua revoca, che è immediata. Le chiavi iniziano con shortit_.

Non mettere mai una chiave in codice pubblico o lato browser: usala da un server o da uno script. L’API non invia intestazioni CORS. L’account deve avere un indirizzo verificato e non essere sospeso.

curl https://shortit.fr/api/v1/links \
  -H "Authorization: Bearer shortit_…"

{
  "error": {
    "code": "unauthorized",
    "message": "Clé absente ou révoquée."
  }
}

Creare un link

Campi del corpo: destination (obbligatorio, http o https, al massimo 2 048 caratteri); alias (da 3 a 32 lettere, cifre o trattini, generato se omesso); title (al massimo 120 caratteri); expires_at (data ISO 8601 nel futuro); password (da 6 a 128 caratteri, mai restituita: la risposta indica solo has_password); domain (uno dei tuoi domini personalizzati attivi, vedi I miei domini; se assente: shortit.fr).

Le destinazioni vengono controllate come nell’interfaccia: indirizzi privati, indirizzi IP diretti, altri riduttori di link e siti segnalati come pericolosi vengono rifiutati (422). I limiti di creazione sono gli stessi dell’interfaccia: 10 all’ora e 50 al giorno, poi 429.

Offerta Pro: max_clicks (da 1 a 10 000 000) limita il numero di clic; raggiunto il limite, il link risponde come un link scaduto. La risposta indica max_clicks e remaining_clicks (null senza limite). Un account gratuito che invia max_clicks riceve 403 pro_required.

curl -X POST https://shortit.fr/api/v1/links \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://exemple-atelier.fr/inscriptions/printemps-2026","alias":"atelier26","title":"Atelier printemps"}'

{
  "alias": "atelier26",
  "domain": "shortit.fr",
  "short_url": "https://shortit.fr/atelier26",
  "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
  "title": "Atelier printemps",
  "status": "active",
  "expires_at": null,
  "has_password": false,
  "created_at": "2026-09-14T09:12:00.000Z",
  "max_clicks": null,
  "remaining_clicks": null,
  "tags": []
}

Leggere un link

Un link si identifica con il suo alias, senza distinzione tra maiuscole e minuscole. Due domini possono avere lo stesso alias: per un link su uno dei tuoi domini personalizzati, aggiungi il parametro domain (ad esempio ?domain=go.miosito.it) per leggere, modificare, eliminare o ottenere le statistiche; senza, si tratta del link di shortit.fr. Un link di un altro account e un link inesistente ricevono la stessa risposta: 404 not_found.

curl https://shortit.fr/api/v1/links/atelier26 \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "alias": "atelier26",
  "domain": "shortit.fr",
  "short_url": "https://shortit.fr/atelier26",
  "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
  "title": "Atelier printemps",
  "status": "active",
  "expires_at": null,
  "has_password": false,
  "created_at": "2026-09-14T09:12:00.000Z",
  "max_clicks": null,
  "remaining_clicks": null,
  "tags": []
}

Elencare i miei link

Dal più recente al più vecchio, tramite cursore: finché next non è null, passa il suo valore nel parametro cursor per ottenere la pagina successiva. Il cursore è opaco; resta valido anche se vengono creati o eliminati link tra una pagina e l’altra. Parametri: limit (da 1 a 100, 20 per impostazione predefinita), cursor, status (active, disabled, expired o flagged).

curl "https://shortit.fr/api/v1/links?status=active&limit=20" \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "data": [
    {
      "alias": "atelier26",
      "domain": "shortit.fr",
      "short_url": "https://shortit.fr/atelier26",
      "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
      "title": "Atelier printemps",
      "status": "active",
      "expires_at": null,
      "has_password": false,
      "created_at": "2026-09-14T09:12:00.000Z",
      "max_clicks": null,
      "remaining_clicks": null,
      "tags": []
    }
  ],
  "next": null
}

Modificare

Campi modificabili: destination, title (null lo cancella), expires_at (null lo rimuove), password (un testo la cambia, null la rimuove) e status (active o disabled). Cambiano solo i campi inviati. L’alias non cambia mai. Un link segnalato non si può modificare (409 link_flagged) e un link disattivato per motivi di sicurezza non si riattiva (409 link_locked).

Offerta Pro: max_clicks imposta o cambia il limite di clic e il relativo contatore riparte da zero (alzare il limite di un link che l'ha raggiunto lo rimette in servizio); null rimuove il limite.

Piano Pro: le regole di reindirizzamento (al massimo 5) si leggono con GET /api/v1/links/ALIAS/rules e si sostituiscono con PUT sullo stesso indirizzo, con il corpo {"rules":[{"type":"country","value":"FR","destination":"https://…"}]}. type è country (codice paese ISO, « FR ») o device (mobile, tablet o desktop); vince la prima regola che corrisponde al visitatore, altrimenti si usa la destinazione del link. Ogni destinazione è controllata come quella del link (422). Su un link con 100 clic o più, la modifica si fa dalla dashboard (403 confirmation_required).

curl -X PATCH https://shortit.fr/api/v1/links/atelier26 \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

{
  "alias": "atelier26",
  "domain": "shortit.fr",
  "short_url": "https://shortit.fr/atelier26",
  "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
  "title": "Atelier printemps",
  "status": "disabled",
  "expires_at": null,
  "has_password": false,
  "created_at": "2026-09-14T09:12:00.000Z",
  "max_clicks": null,
  "remaining_clicks": null,
  "tags": []
}

Eliminare

curl -X DELETE https://shortit.fr/api/v1/links/atelier26 \
  -H "Authorization: Bearer VOTRE_CLE"

(corpo vuoto)

Statistiche di un link

Gli ultimi 30 giorni (giorni di Europe/Paris, dal più vecchio a oggi) e il totale dalla creazione. unique_visitors è la somma dei visitatori unici di ogni giorno: un visitatore tornato per tre giorni conta tre volte (nessun identificativo duraturo viene conservato). variation_pct confronta con il periodo precedente e vale null quando non esiste.

Ogni ripartizione (countries, referrers, devices, browsers) è ordinata per clic decrescenti e limitata a 5 righe. value è il codice del paese, il dominio di provenienza, il dispositivo o il browser; null significa «sconosciuto» oppure, con other a true, «altri» (i valori meno frequenti, raggruppati).

curl https://shortit.fr/api/v1/links/atelier26/stats \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "alias": "atelier26",
  "period_days": 30,
  "clicks": 1397,
  "unique_visitors": 1006,
  "total_clicks": 2310,
  "variation_pct": 12.4,
  "days": [
    {
      "date": "2026-09-12",
      "clicks": 61
    },
    {
      "date": "2026-09-13",
      "clicks": 48
    }
  ],
  "countries": [
    {
      "value": "FR",
      "clicks": 925
    },
    {
      "value": "BE",
      "clicks": 201
    },
    {
      "value": null,
      "clicks": 271,
      "other": true
    }
  ],
  "referrers": [
    {
      "value": "instagram.com",
      "clicks": 512
    },
    {
      "value": null,
      "clicks": 885
    }
  ],
  "devices": [
    {
      "value": "mobile",
      "clicks": 944
    },
    {
      "value": "desktop",
      "clicks": 453
    }
  ],
  "browsers": [
    {
      "value": "Safari",
      "clicks": 601
    },
    {
      "value": "Chrome",
      "clicks": 796
    }
  ]
}

I miei domini

Stato di ogni dominio: pending_dns (in attesa dei tuoi record DNS), verified (proprietà verificata), cert_pending (certificato in corso), active (il dominio reindirizza), error (la verifica è fallita o si è interrotta), disabled (disattivato: un record è scomparso, o decisione dell’amministratore).

curl https://shortit.fr/api/v1/domains \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "data": [
    {
      "name": "go.camille.fr",
      "status": "active",
      "created_at": "2026-09-02T08:00:00.000Z"
    },
    {
      "name": "liens.exemple-asso.fr",
      "status": "pending_dns",
      "created_at": "2026-09-14T09:12:00.000Z"
    }
  ]
}

Limiti ed errori

Ogni chiave è limitata a 30 richieste al minuto (300 con l'offerta Pro, in arrivo). Oltre questo limite, l'API risponde 429 con l'intestazione Retry-After, che indica in secondi il tempo da attendere prima del prossimo tentativo. Trenta chiavi rifiutate in un minuto dallo stesso indirizzo fanno rifiutare quell'indirizzo per il resto del minuto.

Ogni errore ha lo stesso corpo: { "error": { "code", "message" } }, con in più field e reason per un rifiuto di validazione (422). Il codice è stabile; il messaggio è destinato a una persona e può cambiare. Codici:

unauthorized (401) : Clé absente, mal formée ou révoquée.

email_not_verified (403) : L'adresse e-mail du compte n'est pas vérifiée.

account_suspended (403) : Le compte est suspendu.

link_limit_reached (403) : Le plafond de liens du compte est atteint.

pro_required (403) : Cette fonction (limite de clics, règles de redirection…) est réservée aux comptes de l'offre Pro.

confirmation_required (403) : Ce lien a beaucoup de clics : changer sa destination ou ses règles de redirection, ou le supprimer, se fait depuis le tableau de bord, avec un code reçu par e-mail.

not_found (404) : Lien introuvable, ou qui n'est pas à vous.

link_flagged (409) : Le lien est signalé : il ne se modifie ni ne se supprime.

link_locked (409) : Le lien a été désactivé pour un motif de sécurité : il ne se réactive pas.

invalid_json (400) : Le corps n'est pas du JSON valide.

invalid_request (400) : Requête invalide : champ inconnu, type inattendu ou paramètre hors limites.

validation_failed (422) : Une valeur est refusée : le corps porte field et reason.

payload_too_large (413) : Corps de plus de 16 Ko.

length_required (411) : L'en-tête Content-Length est obligatoire avec un corps.

unsupported_media_type (415) : Content-Type : application/json obligatoire avec un corps.

rate_limited (429) : Plus de requêtes par minute que l'offre ne le permet (30 en gratuit, 300 en Pro) avec cette clé : voir Retry-After.

internal_error (500) : Erreur du serveur. Réessayez ; elle ne détaille rien.

{
  "error": {
    "code": "rate_limited",
    "message": "Trop de requêtes. Réessayez dans 12 secondes."
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Déjà pris, choisissez-en un autre.",
    "field": "alias",
    "reason": "taken"
  }
}