Aller au contenu

API tinco.it

API REST, JSON, version 1. Disponible avec les formules Pro et Business.

Mes clés →

Authentification

Créez une clé dans Tableau de bord → API et envoyez-la dans l'en-têteAuthorization. La clé fonctionne dans l'espace de travail où elle a été créée, avec le rôle de la personne qui l'a créée. Ne la mettez pas dans du code exécuté dans le navigateur.

curl https://www.tinco.it/api/v1/links \
  -H "Authorization: Bearer sk_live_…"

Limites : 60 requêtes par minute et par clé (Pro), 300 (Business). Chaque réponse inclut X-RateLimit-Limit, X-RateLimit-Remaining etX-RateLimit-Reset (horodatage Unix).

POST/links

Crée un lien. Seul url est obligatoire ; sans alias, un code est généré. La destination passe par les mêmes contrôles anti-abus que dans le tableau de bord.

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"]}'

Réponse 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 (la vérification de sécurité est en cours ; le lien fonctionne) ou disabled.

Webhooks

Disponibles avec la formule Business, depuis Tableau de bord → API. Pour chaque événement, nous envoyons un POST JSON. Événements : link.created, link.updated, link.deleted, link.clicked (visiteurs réels uniquement, sans robots) et ping (le bouton « Tester »).

POST /webhooks/tinco
Content-Type: application/json
Tinco-Event: link.clicked
Tinco-Delivery: 7d0c…           (unique par événement ; reste identique lors des nouvelles tentatives)
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": {} }
  }
}

Vérifier la signature

Calculez un HMAC-SHA256 avec le secret du webhook sur `${t}.${raw body}` et comparez-le à v1. Rejetez les requêtes dont t date de plus de 5 minutes (protection contre le rejeu).

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épondez avec un code 2xx en moins de 5 secondes. Sinon, nous réessayons après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures. Les redirections ne sont pas suivies. Après 50 échecs consécutifs, le webhook s'arrête automatiquement ; redémarrez-le depuis le tableau de bord. L'ordre de livraison n'est pas garanti : utilisez Tinco-Delivery pour ignorer les doublons.

Erreurs

Les messages d'erreur sont en anglais. code est stable (pour votre logique) ; reason donne la cause exacte (ex. aliasTaken) et field le champ concerné.

{ "error": { "code": "validation_failed", "message": "This alias is already taken. Pick another one.", "reason": "aliasTaken", "field": "alias" } }
HTTPcodeQuand
400invalid_jsonLe corps n'est pas un JSON valide ou Content-Type: application/json est absent.
401unauthorizedClé absente, erronée ou révoquée.
403plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limitLa formule, les autorisations de la clé ou le rôle ne permettent pas l'opération.
404not_foundLe lien n'existe pas dans l'espace de travail de la clé.
422validation_failedDonnées invalides ; field indique le champ.
429rate_limitedTrop de requêtes ; réessayez après Retry-After secondes.