API tinco.it
API REST, JSON, version 1. Disponible avec les formules Pro et Business.
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).
Liens
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.
GET/links
Liste des liens, du plus récent au plus ancien, 20 par page. Paramètres facultatifs : q (recherche dans l'adresse, la destination, le titre), tag, archived=true, page.
{ "data": [ … ], "page": 1, "pages": 3, "total": 52, "per_page": 20 }GET/links/{id}
Un seul lien.
PATCH/links/{id}
Modifie uniquement les champs envoyés : url, alias, title, tags (remplace la liste), archived. La modification s'applique immédiatement à la redirection.
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}
Supprime définitivement le lien (réponse 204). Nécessite un rôle d'administrateur ; l'adresse courte reste réservée et ne peut plus être utilisée. Pour simplement l'arrêter, utilisez PATCH avec {"archived": true}.
GET/links/{id}/stats
Statistiques sans robots. interval : 7z (7 jours), 30z (par défaut), 90z, 12l (12 mois). timezone : un fuseau horaire IANA (ex. Europe/Paris), par défaut Europe/Bucharest ; les jours et les heures (hourly : 0–23, cumulées sur la période) l'utilisent.
{
"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
Le QR code du lien, en SVG, avec le design enregistré dans le tableau de bord. Les scans sont comptés séparément dans les statistiques.
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" } }| HTTP | code | Quand |
|---|---|---|
| 400 | invalid_json | Le corps n'est pas un JSON valide ou Content-Type: application/json est absent. |
| 401 | unauthorized | Clé absente, erronée ou révoquée. |
| 403 | plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limit | La formule, les autorisations de la clé ou le rôle ne permettent pas l'opération. |
| 404 | not_found | Le lien n'existe pas dans l'espace de travail de la clé. |
| 422 | validation_failed | Données invalides ; field indique le champ. |
| 429 | rate_limited | Trop de requêtes ; réessayez après Retry-After secondes. |