Utiliser l'API TinyLink

Marche à suivre

1. Ouvrez Bibliothèque, puis l'onglet Intégrations : la carte API TinyLink est la première.
2. Cliquez sur Générer un jeton : un panneau s'ouvre sur la droite. Choisissez les portées du jeton — Lecture, Écriture (créer, modifier, ajouter des liens, générer des QR codes) et Suppression — puis validez. Ne cochez que ce dont votre outil a besoin.
3. Le jeton apparaît en tête du panneau, masqué comme un mot de passe : l'œil l'affiche, le bouton à côté le copie. Il reste disponible à cet endroit, vous pourrez le reprendre plus tard avec le bouton Gérer de la carte.
4. Envoyez-le dans l'en-tête de chaque requête : Authorization: Bearer tl_…, à l'adresse https://api.tinylink.fr/v1.

Un jeton par environnement

Le jeton n'ouvre que l'environnement où il a été généré : vos autres espaces restent hors de portée. Il agit au nom de l'admin qui l'a généré, et cesse de fonctionner si cette personne n'est plus admin de l'environnement.

Le panneau Gérer est réservé aux admins : eux seuls voient le jeton et le modifient. Il est rangé chiffré chez TinyLink. Les portées se changent sans changer le jeton : vos outils n'ont rien à modifier. Régénérer en crée un nouveau et désactive l'ancien sur-le-champ — à faire si vous pensez qu'il a fuité. Révoquer le supprime. Le panneau indique aussi la date du dernier appel et le nombre d'appels.

Premier appel

Toutes les réponses sont en JSON. GET /v1/me vérifie le jeton et rend l'environnement, les portées et les plafonds de l'offre :

curl https://api.tinylink.fr/v1/me \
  -H "Authorization: Bearer tl_votre_jeton"

Pages

Une page se désigne par son identifiant ou son adresse personnalisée (slug). À la création, name est obligatoire ; description, slug, password, tags (identifiants), qr_code (true ou un modèle) et links (liens à ajouter d'un coup) sont facultatifs.

• GET /v1/pages — la liste, avec ?search=, ?tag=, ?page= et ?per_page= (100 au plus)
• POST /v1/pages — créer une page
• GET /v1/pages/{id} — une page et ses liens
• PATCH /v1/pages/{id} — name, description, slug, password (null retire l'adresse ou le mot de passe)
• DELETE /v1/pages/{id} — supprimer la page

curl -X POST https://api.tinylink.fr/v1/pages \
  -H "Authorization: Bearer tl_votre_jeton" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ma page",
    "slug": "ma-page",
    "qr_code": true,
    "links": [
      { "title": "Mon site", "url": "https://exemple.fr" },
      { "title": "Contact", "url": "bonjour@exemple.fr" }
    ]
  }'

Liens d'une page

Un lien porte title, url (une adresse web, un e-mail ou un téléphone), description, format (LIST, BANNER, SQUARE, SOCIAL ou TITLE pour un titre de section), size (FULL ou HALF), visible et position (1 = en haut). Les plafonds de liens de votre offre s'appliquent comme dans l'application.

• GET /v1/pages/{id}/links — les liens, dans l'ordre
• POST /v1/pages/{id}/links — ajouter un lien, ou plusieurs avec {"links": [ … ]} (100 au plus)
• PATCH /v1/pages/{id}/links/{lien} — modifier, déplacer (position), masquer (visible) ou archiver (archived)
• DELETE /v1/pages/{id}/links/{lien} — supprimer le lien

Liens réduits

À la création, url est obligatoire ; slug, password, tags et qr_code sont facultatifs.

• GET /v1/links — la liste (mêmes filtres que les pages)
• POST /v1/links — réduire une adresse
• GET /v1/links/{id}, PATCH /v1/links/{id} (url, slug, password), DELETE /v1/links/{id}

curl -X POST https://api.tinylink.fr/v1/links \
  -H "Authorization: Bearer tl_votre_jeton" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://exemple.fr/promo", "slug": "promo", "qr_code": "none" }'

Tags

• GET /v1/tags, POST /v1/tags (name, color au format #1E90FF)
• GET, PATCH, DELETE /v1/tags/{id} ; GET /v1/tags/{id}/elements — les pages et liens qui le portent
• PUT /v1/pages/{id}/tags/{tag} pose un tag, DELETE le retire — même chose sur /v1/links/{id}/tags/{tag}. Retirer un tag modifie l'élément sans rien supprimer : la portée Écriture suffit.

QR codes

Le QR code encode l'adresse courte de l'élément : il reste valable si vous changez la destination ou l'adresse personnalisée.

• POST /v1/pages/{id}/qr-code ou /v1/links/{id}/qr-code — générer, avec {"template": "classic"} (logo TinyLink), "none" (sans logo) ou l'identifiant d'un de vos modèles
• GET …/qr-code — les adresses du PNG (2048 px) et du SVG ; ?format=png ou ?format=svg renvoie le fichier lui-même
• GET /v1/qr-templates — les modèles disponibles dans l'environnement

Statistiques

GET /v1/pages/{id}/stats (vues) et GET /v1/links/{id}/stats (clics) acceptent ?days=1, 7, 30 (par défaut), 90 ou 0 pour depuis toujours. La réponse donne le total de la période, la variation par rapport à la période précédente, le total depuis la création, la série par jour (par mois pour 0), et la répartition par provenance, pays et appareil. Pour une page, s'y ajoutent les clics de chacun de ses liens.

Si votre offre change

Le jeton suit l'offre du propriétaire de l'environnement. S'il passe à une offre sans API, le jeton est suspendu : la carte l'indique et chaque appel répond 403 plan_required. Il n'est pas supprimé et reprend dès le retour à une offre Pro ou Business. Un admin peut le révoquer à tout moment, offre ou pas.

Erreurs et limites

Une erreur rend un code HTTP et un objet {"error": {"code": "…", "message": "…"}}. Les plus courantes : 401 jeton absent, invalide ou révoqué ; 403 portée manquante (insufficient_scope), plafond de l'offre atteint (plan_limit_reached) ou offre sans API ; 404 élément introuvable dans l'environnement ; 409 adresse personnalisée déjà prise ; 422 champ invalide (details.field le nomme) ou adresse signalée comme suspecte ; 423 élément bloqué par la modération ; 429 trop de requêtes.

Chaque jeton a droit à 120 requêtes par minute ; les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset disent où vous en êtes. Les contenus créés par l'API passent par la même vérification que ceux de l'application : un lien peut apparaître pending_review le temps qu'elle se fasse.