Qualit.ly API

Données produit, images QC et métadonnées de Weidian, Taobao et 1688. Authentification par jeton Bearer, limites de débit généreuses, plans par paliers.

Obtenir une clé d’API Démarrage rapide

Premiers pas

Toutes les requêtes vont vers https://backend.qualit.ly/api/v1. Trois étapes :

1
Obtenir une clé
Connectez-vous et créez une clé d’API depuis le tableau de bord développeur.
2
Envoyer une requête
Envoyez votre clé comme jeton Bearer dans l’en-tête Authorization.
3
Recevoir les données
Recevez des réponses JSON avec les données produit et les images QC.

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

Authentification

Incluez une clé d’API valide dans l’en-tête Authorization en utilisant le schéma Bearer.

http

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Format de la clé

Les clés suivent le format qc_{mode}_{random}, où mode est live ou test, et random est composé de 32 caractères cryptographiquement aléatoires.

Les clés ne s’affichent qu’une fois, à leur création. Nous ne stockons que le hachage SHA-256 : une clé perdue ne peut donc pas être récupérée — révoquez-la et créez-en une nouvelle.

Liste d’IP autorisées

Vous pouvez restreindre une clé à des IP ou plages CIDR spécifiques depuis le tableau de bord développeur. Les requêtes provenant d’IP non listées reçoivent un 403. Une liste vide autorise toutes les IP.

Limites de débit

Deux compteurs : par minute et par mois. Votre palier est lu depuis votre compte à chaque requête — les mises à niveau prennent effet immédiatement — et les limites s’appliquent à l’ensemble de vos clés.

Palier/ minute/ mois

Basic301,000

Early Adopter403,000

Pro30025,000

Pro+1,000500,000

Sur mesureIllimitéIllimité

/me et /usage s’authentifient mais ne sont pas comptabilisés : demander où vous en êtes ne consomme pas le quota que vous consultez.

En-têtes

Envoyés sur chaque réponse, pas seulement en cas de rejet.

En-têteSignification

X-RateLimit-LimitNombre de requêtes autorisées par minute sur votre palier, ou « illimité ».

X-RateLimit-RemainingRequêtes restantes pour la minute en cours.

X-RateLimit-ResetSecondes avant la réinitialisation du compteur qui vous a bloqué.

En cas de limitation

L’API renvoie 429 — RATE_LIMITED pour le pic par minute, QUOTA_EXCEEDED pour le quota mensuel — avec le nombre de secondes à attendre dans retry_after.

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-minute rate limit exceeded",
    "retry_after": 37
  }
}

Erreurs

Les erreurs renvoient un statut hors 2xx et un objet error de premier niveau avec un code stable et un message. Vérifiez le code, pas le message — les messages peuvent changer.

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}

StatutCodeSignification

400BAD_REQUESTCorps ou paramètres de requête invalides.

401INVALID_KEYClé d’API manquante, mal formée ou inconnue.

401REVOKED_KEYLa clé d’API a été révoquée dans le tableau de bord.

403IP_NOT_AUTHORIZEDL’IP de la requête n’est pas dans la liste autorisée de la clé.

403FORBIDDENVotre palier n’a pas accès à ce point d’accès.

404NOT_FOUNDLa ressource demandée n’existe pas.

429RATE_LIMITEDLimite par minute dépassée.

429QUOTA_EXCEEDEDQuota mensuel épuisé ; réinitialisation au changement de mois UTC.

500INTERNALUne erreur de notre côté. Vous pouvez réessayer sans risque, avec un backoff.

Points d’accès

Les chemins ci-dessous sont relatifs à https://backend.qualit.ly/api/v1. Les boutiques sont weidian, taobao et 1688. Les points d’accès sans badge fonctionnent avec tous les plans.

Obtenir un produit

GET/products/{storefront}/{listing_id}

Une fiche produit unique par boutique et ID. Renvoie ses métadonnées et jusqu’à 5 miniatures d’aperçu QC. C’est le point d’accès par lequel la plupart des intégrations commencent.

ParamètreTypeDescription

storefrontrequisstringL’une de : weidian, taobao, 1688.

listing_idrequisstringL’identifiant de l’article, propre à la boutique.

Exemple

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

Réponse

json

{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
    "pic_gif": null,
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "qc_preview": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg"
    ]
  }
}

Rechercher des produits

GET/products/search

Recherchez dans le catalogue par nom de produit — l’URL du produit est aussi prise en compte. Pas de pagination : chaque plan renvoie jusqu’à un nombre fixe de résultats.

ParamètreTypeDescription

