Documentation de l'API

Comment suivre les redirections d'un lien depuis votre code : la requête, la réponse, les erreurs et les limites.

Introduction

L'API de traçage des redirections ouvre un lien dans un vrai Chrome sur nos serveurs, suit chaque redirection jusqu'au bout et répond par un seul document JSON : chaque étape avec son code de statut, la façon dont elle a redirigé et la page d'arrivée.

Déroulement d'un appel

  1. Vous envoyez le lien à POST /v1/traces, avec votre clé.
  2. Un vrai Chrome l'ouvre et suit chaque redirection : HTTP, meta refresh, JavaScript et formulaires. Le traçage s'arrête dès que plus rien ne change pendant idleTime secondes.
  3. L'appel répond avec toute la chaîne, en un seul document JSON.

Remarque : L'appel reste ouvert jusqu'à la fin du traçage : au plus timeLimit secondes, 50 par défaut. Réglez le délai d'attente de votre client HTTP sur 60 secondes.

Authentification

Envoyez votre clé dans l'en-tête X-Billing-Token de chaque appel. Vous la recevez en vous abonnant à un forfait : elle se trouve dans votre compte sur portal.unshortlink.com, où vous pouvez aussi voir votre consommation du mois, changer ou résilier votre forfait et télécharger vos factures.

En-tête
X-Billing-Token: YOUR_KEY

Remarque : Gardez la clé sur votre serveur, jamais dans une page web ou une application : quiconque la possède peut utiliser les traçages de votre forfait. Un appel sans clé valide reçoit 403.

La requête

POSThttps://trace.unshortlink.com/v1/traces

Envoyez un corps JSON avec l'en-tête Content-Type: application/json. Seul url est obligatoire. Un paramètre que nous ne connaissons pas est refusé avec 400 : une faute de frappe échoue clairement au lieu d'être ignorée.

Paramètres

urlstringObligatoireLe lien à tracer, en http ou https. Sans schéma, https:// est ajouté.
devicestringPar défaut desktopCe que le navigateur prétend être : desktop, iphone ou android.
headersobjectPar défaut {}Des en-têtes ajoutés à chaque requête de la chaîne, comme Accept-Language. Chaque site de la chaîne les reçoit : aucun secret.
maxRedirectsintegerPar défaut 20Arrête le traçage après ce nombre de redirections, de 1 à 20.
timeLimitintegerPar défaut 50La durée maximale de l'appel, en secondes, de 5 à 50.
idleTimeintegerPar défaut 3Les secondes sans changement avant la fin du traçage, de 3 à 30. Augmentez-le pour les pages qui redirigent tard.
bodybooleanPar défaut falseAjoute le contenu de chaque page, jusqu'à 200 Ko chacune.

Exemple

Tracer un lien comme un iPhone l'ouvrirait :

curl -X POST https://trace.unshortlink.com/v1/traces \
  -H "X-Billing-Token: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/go",
    "device": "iphone"
  }'

La réponse, abrégée :

200 OK · application/json
{
  "id": "tr_7d1f0c9a2b8e4c51a3f6e0b9d2c4a817",
  "url": "https://example.com/go",
  "durationMs": 4210,
  "settled": "stable",
  "redirects": {
    "total": 2,
    "byServer": 2,
    "byPage": 0,
    "byChrome": 0
  },
  "end": { "type": "page", "step": 2 },
  "final": {
    "url": "https://shop.example.com/",
    "cleanUrl": "https://shop.example.com/",
    "status": 200,
    "title": "Summer sale"
  },
  "steps": [
    {
      "index": 0,
      "url": "https://example.com/go",
      "status": 301,
      "redirect": {
        "to": "https://www.example.com/go",
        "mechanism": "http"
      }
    },
    …
  ],
  "page": { … },
  "certificate": { … },
  "safety": { … }
}

La réponse

Une réponse 200 contient tout le traçage. Ses parties principales :

