Zum Inhalt springen

tinco.it API

REST-API, JSON, Version 1. Verfügbar in den Plänen Pro und Business.

Meine Schlüssel →

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

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.

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" } }
HTTPcodeWann
400invalid_jsonDer Body ist kein gültiges JSON oder Content-Type: application/json fehlt.
401unauthorizedSchlüssel fehlt, ist falsch oder widerrufen.
403plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limitPlan, Berechtigungen des Schlüssels oder Rolle erlauben die Operation nicht.
404not_foundDer Link existiert nicht im Workspace des Schlüssels.
422validation_failedUngültige Daten; field nennt das Feld.
429rate_limitedZu viele Anfragen; versuch es nach Retry-After Sekunden erneut.