Documentazione API

Introduzione

L'API di ShortIO ti permette di creare e gestire URL accorciati programmaticamente. È perfetta per integrare la funzionalità di URL shortening nelle tue applicazioni, bot, automazioni e servizi.

🔐 Autenticazione

Tutte le richieste API richiedono un token di autenticazione passato nell'header HTTP:

X-Shortio-Token: sk_live_abc123def456...

Come Ottenere un Token API: Per richiedere un token API, contatta il supporto tecnico o l'amministratore del servizio. Il token ti verrà fornito in formato sicuro e potrai utilizzarlo immediatamente nelle tue integrazioni.

Sicurezza del Token: Non condividere mai il tuo token API. Ogni token è personale e tracciato. In caso di compromissione, contatta immediatamente il supporto per la revoca e la generazione di un nuovo token.

🌐 Base URL

https://shortio.it/api

📡 Endpoints

GET

/api

Verifica lo stato dell'API e visualizza gli endpoint disponibili.

Esempio di richiesta:

curl -X GET "https://shortio.it/api" \
  -H "X-Shortio-Token: your_api_token_here"

Risposta (200 OK):

{
  "success": true,
  "status": "operational",
  "version": "1.1.0",
  "api": "ShortIO API",
  "database": "connected",
  "timestamp": "2024-11-28 12:00:00",
  "endpoints": {
    "GET /api": "API status",
    "GET /api/{short_code}": "Get URL by short code",
    "POST /api/create": "Create new URL",
    "PUT /api/update/{short_code}": "Update URL by short code",
    "DELETE /api/delete/{short_code}": "Delete URL by short code"
  }
}

GET

/api/{short_code}

Ottieni i dettagli di un URL specifico tramite il suo codice corto.

Esempio di richiesta:

curl -X GET "https://shortio.it/api/abc123" \
  -H "X-Shortio-Token: your_api_token_here"

Risposta (200 OK):

{
  "success": true,
  "data": {
    "original_url": "https://example.com/very-long-url",
    "short_code": "abc123",
    "alias": "promo-2025",
    "short_url": "https://shortio.it/s/abc123",
    "expires_at": "2025-12-31 23:59:59",
    "max_uses": 1000,
    "created_at": "2024-11-28 12:00:00"
  }
}

POST

/api/create

Crea un nuovo URL accorciato con opzioni avanzate.

Parametri del body (JSON):

Campo	Tipo	Obbligatorio	Descrizione
original_url	string	Sì	URL da accorciare (max 2048 caratteri)
alias	string	No	Alias personalizzato (alfanumerico, -, _)
custom_code	string	No	Codice corto personalizzato
expires_at	string	No	Data di scadenza (YYYY-MM-DD HH:MM:SS)
max_uses	integer	No	Numero massimo di utilizzi/click

Esempio di richiesta (base):

curl -X POST "https://shortio.it/api/create" \
  -H "X-Shortio-Token: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/my-long-url"
  }'

Esempio di richiesta (con opzioni avanzate):

curl -X POST "https://shortio.it/api/create" \
  -H "X-Shortio-Token: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/black-friday-promo",
    "alias": "black-friday-2025",
    "expires_at": "2025-12-01 23:59:59",
    "max_uses": 10000
  }'

Risposta (201 Created):

{
  "success": true,
  "data": {
    "original_url": "https://example.com/black-friday-promo",
    "short_code": "xyz789",
    "alias": "black-friday-2025",
    "short_url": "https://shortio.it/s/xyz789",
    "expires_at": "2025-12-01 23:59:59",
    "max_uses": 10000,
    "created_at": "2024-11-28 12:00:00"
  }
}

PUT

/api/update/{short_code}

Aggiorna un URL esistente utilizzando il suo codice corto. Puoi modificare l'URL originale, l'alias, la data di scadenza e il numero massimo di utilizzi.

Parametri del body (JSON):

Campo	Tipo	Descrizione
original_url	string	Nuovo URL di destinazione
alias	string	Nuovo alias personalizzato
expires_at	string	Nuova data di scadenza
max_uses	integer	Nuovo numero massimo di utilizzi

Esempio di richiesta:

curl -X PUT "https://shortio.it/api/update/abc123" \
  -H "X-Shortio-Token: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/updated-url",
    "alias": "new-promo-2025",
    "expires_at": "2025-12-31 23:59:59",
    "max_uses": 5000
  }'

Risposta (200 OK):

