Créer des liens à la main, ça va, jusqu'au jour où ça ne va plus. Dès que chaque commande réclame un lien de suivi, chaque utilisateur un lien de parrainage, ou chaque annonce un QR code, il vous faut la même chose par programmation. C'est à cela que sert une API de raccourcisseur d'URL — et la surface est assez réduite pour que le branchement tienne dans une pause café.

Ce que vous pouvez automatiser

  • Des liens par commande ou par utilisateur, générés à l'instant où on en a besoin.
  • Des liens de campagne en masse — un par canal, créés depuis un tableur dans une boucle plutôt qu'à la main.
  • Des QR codes à la volée pour les billets, les factures, les étiquettes et les bons de livraison.
  • Les données de clics rapatriées dans votre propre tableau de bord, pour que les chiffres vivent là où votre équipe regarde déjà.

Si vous doutez encore d'avoir besoin de l'API, le test honnête tient au volume et à la répétition : si vous faites la même chose dans un navigateur plus de quelques fois par semaine, automatisez.

S'authentifier

Récupérez votre clé sur la page de votre compte et envoyez-la dans un en-tête X-Api-Key à chaque requête. Deux règles non négociables : gardez la clé côté serveur — tout ce qui se trouve dans du JavaScript front-end est public, et une clé qui fuite laisse des inconnus créer des liens en votre nom — et changez-la immédiatement si elle atterrit un jour dans un dépôt ou un journal.

Créer un lien

Un POST sur /api/getLink.json avec la destination. Vous pouvez passer un alias, un mode, une expiration et un mot de passe dans le même appel :

curl -X POST https://urlik.xyz/api/getLink.json -H "X-Api-Key: YOUR_KEY" -d "url=https://example.com/very/long/path" -d "alias=spring-sale"

La réponse est un JSON contenant l'URL courte, l'URL de son QR et l'URL de ses statistiques. Les liens créés avec une clé sont rattachés à votre compte : ils apparaissent dans votre tableau de bord et restent modifiables.

Un détail à connaître avant de coder : un alias est unique à l'échelle du service. Si spring-sale est déjà pris, vous recevez une erreur, pas un repli silencieux — donc soit vous traitez ce cas, soit vous préfixez vos alias (acme-spring-sale).

Générer un QR code

GET /api/qr.json prend la donnée plus, en option, format, fg, bg, ecc et size, et renvoie le QR. Pointez-le vers un lien court plutôt que vers une longue URL brute : vous obtenez un code plus propre et plus robuste, et la destination reste modifiable ensuite. C'est le principe du QR code dynamique, appliqué depuis votre backend.

Lire les statistiques

GET /api/stats.json renvoie les totaux, une série temporelle, les référents, les appareils et les pays d'un lien — les mêmes chiffres que la page de statistiques, sous une forme que vous pouvez poser dans votre propre interface d'administration.

Interrogez-la selon un calendrier, pas à chaque chargement de page. Les statistiques de clics ne sont pas un registre en temps réel, et marteler l'endpoint pour redessiner un graphique que personne ne regarde, c'est la meilleure façon de rencontrer le limiteur de débit.

Construire pour que ça ne casse pas à 3 h du matin

Les endpoints sont simples ; les intégrations qui échouent sont celles qui supposent que rien ne va jamais de travers. Quatre habitudes qui se remboursent toutes seules :

  • Vérifiez la réponse, toujours. Chaque appel renvoie un statut — lisez-le. Le bug classique consiste à présumer le succès et à stocker un corps d'erreur comme s'il s'agissait d'un lien court, puis à le découvrir sur une facture imprimée.
  • Ne bloquez jamais l'utilisateur sur un lien. Si le raccourcissement se produit à l'intérieur du tunnel de paiement, une API lente devient un paiement lent. Faites-le dans une tâche de fond, ou repliez-vous sur l'URL longue et réessayez plus tard. L'URL longue marche toujours ; c'est votre filet de sécurité.
  • Mettez en cache ce qui ne change pas. Une même destination n'a pas besoin d'être raccourcie deux fois — stockez l'URL courte à côté de l'enregistrement source et réutilisez-la. Moins cher, plus rapide, et votre tableau de bord reste lisible.
  • Temporisez sur les erreurs. Réessayez avec des délais croissants plutôt que dans une boucle serrée. Une limite de débit à laquelle on répond par une tempête de tentatives reste une limite de débit.

Là où l'API s'arrête

Deux limites, honnêtement. Les limites de débit existent, et généreux ne veut pas dire infini : les traitements par lots doivent être cadencés, pas tirés d'un coup. Et l'API crée des liens ; elle ne décide pas de ce qu'il faut mettre dedans. Taguez vos liens avec des paramètres UTM dès la création (voyez le guide UTM) ou vous automatiserez la production de milliers de liens que vous ne saurez pas distinguer dans vos statistiques — une position pire que le travail à la main.

En résumé

Un endpoint pour créer, un pour le QR, un pour les statistiques, un en-tête pour l'authentification. Gardez la clé côté serveur, vérifiez chaque réponse, sortez le travail du chemin critique, mettez en cache ce qui se répète et taguez dès la création. La liste complète des paramètres, les codes d'erreur et les exemples vivent dans la documentation de l'API ; si vous voulez d'abord le contexte conceptuel, commencez par ce qu'est un raccourcisseur d'URL.