Vai al contenuto

API tinco.it

API REST, JSON, versione 1. Disponibile nei piani Pro e Business.

Le mie chiavi →

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).

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.

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" } }
HTTPcodeQuando
400invalid_jsonIl body non è JSON valido oppure manca Content-Type: application/json.
401unauthorizedChiave mancante, errata o revocata.
403plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limitIl piano, i permessi della chiave o il ruolo non consentono l'operazione.
404not_foundIl link non esiste nel workspace della chiave.
422validation_failedDati non validi; field indica quale campo.
429rate_limitedTroppe richieste; riprova dopo Retry-After secondi.