{
  "success": true,
  "data": {
    "original_url": "https://example.com/updated-url",
    "short_code": "abc123",
    "alias": "new-promo-2025",
    "short_url": "https://shortio.it/s/abc123",
    "expires_at": "2025-12-31 23:59:59",
    "max_uses": 5000,
    "created_at": "2024-11-28 12:00:00"
  }
}

DELETE

/api/delete/{short_code}

Elimina (soft delete) un URL esistente utilizzando il suo codice corto. L'URL non sarà più accessibile.

Esempio di richiesta:

curl -X DELETE "https://shortio.it/api/delete/abc123" \
  -H "X-Shortio-Token: your_api_token_here"

Risposta (200 OK):

{
  "success": true,
  "message": "URL deleted successfully",
  "data": {
    "short_code": "abc123"
  }
}

❌ Codici di Errore

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized. Invalid or missing API token."
}

400 Bad Request

{
  "success": false,
  "error": "Invalid URL format"
}

404 Not Found

{
  "success": false,
  "error": "URL not found"
}

409 Conflict

{
  "success": false,
  "error": "Alias already exists"
}

💻 Esempi di Codice

● JavaScript

// Crea un nuovo short URL
async function createShortUrl(originalUrl) {
  const response = await fetch('https://shortio.it/api/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shortio-Token': 'your_api_token_here'
    },
    body: JSON.stringify({
      original_url: originalUrl,
      alias: 'my-custom-link',
      expires_at: '2025-12-31 23:59:59',
      max_uses: 1000
    })
  });
  
  const data = await response.json();
  console.log(data.data.short_url);
  return data;
}

// Aggiorna un URL esistente
async function updateShortUrl(shortCode, updates) {
  const response = await fetch(`https://shortio.it/api/update/${shortCode}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'X-Shortio-Token': 'your_api_token_here'
    },
    body: JSON.stringify(updates)
  });
  
  return await response.json();
}

// Elimina un URL
async function deleteShortUrl(shortCode) {
  const response = await fetch(`https://shortio.it/api/delete/${shortCode}`, {
    method: 'DELETE',
    headers: {
      'X-Shortio-Token': 'your_api_token_here'
    }
  });
  
  return await response.json();
}

● Python

import requests

def create_short_url(original_url):
    url = 'https://shortio.it/api/create'
    headers = {
        'X-Shortio-Token': 'your_api_token_here',
        'Content-Type': 'application/json'
    }
    data = {
        'original_url': original_url,
        'alias': 'my-custom-link',
        'expires_at': '2025-12-31 23:59:59',
        'max_uses': 1000
    }
    
    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    print(result['data']['short_url'])
    return result

def update_short_url(short_code, updates):
    url = f'https://shortio.it/api/update/{short_code}'
    headers = {
        'X-Shortio-Token': 'your_api_token_here',
        'Content-Type': 'application/json'
    }
    
    response = requests.put(url, headers=headers, json=updates)
    return response.json()

def delete_short_url(short_code):
    url = f'https://shortio.it/api/delete/{short_code}'
    headers = {
        'X-Shortio-Token': 'your_api_token_here'
    }
    
    response = requests.delete(url, headers=headers)
    return response.json()

● PHP

function createShortUrl($originalUrl) {
    $ch = curl_init('https://shortio.it/api/create');
    
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Shortio-Token: your_api_token_here'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'original_url' => $originalUrl,
        'alias' => 'my-custom-link',
        'expires_at' => '2025-12-31 23:59:59',
        'max_uses' => 1000
    ]));
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    $data = json_decode($response, true);
    echo $data['data']['short_url'];
    return $data;
}

function updateShortUrl($shortCode, $updates) {
    $ch = curl_init("https://shortio.it/api/update/{$shortCode}");
    
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Shortio-Token: your_api_token_here'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($updates));
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

function deleteShortUrl($shortCode) {
    $ch = curl_init("https://shortio.it/api/delete/{$shortCode}");
    
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Shortio-Token: your_api_token_here'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

⚡ Rate Limiting

L'API implementa un rate limiting di 100 richieste per ora per token. Superato questo limite, riceverai un errore 429 (Too Many Requests).

🆘 Supporto

Hai domande o problemi con l'API?

Verifica di aver impostato correttamente l'header X-Shortio-Token
Controlla che l'URL sia valido e non superi i 2048 caratteri
Assicurati che le date di scadenza siano nel futuro
Verifica che il max_uses sia un numero positivo