Intégration développeur pour créer des liens courts personnalisés et traçables : guide pratique

Un jour ou l’autre, une équipe cesse de créer ses liens à la main. Le produit a besoin d’un lien de partage par utilisateur, le CMS doit générer une URL courte à chaque publication d’article, l’outil de campagne veut un lien suivi par création publicitaire. Une intégration développeur pour créer des liens courts personnalisés et traçables fait du raccourcisseur une fonction que vos systèmes appellent.

Ce guide parcourt l’intégration de bout en bout : ce qu’il faut décider avant d’écrire du code, le fonctionnement de l’authentification et de l’appel de création, comment rendre les liens traçables sans casser l’attribution, les cas limites de redirection qui posent problème, la place des webhooks et la manière de tout tester. L’API de LinkPilot sert d’exemple concret ; la logique s’applique à la plupart des plateformes.

Décider d’abord de l’architecture

Quatre décisions, prises une fois pour toutes, évitent l’essentiel des reprises.

• Quels systèmes créent des liens, et sur quel déclencheur : un événement de publication, une action d’un utilisateur, l’enregistrement d’une fiche de campagne.
• Quels champs les appelants contrôlent. En général la destination et les tags ; parfois un slug. Rarement le domaine, qui devrait être un paramètre propre à chaque espace de travail ou à chaque client.
• Comment les données de campagne se traduisent en suivi. La campagne, le canal et l’emplacement dans votre système deviennent des tags sur le lien et des paramètres UTM sur la destination. Fixez cette correspondance et placez-la dans une seule fonction.
• Lien direct, lien profond ou solution de repli. Un lien vers une application mobile a besoin d’une solution de repli web pour les personnes qui n’ont pas l’application. Décidez si c’est le raccourcisseur ou votre destination qui s’en charge.

Mettez ces décisions par écrit. L’intégration est surtout du code de liaison, et ce code doit rester banal.

S’authentifier avec des clés à portée limitée

L’API de LinkPilot s’authentifie avec des clés de type bearer qui commencent par lp_live_, créées dans le tableau de bord et disponibles sur tous les forfaits, y compris Free. Chaque clé appartient à un espace de travail : une intégration d’agence utilise donc une clé par espace de travail client, et les liens arrivent par construction au bon endroit.

curl https://uselinkpilot.com/api/v1/me \
  -H "Authorization: Bearer lp_live_..."

GET /me renvoie l’espace de travail, le forfait, les limites, l’utilisation actuelle et le budget de requêtes de la clé. Appelez-le au démarrage et faites apparaître les limites dans vos propres logs, pour découvrir un plafond avant qu’une campagne ne le découvre à votre place.

Traitez la clé comme n’importe quel identifiant de production : stockez-la dans un gestionnaire de secrets, jamais dans un dépôt ni dans un bundle front-end, et quand vous devez la transmettre à la personne qui développe l’intégration, envoyez-la par un lien secret à usage unique. Le guide sur les clés API couvre la transmission et la rotation.

Créer le lien

L’appel de création prend la destination et quelques champs facultatifs.

curl -X POST https://uselinkpilot.com/api/v1/links \
  -H "Authorization: Bearer lp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/launch?utm_source=newsletter&utm_medium=email&utm_campaign=oct-launch",
    "slug": "oct-launch-email",
    "domain": "go.example.com",
    "title": "October launch, newsletter",
    "tags": ["oct-launch", "email"]
  }'

La réponse contient l’identifiant du lien, l’URL courte et les métadonnées que vous avez envoyées. Stockez l’identifiant à côté de votre propre enregistrement : c’est lui qui servira plus tard à lire, modifier ou supprimer le lien. GET /links liste les liens du plus récent au plus ancien, avec une pagination par curseur ({ data, next_cursor }), et GET /links/{id} et DELETE /links/{id} agissent sur un lien précis.

Quelques règles qui gardent l’intégration fiable :

• Construisez l’URL de destination dans le code, paramètres UTM compris, à partir des champs de votre campagne. Les paramètres saisis à la main finissent par diverger. Le guide complet des paramètres UTM fixe les conventions.
• Laissez la plateforme générer les slugs, sauf si un humain doit les lire. Quand vous définissez vous-même les slugs, dérivez-les de la campagne, du canal et de l’emplacement, en minuscules avec des tirets, et gérez un conflit en ajoutant un court suffixe puis en réessayant une seule fois.
• Rendez la création idempotente. Associez chaque création à l’identifiant de votre propre enregistrement, pour qu’une nouvelle tentative après un dépassement de délai retrouve le lien existant au lieu d’en créer un second. Si la plateforme ne propose pas de clé d’idempotence, cherchez votre tag ou votre slug avec GET /links avant de créer le lien.
• Un traitement en masse, c’est une boucle avec temporisation. Respectez le budget de requêtes indiqué par /me, temporisez en cas de 429 et consignez chaque échec avec l’enregistrement concerné.

