Qualit.ly API

Dati dei prodotti, immagini QC e metadati da Weidian, Taobao e 1688. Autenticazione con bearer token, limiti di frequenza generosi, piani a livelli.

Ottieni una chiave API Guida rapida

Per iniziare

Tutte le richieste vanno a https://backend.qualit.ly/api/v1. Tre passaggi:

1
Ottieni una chiave
Accedi e crea una chiave API dalla dashboard per sviluppatori.
2
Effettua una richiesta
Invia la tua chiave come bearer token nell'header Authorization.
3
Ottieni i dati
Ricevi risposte JSON con dati dei prodotti e immagini QC.

bash

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

Autenticazione

Includi una chiave API valida nell'header Authorization usando lo schema Bearer.

http

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Formato della chiave

Le chiavi seguono il formato qc_{mode}_{random}, dove mode è live o test e random è composto da 32 caratteri crittograficamente casuali.

Le chiavi vengono mostrate una sola volta alla creazione. Memorizziamo solo l'hash SHA-256, quindi le chiavi smarrite non possono essere recuperate — revocala e generane una nuova.

Allowlist degli IP

Facoltativamente, limita le chiavi a IP o intervalli CIDR specifici dalla dashboard per sviluppatori. Le richieste da IP non elencati ricevono un 403. Una allowlist vuota consente tutti gli IP.

Limiti di frequenza

Due bucket: al minuto e al mese. Il tuo livello viene letto dal tuo account a ogni richiesta — gli upgrade hanno effetto immediato — e i limiti si applicano a tutte le tue chiavi.

Livello/ minuto/ mese

Basic301,000

Early Adopter403,000

Pro30025,000

Pro+1,000500,000

CustomIllimitatoIllimitato

/me e /usage richiedono l'autenticazione ma non vengono conteggiati: chiedere a che punto sei non consuma la quota di cui stai chiedendo.

Header

Incluso in ogni risposta, non solo nei rifiuti.

HeaderSignificato

X-RateLimit-LimitRichieste consentite al minuto per il tuo livello, oppure "illimitato".

X-RateLimit-RemainingRichieste rimaste nel minuto corrente.

X-RateLimit-ResetSecondi mancanti all'azzeramento del contatore che ti ha bloccato.

Quando vieni limitato

L'API restituisce 429 — RATE_LIMITED per il picco al minuto, QUOTA_EXCEEDED per la quota mensile — con i secondi di attesa in retry_after.

json

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

Errori

Gli errori restituiscono uno stato non-2xx e un oggetto error di primo livello con un code stabile e un message. Verifica il code, non il message — i messaggi possono cambiare.

json

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

StatoCodiceSignificato

400BAD_REQUESTCorpo della richiesta o parametri non validi.

401INVALID_KEYChiave API mancante, malformata o sconosciuta.

401REVOKED_KEYLa chiave è stata revocata nella dashboard.

403IP_NOT_AUTHORIZEDL'IP della richiesta non è nell'allowlist della chiave.

403FORBIDDENIl tuo livello non ha accesso a questo endpoint.

404NOT_FOUNDLa risorsa richiesta non esiste.

429RATE_LIMITEDLimite al minuto superato.

429QUOTA_EXCEEDEDQuota mensile esaurita; si azzera al cambio di mese UTC.

500INTERNALColpa nostra. Puoi riprovare in sicurezza con backoff.

Endpoint

I percorsi qui sotto sono relativi a https://backend.qualit.ly/api/v1. I negozi sono weidian, taobao e 1688. Gli endpoint senza badge funzionano con ogni piano.

Ottieni prodotto

GET/products/{storefront}/{listing_id}

Una singola inserzione tramite negozio e ID. Restituisce i suoi metadati e fino a 5 anteprime QC. È l'endpoint da cui iniziano la maggior parte delle integrazioni.

ParametroTipoDescrizione

storefrontobbligatoriostringUno tra weidian, taobao, 1688.

listing_idobbligatoriostringL'ID dell'inserzione assegnato dal negozio.

Esempio

bash

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

Risposta

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"
    ]
  }
}

Cerca prodotti

GET/products/search

Cerca nel catalogo per nome del prodotto — viene verificato anche l'URL del prodotto. Non c'è paginazione: ogni piano restituisce fino a un numero fisso di risultati.

ParametroTipoDescrizione

qobbligatoriostringTesto di ricerca. Più parole vengono confrontate in AND rispetto al nome e all'URL del prodotto.

storefrontstringLimita a weidian, taobao o 1688.

has_qcbooleanSolo le inserzioni con foto QC.

limitintegerRichiedi un numero inferiore al limite del tuo piano. I valori superiori vengono ridotti automaticamente, mai aumentati.

Nessuna paginazione. Ogni piano restituisce fino a un numero fisso di risultati per ricerca; limit può chiederne di meno, mai di più.

PianoRisultati massimi

Basic5

Early Adopter10

Pro50

Pro+100

Custom250

Esempio

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"

Risposta

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"]
    }
  ]
}

Campi

CampoNote

max_resultsIl limite del tuo piano — il tetto massimo a cui `limit` viene ridotto.

countQuante righe contiene effettivamente questa risposta.

Prodotti in blocco

Pro+

POST/products/batch

