API tinco.it
API REST, JSON, versiunea 1. Disponibil în planurile Pro și Business.
Autentificare
Creează o cheie din Dashboard → API și trimite-o în headerulAuthorization. Cheia lucrează în workspace-ul în care a fost creată, cu rolul persoanei care a creat-o. Nu o pune în cod care rulează în browser.
curl https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…"Limite: 60 de cereri pe minut per cheie (Pro), 300 (Business). Fiecare răspuns are X-RateLimit-Limit, X-RateLimit-Remaining șiX-RateLimit-Reset (timestamp Unix).
Linkuri
POST/links
Creează un link. Doar url e obligatoriu; fără alias, codul se generează. Destinația trece prin aceleași verificări anti-abuz ca în dashboard.
curl -X POST https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://exemplu.ro/offer","alias":"offer","tags":["newsletter"]}'Răspuns 201:
{
"id": "5c1f…",
"short_url": "https://tinco.it/offer",
"domain": "tinco.it",
"key": "offer",
"url": "https://exemplu.ro/offer",
"title": null,
"tags": ["newsletter"],
"archived": false,
"clicks": 0,
"status": "active",
"created_at": "2026-11-16T10:00:00.000Z"
}status: active, pending_check (verificarea de siguranță e în curs; linkul funcționează) sau disabled.
GET/links
Lista linkurilor, cele mai noi primele, câte 20 pe pagină. Parametri opționali: q (caută în adresă, destinație, titlu), tag, archived=true, page.
{ "data": [ … ], "page": 1, "pages": 3, "total": 52, "per_page": 20 }GET/links/{id}
Un singur link.
PATCH/links/{id}
Modifică doar câmpurile trimise: url, alias, title, tags (înlocuiește lista), archived. Schimbarea se aplică imediat redirectului.
curl -X PATCH https://www.tinco.it/api/v1/links/5c1f… \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://exemplu.ro/new-offer"}'DELETE/links/{id}
Șterge definitiv linkul (răspuns 204). Cere rol de administrator; adresa scurtă rămâne rezervată și nu mai poate fi folosită. Dacă vrei doar să-l oprești, folosește PATCH cu {"archived": true}.
GET/links/{id}/stats
Statistici fără boți. interval: 7z, 30z (implicit), 90z, 12l. timezone: un fus orar IANA (ex. Europe/London), implicit Europe/Bucharest; zilele și orele (hourly: 0–23, adunate pe interval) sunt în acest fus.
{
"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
Codul QR al linkului, ca SVG, cu designul salvat în dashboard. Scanările sunt numărate separat în statistici.
Webhooks
Disponibile în planul Business, din Dashboard → API. La fiecare eveniment trimitem un POST JSON. Evenimente: link.created, link.updated, link.deleted, link.clicked (doar vizitatori reali, fără boți) și ping (butonul „Test”).
POST /webhooks/tinco
Content-Type: application/json
Tinco-Event: link.clicked
Tinco-Delivery: 7d0c… (unic per eveniment; la reîncercări rămâne același)
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://exemplu.ro/offer" },
"click": { "timestamp": "…", "country": "RO", "city": "Bucharest", "device": "mobile", "os": "iOS",
"browser": "Mobile Safari", "referrer": "facebook.com", "qr": false, "variant": null, "utm": {} }
}
}Verifică semnătura
Calculează HMAC-SHA256 cu secretul webhook-ului peste `${t}.${corpul brut}` și compară cu v1. Respinge cererile cu t mai vechi de 5 minute (protecție la reluare).
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));
}Răspunde cu un cod 2xx în cel mult 5 secunde. Altfel reîncercăm după 1 minut, 5 minute, 30 de minute, 2 ore și 6 ore. Redirecturile nu sunt urmate. După 50 de eșecuri la rând, webhook-ul se oprește automat; îl pornești din nou din dashboard. Ordinea livrărilor nu e garantată: folosește Tinco-Delivery ca să ignori dublurile.
Erori
Mesajele de eroare sunt în engleză. code e stabil (pentru logica ta); reason dă cauza exactă (ex. aliasTaken), iar field câmpul cu problema.
{ "error": { "code": "validation_failed", "message": "This alias is already taken. Pick another one.", "reason": "aliasTaken", "field": "alias" } }| HTTP | code | Când |
|---|---|---|
| 400 | invalid_json | Corpul nu e JSON valid sau lipsește Content-Type: application/json. |
| 401 | unauthorized | Cheie lipsă, greșită sau revocată. |
| 403 | plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limit | Planul, drepturile cheii sau rolul nu permit operația. |
| 404 | not_found | Linkul nu există în workspace-ul cheii. |
| 422 | validation_failed | Date invalide; field spune care câmp. |
| 429 | rate_limited | Prea multe cereri; reîncearcă după Retry-After secunde. |