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
- Vous envoyez le lien à
POST /v1/traces, avec votre clé. - 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
idleTimesecondes. - 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.
X-Billing-Token: YOUR_KEYRemarque : 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
https://trace.unshortlink.com/v1/tracesEnvoyez 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
| Nom | Type | Par défaut | Description |
|---|---|---|---|
urlObligatoire | string | Obligatoire— | Le lien à tracer, en http ou https. Sans schéma, https:// est ajouté. |
device | string | Par défaut desktop | Ce que le navigateur prétend être : desktop, iphone ou android. |
headers | object | Par 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. |
maxRedirects | integer | Par défaut 20 | Arrête le traçage après ce nombre de redirections, de 1 à 20. |
timeLimit | integer | Par défaut 50 | La durée maximale de l'appel, en secondes, de 5 à 50. |
idleTime | integer | Par défaut 3 | Les secondes sans changement avant la fin du traçage, de 3 à 30. Augmentez-le pour les pages qui redirigent tard. |
body | boolean | Par défaut false | Ajoute 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 :
{
"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 :
| Champ | Contenu |
|---|---|
id | L'identifiant du traçage |
url | Le lien tel que tracé, avec https:// ajouté s'il n'avait pas de schéma |
startedAt, finishedAt, durationMs | Quand le traçage a commencé et fini, et sa durée en millisecondes |
settled | Ce qui a terminé le traçage : stable, time_limit ou redirect_limit |
redirects | Le nombre de redirections, et qui les a faites : le serveur, la page ou Chrome |
end | Où le lien a abouti : une page, un téléchargement, une application, une erreur… Voir comment un lien peut aboutir. |
final | La dernière page : son adresse, l'adresse sans paramètres de suivi, son statut et son titre |
steps | Chaque é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 |
page | La page finale : description, langue, balises Open Graph, technologies, un extrait du texte… |
domains | Chaque domaine de la chaîne : ses dates d'enregistrement et d'expiration, son registraire et son statut, selon le registre |
certificate | Le certificat de la page finale : émetteur, entreprise vérifiée, validité |
safety | Safe Browsing, le parcours par chaque hôte, les paramètres de suivi retirés |
downloads, file | Les fichiers que le lien a lancés ou affichés, avec leurs empreintes |
downloadsRefused | Le nombre de fichiers lancés par le lien après les 5 premiers : ils ont été arrêtés avant de commencer |
lookups | Des liens vers VirusTotal, urlscan et la Wayback Machine pour le domaine final |
report | Quand le résultat et ses fichiers sont supprimés, 30 jours plus tard |
request | Les options utilisées par le traçage, valeurs par défaut comprises |
meta | La 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 :
| Aboutissement | Signification | Avec |
|---|---|---|
page | Une page web. | Avec : Rien de plus. |
download | Le lien a lancé un téléchargement. | Avec : end.files, la liste downloads et downloadsRefused. |
file | Un 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. |
app | Un 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_error | La dernière réponse était une erreur HTTP (400 ou plus). | Avec : end.status. |
empty | La dernière réponse n'avait pas de contenu (204 ou 205). | Avec : end.status. |
network_error | Rien 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_check | Une vérification anti-bot a arrêté le navigateur. | Avec : end.botCheck : le fournisseur (Cloudflare, DataDome, Imperva…). |
warning_page | Chrome 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. |
redirect | Le 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.
{
"error": {
"code": "invalid_request",
"message": "url is required.",
"param": "url"
}
}| Statut | Code | Quand |
|---|---|---|
400 | invalid_request | JSON mal formé, paramètre inconnu ou valeur hors limites. param le désigne. |
403 | forbidden_url | Une adresse privée, locale ou réservée, ou un lien que nos règles contre les abus refusent. |
403 | — | Une clé absente ou erronée. Nadles y répond, avec son propre corps message. Copiez à nouveau votre clé depuis le portail. |
413 | request_too_large | Un corps de plus de 64 Ko. |
429 | — | Les traçages de votre forfait sont épuisés, ou vous avez appelé plus vite que sa limite de débit. |
500 | internal_error | Une erreur de notre part. Réessayez. |
503 | busy | Aucun navigateur ne s'est libéré à temps. Réessayez. |
503 | unavailable | L'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
| Limite | Valeur |
|---|---|
| Traçages par mois | Le quota de votre forfait. Seules les réponses 200 comptent. Voyez combien il en reste dans le portail. |
| Appels par seconde | Fixés par votre forfait. Au-delà : 429. |
| Durée d'un appel | 50 secondes au plus, réglable avec timeLimit. |
| Redirections | 20 par traçage au plus, réglable avec maxRedirects. |
| Corps de la requête | 64 Ko au plus. |
| Contenu des pages | 200 Ko chacune, avec body: true. |
| Conservation des résultats | 30 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.
Obtenez votre clé
Choisissez un forfait mensuel. Nadles encaisse le paiement et vous remet une clé.
Voir les forfaits