Qualit.ly
Qualit.ly
HomeBot DiscordCerca

Riferimento API

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

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.

Esempio rapido

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

Autenticazione

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

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Formato della chiave

Le chiavi seguono 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.

Allowlist degli IP

Facoltativamente, limita le chiavi a IP o intervalli CIDR specifici tramite la 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. I limiti sono legati al livello del tuo account e si applicano a tutte le chiavi.

Livello
/ minuto
/ mese
Basic
30
1,000
Early Adopter
40
3,000
Pro
300
25,000
Pro+
1,000
500,000

Quando vieni limitato

L'API restituisce 429 con un header Retry-After.

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-minute limit exceeded",
    "retry_after": 12
  }
}

Errori

Tutti gli errori restituiscono un oggetto error di primo livello con code e message.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
400BAD_REQUESTCorpo della richiesta o parametri non validi.
401INVALID_KEYChiave API mancante, malformata o sconosciuta.
401REVOKED_KEYLa chiave API è 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, controlla Retry-After.
429QUOTA_EXCEEDEDQuota mensile esaurita; si azzera al cambio di mese UTC.
500INTERNALErrore del server. Riprova o contatta il supporto.

Endpoint

Base: https://backend.qualit.ly/api/v1. Negozi: weidian, taobao, 1688.

GET/products/:storefront/:listingIdBasic

Cerca un singolo prodotto per negozio e ID inserzione. Restituisce i metadati e fino a 5 anteprime QC.

Parametri

storefrontobbligatorio

Uno tra: weidian, taobao, 1688

listingIdobbligatorio

L'ID dell'inserzione del prodotto 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/...",
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qc_count": 12,
    "qc_preview": [
      "https://cdn.qualit.ly/qc/...",
      "https://cdn.qualit.ly/qc/..."
    ]
  }
}
GET/products/searchBasic

Cerca nel catalogo per nome prodotto (corrisponde anche all'URL del prodotto). Puoi filtrare facoltativamente per store o per prodotti con foto QC. Nessuna paginazione: il numero di risultati è limitato dal tuo piano.

Parametri di query

qobbligatorio

Testo da cercare. Più parole vengono confrontate in AND con il nome e l'URL del prodotto. (obbligatorio)

storefront

Facoltativo. Limita i risultati a uno tra: weidian, taobao, 1688

has_qc

Facoltativo. Imposta su true per restituire solo i prodotti con foto QC

limit

Facoltativo. Meno risultati rispetto al limite del tuo piano. I valori superiori al limite vengono ridotti, mai aumentati.

Limiti dei risultati

Nessuna paginazione. Ogni piano restituisce al massimo un numero fisso di risultati per ricerca. Passa un limite più basso per ottenerne meno; non puoi superare il limite del tuo piano.

Piano
Risultati max
Basic
5
Early Adopter
10
Pro
50
Pro+
100
Custom
250

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/...",
      "product_url": "https://weidian.com/item.html?itemID=7231368393",
      "qc_count": 12,
      "qc_preview": ["https://cdn.qualit.ly/qc/..."]
    }
  ]
}
POST/products/batchPro+

Cerca più prodotti in un'unica richiesta (fino a 100). Ogni risultato è indipendente, quindi un prodotto mancante non fa fallire il blocco.

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",
        "qc_count": 12,
        "qc_preview": ["..."]
      }
    },
    { "error": { "code": "NOT_FOUND" } }
  ]
}
GET/qc/:storefront/:listingIdBasic

Ottieni i metadati QC e i primi 3 URL delle anteprime per un prodotto.

Esempio

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/weidian/7231368393
json
{
  "data": {
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qc_count": 12,
    "thumbnails": ["..."]
  }
}
GET/qc/:id/imagesPro+

Elenco completo delle immagini QC. Accetta un ID prodotto numerico o un parametro di query ?url= per le ricerche basate su URL.

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",
    "qc_count": 12,
    "images": [
      "https://cdn.qualit.ly/qc/img1.jpg",
      "https://cdn.qualit.ly/qc/img2.jpg",
      "..."
    ]
  }
}
Solo Pro+. Il parametro ?url= accetta URL completi di prodotti da Weidian, Taobao, 1688 e agenti supportati.
GET/meBasic

Restituisce le info del tuo account, la chiave usata per la richiesta e il tuo livello attuale.

Esempio

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/me
json
{
  "user": { "id": 12345, "username": "you" },
  "key": { "id": 1, "mode": "live" },
  "tier": "basic"
}
GET/usageBasic

