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

Free QC photos and the Discord link converter for Taobao, Weidian and 1688.

Tools

  • Search QC photos
  • Discord link converter
  • Curated spreadsheets
  • Order tracking
  • Public REST API

Marketplaces

  • Weidian QC photos
  • Taobao QC photos
  • 1688 QC photos

Resources

  • Plans & pricing
  • About Qualit.ly
  • Contact
  • Terms of Service
  • Privacy Policy
  • Discord community
  • r/qualitly
  • Telegram channel

© Qualit.ly. Free for the rep finds community.

Questions? [email protected]