Yero
IT | EN
Inizia gratis
Developer Docs

API & MCP Server

Integra Yero nelle tue applicazioni con la REST API. Connetti Claude e altri sistemi AI tramite il server MCP.

Autenticazione

Tutte le API richiedono un token Bearer. Puoi crearne uno dalla dashboard.

Creare un token
  1. Accedi alla dashboard → API Token nella sidebar
  2. Assegna un nome al token e seleziona i permessi (scope) necessari
  3. Clicca Crea token e copia subito il valore — non sarà più visibile

I token non scadono automaticamente. Revocali dalla stessa pagina quando non servono più.

Header richiesto
Authorization: Bearer YOUR_TOKEN_HERE
links:read

Lettura link

Elenco e dettaglio dei tuoi link.

links:write

Scrittura link

Creazione, modifica ed eliminazione.

stats:read

Statistiche

Accesso ai dati di click e analytics.

Base URL

https://yero.it/api/v1

Tutte le risposte sono in application/json. Rate limit: 50 richieste/giorno per token.

Headers restituiti: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoint

GET /api/v1/user links:read

Utente corrente

Restituisce le informazioni dell'account associato al token.

GET /api/v1/links links:read

Elenco link

Lista paginata dei tuoi link. Parametri: ?page=1

POST /api/v1/links links:write

Crea link

Crea un nuovo link breve. Corpo JSON: target_url (required), slug, expires_at, max_clicks, password, notes.

GET /api/v1/links/{id} links:read

Dettaglio link

Restituisce un singolo link tramite il suo UUID.

PATCH /api/v1/links/{id} links:write

Aggiorna link

Aggiorna target_url, expires_at, max_clicks, password, notes.

DELETE /api/v1/links/{id} links:write

Elimina link

Elimina definitivamente il link. Risposta: 204 No Content.

GET /api/v1/links/{id}/stats stats:read

Statistiche link

Statistiche di click per un link. Parametro: ?days=7|30|90|365 (default 30).

GET /api/v1/stats stats:read

Statistiche globali

Panoramica di tutti i tuoi link. Parametro: ?days=7|30|90|365 (default 30).

GET /api/v1/qrcodes links:read

Elenco QR code

Lista dei QR code generati.

Esempio — crea un link
curl -X POST https://yero.it/api/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com/una-pagina-lunga",
    "slug": "prova",
    "expires_at": "2026-12-31T23:59:59",
    "notes": "Campagna maggio"
  }'
Risposta
{
  "data": {
    "id": "0196a1b2-...",
    "slug": "prova",
    "short_url": "https://yero.it/prova",
    "target_url": "https://example.com/una-pagina-lunga",
    "clicks_count": 0,
    "is_available": true,
    "expires_at": "2026-12-31T23:59:59.000000Z",
    "created_at": "2026-05-12T10:00:00.000000Z"
  }
}

Errori

Codice Significato
401 Non autenticato — token mancante o non valido.
403 Scope insufficiente — il token non ha il permesso richiesto.
404 Risorsa non trovata.
422 Dati di input non validi — risposta con dettagli dei campi.
429 Rate limit raggiunto — riprova domani.
500 Errore interno del server.

MCP Server

Il Model Context Protocol (MCP) è uno standard aperto di Anthropic che permette ad assistenti AI come Claude di interagire con servizi esterni tramite strumenti (tools). Yero espone un server MCP che puoi collegare direttamente a Claude Desktop o ad altri client compatibili.

Endpoint MCP: POST https://yero.it/api/mcp Autenticazione: OAuth 2.0 (Claude Desktop) oppure Bearer token (altri client).

Tool disponibili

shorten_url

Accorcia un URL e restituisce il link breve.

links:write

url (required), slug (optional)

list_links

Elenca i tuoi link con paginazione.

links:read

page (optional), per_page (optional, max 50)

get_stats

Statistiche di click degli ultimi 30 giorni.

stats:read

slug (required)

delete_link

Elimina definitivamente un link.

links:write

slug (required)

create_qr

Restituisce il link al creatore QR code.

links:write

url (required)

Come si usa con Claude Desktop

Una volta connesso, parla con Claude in linguaggio naturale. Non devi invocare gli strumenti manualmente.

"Accorcia questo URL: https://esempio.com/pagina-lunga"

→ shorten_url

"Accorcia https://esempio.com con slug 'promo'"

→ shorten_url + slug personalizzato

"Mostrami i miei ultimi 10 link"

→ list_links

"Quanti click ha lo slug 'promo' negli ultimi 30 giorni?"

→ get_stats

"Cancella il link con slug 'promo'"

→ delete_link

"Crea un QR code per https://esempio.com"

→ create_qr

Connettere Claude Desktop (OAuth 2.0)

Claude Desktop usa OAuth 2.0 con PKCE per autenticarsi. Non serve inserire token manualmente: il browser si apre automaticamente per autorizzare l'accesso.

  1. 1

    Recupera il Client ID

    Vai su Impostazioni → API Token. Trovi la card "Connetti Claude Desktop (MCP)" con il Server URL e il Client ID da copiare.

  2. 2

    Aggiungi il server in Claude Desktop

    Apri Claude Desktop → Impostazioni → Model Context Protocol → aggiungi server remoto. Inserisci il Server URL, il Client ID copiato e lascia il Client Secret vuoto.

  3. 3

    Autorizza nel browser

    Si apre automaticamente la pagina di consenso di Yero. Fai login se necessario, poi clicca Autorizza. Fatto.

Altri client MCP (Bearer token)

Per client che non supportano OAuth, puoi passare direttamente un Bearer token.

Test via curl — initialize
curl -X POST https://yero.it/api/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
Esempio — accorcia un URL via MCP
curl -X POST https://yero.it/api/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "shorten_url",
      "arguments": { "url": "https://example.com/pagina-lunga" }
    }
  }'

Pronto a iniziare?

Crea un token gratuito dalla dashboard e inizia subito.

Crea account gratuito →