Controlla il tuo utilizzo attuale di limiti di frequenza e quota. Restituisce i contatori al minuto e al mese con i timestamp di reset. La chiamata stessa consuma 1 richiesta da entrambi i contatori.

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-04-17T18:42:00.000Z"
  },
  "month": {
    "limit": 500000,
    "used": 1843,
    "remaining": 498157,
    "reset_in_seconds": 1159200,
    "reset_at": "2026-05-01T00:00:00.000Z",
    "bucket": 202604
  }
}

Campi

tier

Uno tra: basic, early_adopter, pro, pro_plus, custom

limit / remaining

null sul livello custom (illimitato)

used

Richieste conteggiate nella finestra attuale. Il contatore al minuto si azzera ogni 60s; quello mensile al cambio di mese UTC.

reset_at

Timestamp UTC ISO 8601

bucket

Chiave interna YYYYMM per il contatore mensile

Errori

Come per gli altri endpoint /api/v1/*:401 INVALID_KEY /REVOKED_KEY,403 IP_NOT_AUTHORIZED,429 RATE_LIMITED /QUOTA_EXCEEDED.

Esempi di codice

Snippet di avvio rapido nei linguaggi più popolari.

const res = await fetch(
  'https://backend.qualit.ly/api/v1/products/weidian/7231368393',
  { headers: { Authorization: 'Bearer ' + process.env.QUALITLY_KEY } }
);
const { data } = await res.json();
console.log(data.name, data.qc_count, 'QC images');

Server MCP

L'API di Qualit.ly è disponibile come server Model Context Protocol (MCP). Collegalo a Claude Desktop, Cursor, VS Code o a qualsiasi client compatibile con MCP e interroga prodotti, immagini QC e dati di utilizzo direttamente dal tuo assistente IA, senza HTTP manuale. Si applicano la stessa chiave API, gli stessi limiti di frequenza e le stesse regole di livello.

URL del server

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

Trasporto

StreamableHTTP (POST)

Autenticazione

Authorization: Bearer qc_live_…

Strumenti disponibili

Strumento
Descrizione
Livello
get_product
Cerca un prodotto per negozio e ID inserzione
Basic
search_products
Cerca prodotti per nome, con filtri per store e presenza di foto QC
Basic
get_products_batch
Cerca fino a 100 prodotti in una sola chiamata
Pro+
get_qc
Conteggio QC e 3 URL di anteprima
Basic
get_qc_images
Elenco completo delle immagini CDN (per ID o URL)
Pro+
get_me
Chiave, utente e livello attuali
Basic
get_usage
Stato della quota al minuto e mensile
Basic
OAuth 2.0 supportato. I client che supportano l'auto-discovery OAuth (Claude.ai, ChatGPT, ecc.) chiederanno automaticamente ai tuoi utenti di autorizzare tramite una pagina di accesso, senza alcuna chiave hardcoded. Il server espone i suoi endpoint OAuth a https://backend.qualit.ly/.well-known/oauth-authorization-server.

Claude Desktop (chiave hardcoded)

Aggiungi questo al tuo claude_desktop_config.json (Claude → Impostazioni → Sviluppatore):

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

Cursor / VS Code (chiave hardcoded)

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

Verifica rapida

bash
# List available tools
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 a ogni richiesta, quindi gli upgrade hanno effetto immediato. Gli endpoint per blocchi e immagini complete richiedono Pro+.

Piano
/ minuto
/ mese
Blocco + immagini
Basic
30
1,000
—
Early Adopter
40
3,000
—
Pro
300
25,000
—
Pro+
1,000
500,000
Incluso

Ti servono limiti più alti? [email protected]

Vedi tutti i piani, prezzi e vantaggi
Qualit.ly

Foto QC gratuite e il convertitore di link Discord per Taobao, Weidian e 1688.

Strumenti

  • Cerca foto QC
  • Trova foto QC
  • Convertitore di link Discord
  • Tracciamento ordini
  • API REST pubblica

Esplora

  • Cerca prodotti
  • Di tendenza
  • In evidenza
  • Fogli della community
  • Server Discord
  • Coupon

Marketplace

  • Foto QC Weidian
  • Foto QC Taobao
  • Foto QC 1688

Risorse

  • Piani e prezzi
  • Chi siamo
  • Contatti
  • Termini di servizio
  • Informativa sulla privacy
  • Community Discord
  • r/qualitly
  • Canale Telegram

© Qualit.ly. Gratis per la community rep finds.

Domande? [email protected]