Risolvi fino a 100 inserzioni in un'unica chiamata. Ogni elemento viene risolto in modo indipendente, quindi un prodotto mancante non fa fallire l'intero blocco — torna come voce di errore nella stessa posizione.

ParametroTipoDescrizione

itemsobbligatorioarrayArray di oggetti { storefront, listing_id }. Limitato a 100, oppure al limite per pagina del tuo piano se inferiore.

Corpo della richiesta

json

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

Esempio

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

Risposta

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" } }
  ]
}

Prodotto casuale

POST/products/random

Un'inserzione casuale con foto QC — utile per vetrine, feed o il campionamento del catalogo. Non serve alcun corpo della richiesta.

Esempio

bash

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

Risposta

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"]
  }
}

Metadati QC

GET/qc/{storefront}/{listing_id}

Il numero di foto QC di un'inserzione, più le prime tre anteprime — senza scaricare l'elenco completo delle immagini.

ParametroTipoDescrizione

storefrontobbligatoriostringUno tra weidian, taobao, 1688.

listing_idobbligatoriostringL'ID dell'inserzione assegnato dal negozio.

Esempio

bash

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

Risposta

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"
    ]
  }
}

Immagini QC

Pro+

GET/qc/{id}/images

Tutte le foto QC indicizzate per un'inserzione. Richiede l'ID numerico del prodotto, oppure passa ?url= con qualsiasi link di prodotto supportato e lascia che sia l'API a risolverlo.

ParametroTipoDescrizione

idobbligatoriointegerID numerico del prodotto. Passa 0 quando cerchi tramite ?url=.

urlstringURL completo del prodotto da risolvere al posto di un ID. Ha la precedenza quando presente.

Per ID prodotto

bash

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

Per 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"

Risposta

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"
    ]
  }
}

Il parametro ?url= accetta link di prodotti da Weidian, Taobao e 1688, e da ogni agente supportato dal Link Converter. Le immagini sono sempre URL CDN.

Info account

GET/me

Il tuo account, la chiave che ha effettuato questa richiesta e il livello a cui corrisponde. Utile come controllo di funzionamento.

Esempio

bash

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

Risposta

json

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

Utilizzo

GET/usage

A che punto sei in entrambi i bucket dei limiti di frequenza, con i timestamp di reset. Come /me, questo endpoint richiede autenticazione ma non viene conteggiato — chiedere informazioni sulla tua quota non la consuma.

Esempio

bash

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

Risposta

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
  }
}

Campi

CampoNote

tierUno tra basic, early_adopter, pro, pro_plus, custom.

limit / remainingnull sul livello Custom, che è illimitato.

usedRichieste nella finestra corrente. Il contatore al minuto si azzera ogni 60s, quello mensile al cambio di mese UTC.

reset_atISO 8601, UTC.

bucketChiave interna YYYYMM per il contatore mensile.

Esempi di codice

bash

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

Server MCP

La stessa API è disponibile come server Model Context Protocol ospitato, così Claude, Cursor, VS Code o qualsiasi client MCP possono interrogare inserzioni e set di foto QC senza scrivere HTTP. La tua chiave API, i limiti di frequenza e le regole di livello restano invariati.

URL del server

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

Trasporto

StreamableHTTP (POST)

Autenticazione

Authorization: Bearer qc_live_…

Strumenti

Vengono registrati solo gli strumenti che il tuo livello può chiamare, quindi una chiave Basic non ne vede mai uno per cui verrebbe rifiutata.

StrumentoDescrizionePiano

get_productCerca un prodotto per negozio e ID inserzione.

search_productsCerca per nome, con filtri per negozio e presenza di foto QC.

get_products_batchCerca fino a 100 prodotti in una sola chiamata.Pro+

random_productUn prodotto casuale con foto QC.

get_qcConteggio QC e le prime 3 anteprime.

get_qc_imagesElenco completo delle immagini CDN, per ID o URL.Pro+

get_meChiave, utente e livello attuali.

get_usageStato della quota al minuto e mensile.

Claude Desktop, Cursor e VS Code

Aggiungi il server a claude_desktop_config.json (Claude → Impostazioni → Sviluppatore), oppure alle impostazioni MCP del tuo editor.

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"
        }
      }
    }
  }
}

I client che supportano la discovery OAuth — tra cui Claude.ai e ChatGPT — possono fare a meno della chiave hardcoded: una richiesta non autenticata riceve come risposta un header WWW-Authenticate che punta ai metadati OAuth del server, e il client guida i tuoi utenti attraverso una pagina di accesso al suo posto.

Verifica che funzioni

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":{}}'

Piani e livelli

Il tuo livello viene risolto dal tuo account a ogni richiesta, quindi un upgrade si applica già alla chiamata successiva — non serve una nuova chiave. Le ricerche in blocco, gli elenchi completi delle immagini QC e l'estrazione tramite ?url= sono gli unici endpoint riservati oltre il livello Basic; tutto il resto cambia solo per volume.

Piano	/ minuto	/ mese	Risultati di ricerca
Basic	30	1,000	5
Early AdopterLegacy	40	3,000	10
Pro	300	25,000	50
Pro+	1,000	500,000	100
Custom	Illimitato	Illimitato	250

Early Adopter è un piano legacy — riservato agli account esistenti, non più in vendita. Ti serve più di Pro+? [email protected] imposta i limiti Custom.

Vedi tutti i piani, prezzi e vantaggi