tinco.it

API tinco.it

API REST, JSON, versiunea 1. Disponibil în planurile Pro și Business.

Cheile mele →

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

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.

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" } }
HTTPcodeCând
400invalid_jsonCorpul nu e JSON valid sau lipsește Content-Type: application/json.
401unauthorizedCheie lipsă, greșită sau revocată.
403plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limitPlanul, drepturile cheii sau rolul nu permit operația.
404not_foundLinkul nu există în workspace-ul cheii.
422validation_failedDate invalide; field spune care câmp.
429rate_limitedPrea multe cereri; reîncearcă după Retry-After secunde.