Pour les scripts et l’outillage local, la CLI linkpilot disponible sur npm encapsule les mêmes appels, et le serveur @uselinkpilot/mcp les met à disposition des agents IA. Les deux sont open source sur GitHub, sous TetraCoreHQ.

Rendre les liens traçables sans casser l’attribution

Chaque clic sur un lien créé par l’API est enregistré exactement comme pour un lien créé dans le tableau de bord : l’heure, le référent, l’appareil, le navigateur, le pays, la région, le signalement des bots et un hash salé à la place de l’adresse IP. Vous obtenez ainsi le décompte au niveau du lien. L’attribution sur la destination dépend toujours de l’arrivée intacte de l’URL.

• Conservez les paramètres de requête à travers la redirection. Testez un lien avec le vérificateur de redirections et vérifiez que les paramètres UTM figurent bien dans l’URL finale.
• Évitez les chaînes. Un lien court qui redirige vers une autre redirection perd des paramètres et de la vitesse. Pointez directement vers la page finale.
• Décidez de ce que vous collectez. Le pays et l’appareil relèvent des statistiques agrégées. Un lien par utilisateur relié à une fiche client est une donnée personnelle. Le guide moderne du suivi des liens liste ce qui est enregistré et ce qui ne l’est volontairement pas.
• Fixez les attentes dans le produit. Un nombre de clics n’est pas un nombre de conversions. Affichez les deux, avec des libellés clairs.

Gérer les cas limites de redirection

• Validation de la destination. Avant de créer le lien, refusez les destinations qui ne sont pas en HTTPS, votre propre domaine de raccourcissement et tout ce qui figure sur une liste de blocage. Une redirection ouverte sur votre marque est un outil d’hameçonnage (phishing).
• Liens expirés, désactivés ou introuvables. Choisissez la page de repli au moment de créer le lien et configurez-la, pour qu’un lien de campagne mort mène à la page d’accueil plutôt qu’à une erreur. Pour les liens imprimés, préférez modifier la destination plutôt que de laisser le lien expirer.
• Liens profonds. Utilisez une destination qui détecte l’application et se rabat sur le web, ou une fonctionnalité de la plateforme prévue pour cela. Testez sur les deux systèmes d’exploitation, avec et sans l’application installée.
• Encodage. Encodez l’URL de destination avant de la placer dans le JSON, surtout quand elle contient sa propre chaîne de requête. Le double encodage est le bug habituel.
• Localisation. Si un même lien court sert plusieurs langues, faites la détection de langue sur la destination, pas dans le slug.

Ajouter des webhooks pour les événements qui comptent

Les webhooks permettent au reste de votre stack de réagir à l’activité des liens sans interrogation périodique. LinkPilot signe chaque envoi avec un en-tête de signature HMAC et se déclenche sur le cycle de vie des liens (link.created, link.updated, link.deleted) et sur celui des secrets (secret.created, secret.viewed, secret.burned). Vérifiez la signature avant d’analyser le contenu, accusez réception rapidement, traitez depuis une file d’attente et stockez les identifiants d’événements pour que les renvois soient sans effet. Les données de clics forment un flux de reporting et non un webhook : lisez-les via les statistiques et les exports. Le guide des intégrations par webhook explique comment construire le récepteur.

Tester de bout en bout, puis continuer à surveiller

Avant que l’intégration ne touche une vraie campagne :

1. Créez un lien avec vos tags de test, dans un espace de travail de préproduction.
2. Vérifiez que la réponse contient l’identifiant et l’URL courte attendus.
3. Cliquez dessus depuis un téléphone et un ordinateur portable. Vérifiez la redirection, la présence des paramètres UTM à l’arrivée et les deux clics dans les statistiques, avec les bons types d’appareils.
4. Créez à nouveau le même enregistrement et vérifiez que vous obtenez le même lien, pas un doublon.
5. Supprimez-le et vérifiez que link.deleted arrive sur l’endpoint de votre webhook, si vous en utilisez un.

En production, surveillez trois choses : les taux d’erreur de l’API par code de statut, la latence de redirection mesurée par un contrôle synthétique, et un rapprochement hebdomadaire du nombre de liens entre vos enregistrements et GET /links. Renouvelez la clé API à intervalle régulier et à chaque départ d’un membre de l’équipe qui la détient.

Documentez l’intégration comme un produit interne : les champs qu’elle accepte, la règle des slugs, le comportement de repli, les limites indiquées par /me et la personne à contacter quand une campagne affiche zéro clic. La prochaine personne qui y touchera vous en sera reconnaissante, et ce sera souvent vous.

Lectures complémentaires

• Comparatif des API de raccourcisseurs d’URL : Bitly, Dub, Short.io, TinyURL
• Comment choisir et utiliser une plateforme de suivi des liens avec intégrations par webhook
• Comment partager des clés API en toute sécurité
• Paramètres UTM : le guide complet 2026