tinco.it API
REST-API, JSON, Version 1. Verfügbar in den Plänen Pro und Business.
Authentifizierung
Erstelle einen Schlüssel unter Dashboard → API und sende ihn imAuthorization Header. Der Schlüssel gilt in dem Workspace, in dem er erstellt wurde, mit der Rolle der Person, die ihn erstellt hat. Verwende ihn nicht in Code, der im Browser läuft.
curl https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…"Limits: 60 Anfragen pro Minute pro Schlüssel (Pro), 300 (Business). Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining undX-RateLimit-Reset (Unix-Zeitstempel).
Links
POST/links
Erstellt einen Link. Nur url ist Pflicht; ohne alias wird ein Code erzeugt. Das Ziel durchläuft dieselben Anti-Missbrauchs-Prüfungen wie im 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"]}'Antwort 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 (die Sicherheitsprüfung läuft; der Link funktioniert) oder disabled.
GET/links
Liste der Links, neueste zuerst, 20 pro Seite. Optionale Parameter: q (durchsucht Adresse, Ziel, Titel), tag, archived=true, page.
{ "data": [ … ], "page": 1, "pages": 3, "total": 52, "per_page": 20 }GET/links/{id}
Ein einzelner Link.
PATCH/links/{id}
Ändert nur die Felder, die du sendest: url, alias, title, tags (ersetzt die Liste), archived. Die Änderung gilt sofort für die Weiterleitung.
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}
Löscht den Link endgültig (Antwort 204). Erfordert die Rolle Admin; die Kurzadresse bleibt reserviert und kann nicht wiederverwendet werden. Um ihn nur zu stoppen, verwende PATCH mit {"archived": true}.
GET/links/{id}/stats
Statistiken ohne Bots. interval: 7z (7 Tage), 30z (Standard), 90z, 12l (12 Monate). timezone: eine IANA-Zeitzone (z. B. Europe/Berlin), Standard Europe/Bucharest; Tage und Stunden (hourly: 0–23, über den Zeitraum summiert) richten sich danach.
{
"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
Der QR-Code des Links als SVG, mit dem im Dashboard gespeicherten Design. Scans werden in den Statistiken separat gezählt.
Webhooks
Verfügbar im Business-Plan, unter Dashboard → API. Für jedes Ereignis senden wir einen JSON-POST. Ereignisse: link.created, link.updated, link.deleted, link.clicked (nur echte Besucher, keine Bots) und ping (der Button „Testen“).
POST /webhooks/tinco
Content-Type: application/json
Tinco-Event: link.clicked
Tinco-Delivery: 7d0c… (eindeutig pro Ereignis; bleibt bei Wiederholungen gleich)
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": {} }
}
}Signatur prüfen
Berechne HMAC-SHA256 mit dem Secret des Webhooks über `${t}.${raw body}` und vergleiche mit v1. Lehne Anfragen ab, deren t älter als 5 Minuten ist (Schutz vor Replay-Angriffen).
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));
}Antworte innerhalb von 5 Sekunden mit einem 2xx-Code. Andernfalls versuchen wir es nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden erneut. Weiterleitungen werden nicht verfolgt. Nach 50 Fehlschlägen in Folge stoppt der Webhook automatisch; starte ihn im Dashboard neu. Die Zustellreihenfolge ist nicht garantiert: Nutze Tinco-Delivery, um Duplikate zu ignorieren.
Fehler
Fehlermeldungen sind auf Englisch. code ist stabil (für deine Logik); reason nennt die genaue Ursache (z. B. aliasTaken) und field das betroffene Feld.
{ "error": { "code": "validation_failed", "message": "This alias is already taken. Pick another one.", "reason": "aliasTaken", "field": "alias" } }| HTTP | code | Wann |
|---|---|---|
| 400 | invalid_json | Der Body ist kein gültiges JSON oder Content-Type: application/json fehlt. |
| 401 | unauthorized | Schlüssel fehlt, ist falsch oder widerrufen. |
| 403 | plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limit | Plan, Berechtigungen des Schlüssels oder Rolle erlauben die Operation nicht. |
| 404 | not_found | Der Link existiert nicht im Workspace des Schlüssels. |
| 422 | validation_failed | Ungültige Daten; field nennt das Feld. |
| 429 | rate_limited | Zu viele Anfragen; versuch es nach Retry-After Sekunden erneut. |