qrequisstringTexte de recherche. Plusieurs mots sont combinés en ET sur le nom et l’URL du produit.

storefrontstringRestreindre à weidian, taobao ou 1688.

has_qcbooleanUniquement les fiches produit ayant des photos QC.

limitintegerDemandez moins que le plafond de votre plan. Les valeurs au-delà sont ramenées à ce plafond, jamais augmentées.

Pas de pagination. Chaque plan renvoie jusqu’à un nombre fixe de résultats par recherche ; limit peut en demander moins, jamais plus.

PlanRésultats max

Basic5

Early Adopter10

Pro50

Pro+100

Sur mesure250

Exemple

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/products/search?q=jordan+1&storefront=weidian&has_qc=true&limit=10"

Réponse

json

{
  "query": "jordan 1",
  "count": 10,
  "limit": 10,
  "max_results": 100,
  "data": [
    {
      "id": 482910,
      "storefront": "weidian",
      "listing_id": "7231368393",
      "name": "AJ1 Retro High OG",
      "price": "¥470.00",
      "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
      "product_url": "https://weidian.com/item.html?itemID=7231368393",
      "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
      "qc_count": 12,
      "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
    }
  ]
}

Champs

ChampNotes

max_resultsLe plafond de votre plan — la limite maximale à laquelle `limit` est ramené.

countLe nombre de lignes réellement contenues dans cette réponse.

Produits par lot

Pro+

POST/products/batch

Résolvez jusqu’à 100 fiches produit en un seul appel. Chaque élément est résolu indépendamment : un produit manquant ne fait pas échouer le lot, il revient sous forme d’entrée d’erreur à la même position.

ParamètreTypeDescription

itemsrequisarrayTableau d’objets { storefront, listing_id }. Plafonné à 100, ou à la limite par page de votre plan si elle est plus basse.

Corps de la requête

json

{
  "items": [
    { "storefront": "weidian", "listing_id": "7231368393" },
    { "storefront": "taobao", "listing_id": "123456789" }
  ]
}

Exemple

bash

curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"storefront":"weidian","listing_id":"7231368393"}]}' \
  https://backend.qualit.ly/api/v1/products/batch

Réponse

json

{
  "results": [
    {
      "data": {
        "id": 482910,
        "storefront": "weidian",
        "listing_id": "7231368393",
        "name": "AJ1 Retro High OG",
        "price": "¥470.00",
        "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
        "qc_count": 12,
        "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
      }
    },
    { "error": { "code": "NOT_FOUND" } }
  ]
}

Produit aléatoire

POST/products/random

Une fiche produit aléatoire ayant des photos QC — pour des vitrines, des flux, ou pour échantillonner le catalogue. Aucun corps de requête nécessaire.

Exemple

bash

curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/random

Réponse

json

{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
  }
}

Métadonnées QC

GET/qc/{storefront}/{listing_id}

Le nombre de photos QC d’une fiche produit, plus les trois premières miniatures — sans récupérer la liste complète des images.

ParamètreTypeDescription

storefrontrequisstringL’une de : weidian, taobao, 1688.

listing_idrequisstringL’identifiant de l’article, propre à la boutique.

Exemple

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/weidian/7231368393

Réponse

json

{
  "data": {
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "thumbnails": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg",
      "https://cdn.qualit.ly/qc/0f19ab77.jpg"
    ]
  }
}

Images QC

Pro+

GET/qc/{id}/images

Toutes les photos QC indexées pour une fiche produit. Prend l’ID numérique du produit, ou passez ?url= avec n’importe quel lien produit pris en charge et laissez l’API le résoudre.

ParamètreTypeDescription

idrequisintegerID numérique du produit. Passez 0 lors d’une recherche par ?url=.

urlstringURL complète du produit à résoudre à la place d’un ID. Prend le pas quand elle est présente.

Par ID produit

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/482910/images

Par URL

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/qc/0/images?url=https://weidian.com/item.html?itemID=7231368393"

Réponse

json

{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "images": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg"
    ]
  }
}

Le paramètre ?url= accepte les liens produit de Weidian, Taobao et 1688, ainsi que de tous les agents pris en charge par le convertisseur de liens. Les images sont toujours des URL CDN.

Infos du compte

GET/me

Votre compte, la clé ayant effectué la requête et le palier qui en découle. Utile comme vérification de bon fonctionnement.

Exemple

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/me

Réponse

json

{
  "user": { "id": 12345, "username": "you" },
  "key": { "id": 7, "mode": "live" },
  "tier": "pro_plus"
}

Utilisation

GET/usage

