API tinco.it
API REST, JSON, versione 1. Disponibile nei piani Pro e Business.
Autenticazione
Crea una chiave in Dashboard → API e inviala nell'headerAuthorization. La chiave funziona nel workspace in cui è stata creata, con il ruolo della persona che l'ha creata. Non inserirla in codice eseguito nel browser.
curl https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…"Limiti: 60 richieste al minuto per chiave (Pro), 300 (Business). Ogni risposta include X-RateLimit-Limit, X-RateLimit-Remaining eX-RateLimit-Reset (timestamp Unix).
Link
POST/links
Crea un link. Solo url è obbligatorio; senza alias, viene generato un codice. La destinazione passa per gli stessi controlli anti-abuso della dashboard.
curl -X POST https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/offer","alias":"offer","tags":["newsletter"]}'Risposta 201:
{
"id": "5c1f…",
"short_url": "https://tinco.it/offer",
"domain": "tinco.it",
"key": "offer",
"url": "https://example.com/offer",
"title": null,
"tags": ["newsletter"],
"archived": false,
"clicks": 0,
"status": "active",
"created_at": "2026-11-16T10:00:00.000Z"
}status: active, pending_check (il controllo di sicurezza è in corso; il link funziona) o disabled.
GET/links
Elenco dei link, dal più recente, 20 per pagina. Parametri facoltativi: q (cerca in indirizzo, destinazione, titolo), tag, archived=true, page.
{ "data": [ … ], "page": 1, "pages": 3, "total": 52, "per_page": 20 }GET/links/{id}
Un singolo link.
PATCH/links/{id}
Modifica solo i campi che invii: url, alias, title, tags (sostituisce l'elenco), archived. La modifica si applica subito al reindirizzamento.
curl -X PATCH https://www.tinco.it/api/v1/links/5c1f… \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/new-offer"}'DELETE/links/{id}
Elimina definitivamente il link (risposta 204). Richiede il ruolo di amministratore; l'indirizzo breve resta riservato e non può essere riutilizzato. Per fermarlo soltanto, usa PATCH con {"archived": true}.
GET/links/{id}/stats
Statistiche senza bot. interval: 7z (7 giorni), 30z (predefinito), 90z, 12l (12 mesi). timezone: un fuso orario IANA (es. Europe/Rome), predefinito Europe/Bucharest; giorni e ore (hourly: 0–23, sommati sul periodo) lo usano.
{
"interval": { "id": "30z", "from": "2026-10-18", "to": "2026-11-16", "timezone": "Europe/Bucharest" },
"clicks": 1250, "clicks_previous_period": 980, "unique_visitors": 1032,
"daily": [ { "day": "2026-10-18", "clicks": 31, "unique_visitors": 27 }, … ],
"hourly": [ { "hour": 0, "clicks": 12 }, … { "hour": 23, "clicks": 40 } ],
"breakdowns": {
"country": { "top": [ { "value": "RO", "clicks": 1100 }, … ], "other": 12 },
"device": …, "os": …, "browser": …, "referrer": …, "region": …, "city": …, "via": …,
"utmSource": …, "utmMedium": …, "utmCampaign": …, "variant": …
}
}GET/links/{id}/qr
Il codice QR del link, in SVG, con il design salvato nella dashboard. Le scansioni sono conteggiate a parte nelle statistiche.
Webhook
Disponibili nel piano Business, da Dashboard → API. Per ogni evento inviamo un POST JSON. Eventi: link.created, link.updated, link.deleted, link.clicked (solo visitatori reali, niente bot) e ping (il pulsante “Test”).
POST /webhooks/tinco
Content-Type: application/json
Tinco-Event: link.clicked
Tinco-Delivery: 7d0c… (unico per evento; resta uguale nei nuovi tentativi)
Tinco-Signature: t=1794835200,v1=5f2b…
{
"id": "evt_9a1e…",
"type": "link.clicked",
"created_at": "2026-11-16T10:00:00.000Z",
"workspace_id": "…",
"data": {
"link": { "id": "…", "short_url": "https://tinco.it/offer", "url": "https://example.com/offer" },
"click": { "timestamp": "…", "country": "RO", "city": "Bucharest", "device": "mobile", "os": "iOS",
"browser": "Mobile Safari", "referrer": "facebook.com", "qr": false, "variant": null, "utm": {} }
}
}Verifica la firma
Calcola HMAC-SHA256 con il secret del webhook su `${t}.${raw body}` e confrontalo con v1. Rifiuta le richieste il cui t è più vecchio di 5 minuti (protezione dal replay).
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Rispondi con un codice 2xx entro 5 secondi. Altrimenti riproviamo dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore. I reindirizzamenti non vengono seguiti. Dopo 50 errori consecutivi il webhook si ferma automaticamente; riattivalo dalla dashboard. L'ordine di consegna non è garantito: usa Tinco-Delivery per ignorare i duplicati.
Errori
I messaggi di errore sono in inglese. code è stabile (per la tua logica); reason indica la causa esatta (es. aliasTaken) e field il campo interessato.
{ "error": { "code": "validation_failed", "message": "This alias is already taken. Pick another one.", "reason": "aliasTaken", "field": "alias" } }| HTTP | code | Quando |
|---|---|---|
| 400 | invalid_json | Il body non è JSON valido oppure manca Content-Type: application/json. |
| 401 | unauthorized | Chiave mancante, errata o revocata. |
| 403 | plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limit | Il piano, i permessi della chiave o il ruolo non consentono l'operazione. |
| 404 | not_found | Il link non esiste nel workspace della chiave. |
| 422 | validation_failed | Dati non validi; field indica quale campo. |
| 429 | rate_limited | Troppe richieste; riprova dopo Retry-After secondi. |