idL'identifiant du traçage
urlLe lien tel que tracé, avec https:// ajouté s'il n'avait pas de schéma
startedAt, finishedAt, durationMsQuand le traçage a commencé et fini, et sa durée en millisecondes
settledCe qui a terminé le traçage : stable, time_limit ou redirect_limit
redirectsLe nombre de redirections, et qui les a faites : le serveur, la page ou Chrome
endOù le lien a abouti : une page, un téléchargement, une application, une erreur… Voir comment un lien peut aboutir.
finalLa dernière page : son adresse, l'adresse sans paramètres de suivi, son statut et son titre
stepsChaque étape : son adresse, son code de statut, sa façon de rediriger, le serveur, son certificat, les temps, les en-têtes et les cookies
pageLa page finale : description, langue, balises Open Graph, technologies, un extrait du texte…
domainsChaque domaine de la chaîne : ses dates d'enregistrement et d'expiration, son registraire et son statut, selon le registre
certificateLe certificat de la page finale : émetteur, entreprise vérifiée, validité
safetySafe Browsing, le parcours par chaque hôte, les paramètres de suivi retirés
downloads, fileLes fichiers que le lien a lancés ou affichés, avec leurs empreintes
downloadsRefusedLe nombre de fichiers lancés par le lien après les 5 premiers : ils ont été arrêtés avant de commencer
lookupsDes liens vers VirusTotal, urlscan et la Wayback Machine pour le domaine final
reportQuand le résultat et ses fichiers sont supprimés, 30 jours plus tard
requestLes options utilisées par le traçage, valeurs par défaut comprises
metaLa version de l'API et l'heure de la réponse

Chaque champ est décrit dans le fichier OpenAPI.

Comment un lien peut aboutir

Chaque réponse a les mêmes parties, mais end.type indique où le lien a abouti, et certains champs n'apparaissent qu'avec certains aboutissements :

pageUne page web.Avec : Rien de plus.
downloadLe lien a lancé un téléchargement.Avec : end.files, la liste downloads et downloadsRefused.
fileUn fichier que le navigateur a affiché lui-même, comme un PDF ou une image.Avec : L'objet file : son nom, sa taille, ses empreintes et son vrai type.
appUn lien d'application (WhatsApp, Telegram, App Store…).Avec : end.app : le schéma, le nom de l'application, le lien complet et, s'ils sont connus, le paquet Android, l'identifiant App Store et la page de repli.
http_errorLa dernière réponse était une erreur HTTP (400 ou plus).Avec : end.status.
emptyLa dernière réponse n'avait pas de contenu (204 ou 205).Avec : end.status.
network_errorRien n'a répondu : le nom ne se résout pas, la connexion a échoué…Avec : end.error (son type et le message de Chrome) et, quand le nom ne se résout pas, end.deadReason : la raison selon le registre (expiré, suspendu…).
bot_checkUne vérification anti-bot a arrêté le navigateur.Avec : end.botCheck : le fournisseur (Cloudflare, DataDome, Imperva…).
warning_pageChrome a affiché son propre avertissement au lieu de la page.Avec : end.warning (aujourd'hui toujours safe_browsing), end.threat (phishing, malware, unwanted_software, billing ou unknown) et end.warningText, les mots de Chrome.
redirectLe traçage s'est arrêté à maxRedirects : la redirection de la dernière étape n'a pas été suivie.Avec : Rien de plus.

Remarque : page vaut null quand le lien n'a pas abouti à une page web, certificate quand la page finale n'est pas sécurisée (ou qu'il n'y en a pas), et lookups pour une page à l'adresse même d'une plateforme, comme un formulaire Google.

Erreurs

Une erreur répond avec un statut HTTP et un corps JSON : un code que votre code peut tester, un message pour une personne et, pour invalid_request, le param en cause.

400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "url is required.",
    "param": "url"
  }
}
400invalid_requestJSON mal formé, paramètre inconnu ou valeur hors limites. param le désigne.
403forbidden_urlUne adresse privée, locale ou réservée, ou un lien que nos règles contre les abus refusent.
403Une clé absente ou erronée. Nadles y répond, avec son propre corps message. Copiez à nouveau votre clé depuis le portail.
413request_too_largeUn corps de plus de 64 Ko.
429Les traçages de votre forfait sont épuisés, ou vous avez appelé plus vite que sa limite de débit.
500internal_errorUne erreur de notre part. Réessayez.
503busyAucun navigateur ne s'est libéré à temps. Réessayez.
503unavailableL'API est en pause. Réessayez plus tard.

Remarque : Un appel ne compte comme un traçage que s'il répond 200.

Limites et quotas

Traçages par moisLe quota de votre forfait. Seules les réponses 200 comptent. Voyez combien il en reste dans le portail.
Appels par secondeFixés par votre forfait. Au-delà : 429.
Durée d'un appel50 secondes au plus, réglable avec timeLimit.
Redirections20 par traçage au plus, réglable avec maxRedirects.
Corps de la requête64 Ko au plus.
Contenu des pages200 Ko chacune, avec body: true.
Conservation des résultats30 jours, captures d'écran et liens des fichiers compris.

Fichier OpenAPI

Toute l'API dans un seul fichier OpenAPI : importez-le dans Postman ou Insomnia, ou générez un client dans votre langage.

Télécharger openapi.json

Obtenez votre clé

Choisissez un forfait mensuel. Nadles encaisse le paiement et vous remet une clé.

Voir les forfaits