Où vous en êtes dans les deux compteurs de limite de débit, avec les horodatages de réinitialisation. Comme /me, ce point d’accès s’authentifie mais n’est pas comptabilisé — consulter votre quota ne le consomme pas.

Exemple

bash

curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/usage

Réponse

json

{
  "tier": "pro_plus",
  "key": { "id": 7, "mode": "live" },
  "minute": {
    "limit": 1000,
    "used": 12,
    "remaining": 988,
    "reset_in_seconds": 37,
    "reset_at": "2026-08-20T18:42:00.000Z"
  },
  "month": {
    "limit": 500000,
    "used": 1843,
    "remaining": 498157,
    "reset_in_seconds": 1159200,
    "reset_at": "2026-09-01T00:00:00.000Z",
    "bucket": 202608
  }
}

Champs

ChampNotes

tierL’un de : basic, early_adopter, pro, pro_plus, custom.

limit / remainingnull sur le palier Custom, qui est illimité.

usedRequêtes dans la fenêtre actuelle. Le compteur par minute se réinitialise toutes les 60 s, le compteur mensuel au changement de mois UTC.

reset_atHorodatage UTC ISO 8601.

bucketClé interne AAAAMM pour le compteur mensuel.

Exemples de code

bash

curl -H "Authorization: Bearer $QUALITLY_KEY" \
  "https://backend.qualit.ly/api/v1/products/search?q=jordan+1&storefront=weidian"

Serveur MCP

La même API est proposée sous forme de serveur Model Context Protocol hébergé, afin que Claude, Cursor, VS Code ou tout autre client MCP puisse interroger les fiches produit et les jeux de photos QC sans écrire de HTTP. Votre clé d’API, vos limites de débit et les règles de palier restent inchangées.

URL du serveur

https://backend.qualit.ly/api/mcp

Transport

StreamableHTTP (POST)

Authentification

Authorization: Bearer qc_live_…

Outils

Seuls les outils accessibles à votre palier sont enregistrés : une clé Basic n’en voit jamais un qui lui serait refusé.

OutilDescriptionPlan

get_productRechercher un produit par boutique et ID de fiche.

search_productsRechercher par nom, avec filtres boutique et présence de QC.

get_products_batchRechercher jusqu’à 100 produits en un appel.Pro+

random_productUn produit aléatoire disposant de photos QC.

get_qcNombre de photos QC et les 3 premières miniatures.

get_qc_imagesListe complète des images CDN, par ID ou URL.Pro+

get_meClé, utilisateur et palier actuels.

get_usageÉtat du quota par minute et mensuel.

Claude Desktop, Cursor et VS Code

Ajoutez le serveur à claude_desktop_config.json (Claude → Paramètres → Développeur), ou aux paramètres MCP de votre éditeur.

Claude Desktop

json

{
  "mcpServers": {
    "qualitly": {
      "url": "https://backend.qualit.ly/api/mcp",
      "headers": {
        "Authorization": "Bearer qc_live_YOUR_KEY"
      }
    }
  }
}

Cursor / VS Code

json

{
  "mcp": {
    "servers": {
      "qualitly": {
        "url": "https://backend.qualit.ly/api/mcp",
        "headers": {
          "Authorization": "Bearer qc_live_YOUR_KEY"
        }
      }
    }
  }
}

Les clients qui prennent en charge la découverte OAuth — dont Claude.ai et ChatGPT — peuvent se passer entièrement de la clé codée en dur : une requête non authentifiée reçoit un en-tête WWW-Authenticate pointant vers les métadonnées OAuth du serveur, et le client fait passer vos utilisateurs par une page de connexion à la place.

Vérifier que ça fonctionne

bash

# List the tools your key can see
curl -X POST https://backend.qualit.ly/api/mcp \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Plans et paliers

Votre palier est déterminé à partir de votre compte à chaque requête, une mise à niveau s’applique donc dès le prochain appel — pas besoin d’une nouvelle clé. Les recherches par lot, les listes complètes d’images QC et l’extraction ?url= sont les seuls points d’accès réservés au-delà de Basic ; tout le reste ne varie qu’en volume.

Plan	/ minute	/ mois	Résultats de recherche
Basic	30	1,000	5
Early Adopterhérité	40	3,000	10
Pro	300	25,000	50
Pro+	1,000	500,000	100
Sur mesure	Illimité	Illimité	250

Early Adopter est hérité — réservé aux comptes existants, il n’est plus vendu. Besoin de plus que Pro+ ? [email protected] peut configurer des limites Custom.

Tous les plans, tarifs et avantages