Salt la conținut

Mai multe

Limbă și monedă

Qualit.ly API

Date despre produse, imagini QC și metadate de pe Weidian, Taobao și 1688. Autentificare cu token Bearer, limite de rată generoase, planuri pe niveluri.

Obține cheia APIStart rapid

Primii pași

Toate cererile merg către https://backend.qualit.ly/api/v1. Trei pași:

  1. 1

    Obține o cheie

    Autentifică-te și creează o cheie API din panoul pentru dezvoltatori.

  2. 2

    Fă o cerere

    Trimite-ți cheia ca token Bearer în antetul Authorization.

  3. 3

    Obține date

    Primești răspunsuri JSON cu date despre produse și imagini QC.

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

Autentificare

Include o cheie API validă în antetul Authorization folosind schema Bearer.

http
Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Formatul cheii

Cheile urmează formatul qc_{mode}_{random}, unde mode este live sau test, iar random reprezintă 32 de caractere aleatorii criptografic.

Cheile sunt afișate o singură dată, la creare. Stocăm doar hash-ul SHA-256, așa că cheile pierdute nu pot fi recuperate — revocă-o și generează una nouă.

Listă de permisiuni IP

Opțional, poți restricționa cheile la anumite IP-uri sau intervale CIDR din panoul pentru dezvoltatori. Cererile de la IP-uri nelistate primesc un 403. O listă de permisiuni goală permite toate IP-urile.

Limite de rată

Două praguri: pe minut și pe lună. Nivelul contului tău este citit la fiecare cerere — upgrade-urile intră în vigoare imediat — iar limitele se aplică tuturor cheilor tale.

Nivel/ minut/ lună
Basic301,000
Early Adopter403,000
Pro30025,000
Pro+1,000500,000
CustomNelimitatNelimitat

/me și /usage se autentifică, dar nu sunt contorizate: a întreba unde te afli nu îți consumă cota despre care întrebi.

Anteturi

Trimise la fiecare răspuns, nu doar la respingeri.

X-RateLimit-LimitNumărul de cereri permise pe minut la nivelul tău, sau „nelimitat”.
X-RateLimit-RemainingCereri rămase în minutul curent.
X-RateLimit-ResetSecunde până la resetarea contorului care te-a blocat.

Când ești limitat de rată

API-ul returnează 429 — RATE_LIMITED pentru vârful de pe minut, QUOTA_EXCEEDED pentru cota lunară — cu numărul de secunde de așteptare în retry_after.

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

Erori

Erorile returnează un status non-2xx și un obiect error de nivel superior, cu un code stabil și un message. Potrivește după cod, nu după mesaj — mesajele se pot schimba.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
400BAD_REQUESTCorp sau parametri de cerere nevalizi.
401INVALID_KEYCheie API lipsă, malformată sau necunoscută.
401REVOKED_KEYCheia a fost revocată în panou.
403IP_NOT_AUTHORIZEDIP-ul cererii nu se află în lista de permisiuni a cheii.
403FORBIDDENNivelul tău nu are acces la acest endpoint.
404NOT_FOUNDResursa solicitată nu există.
429RATE_LIMITEDLimita pe minut a fost depășită.
429QUOTA_EXCEEDEDCota lunară a fost epuizată; se resetează la trecerea în luna următoare, ora UTC.
500INTERNALVina noastră. Poți reîncerca în siguranță, cu backoff.

Endpoint-uri

Căile de mai jos sunt relative la https://backend.qualit.ly/api/v1. Magazinele sunt weidian, taobao și 1688. Endpoint-urile fără etichetă funcționează pe orice plan.

Obține produs

GET/products/{storefront}/{listing_id}

Un singur produs, după magazin și ID. Returnează metadatele lui și până la 5 miniaturi de previzualizare QC. Acesta este endpoint-ul de la care pornesc majoritatea integrărilor.

storefrontobligatoriustringUnul dintre: weidian, taobao, 1688.
listing_idobligatoriustringID-ul propriu al produsului la acel magazin.

Exemplu

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

Răspuns

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

Caută produse

GET/products/search

Caută în catalog după numele produsului — se potrivește și URL-ul produsului. Nu există paginare: fiecare plan returnează până la un număr fix de rezultate.

qobligatoriustringText de căutare. Mai multe cuvinte sunt potrivite cu AND față de numele și URL-ul produsului.
storefrontstringLimitează la weidian, taobao sau 1688.
has_qcbooleanDoar produsele care au fotografii QC.
limitintegerCere mai puține rezultate decât plafonul planului tău. Valorile peste plafon sunt reduse — niciodată mărite.

Fără paginare. Fiecare plan returnează până la un număr fix de rezultate per căutare; limit poate cere mai puține, niciodată mai multe.

PlanRezultate maxime
Basic5
Early Adopter10
Pro50
Pro+100
Custom250

Exemplu

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ăspuns

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

Câmpuri

max_resultsPlafonul planului tău — limita maximă la care este redus `limit`.
countCâte rânduri conține efectiv acest răspuns.

Produse în lot

Pro+
POST/products/batch

Rezolvă până la 100 de produse într-un singur apel. Fiecare element este rezolvat independent, așa că un produs lipsă nu face lotul să eșueze — revine ca o intrare de eroare, pe aceeași poziție.

itemsobligatoriuarrayListă de obiecte { storefront, listing_id }. Plafonată la 100, sau la limita per pagină a planului tău, dacă aceasta este mai mică.

Corpul cererii

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

Exemplu

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ăspuns

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

Produs aleatoriu

POST/products/random

Un produs aleatoriu care are fotografii QC — pentru vitrine, fluxuri sau eșantionarea catalogului. Nu necesită corp de cerere.

Exemplu

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

Răspuns

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

Metadate QC

GET/qc/{storefront}/{listing_id}

Numărul de fotografii QC pentru un produs, plus primele trei miniaturi — fără să extragă lista completă de imagini.

storefrontobligatoriustringUnul dintre: weidian, taobao, 1688.
listing_idobligatoriustringID-ul propriu al produsului la acel magazin.

Exemplu

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

Răspuns

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

Imagini QC

Pro+
GET/qc/{id}/images

Fiecare fotografie QC indexată pentru un produs. Acceptă ID-ul numeric al produsului sau parametrul ?url= cu orice link de produs acceptat, iar API-ul îl rezolvă.

idobligatoriuintegerID-ul numeric al produsului. Trimite 0 când cauți după ?url=.
urlstringURL-ul complet al produsului, de rezolvat în locul unui ID. Are prioritate atunci când este prezent.

După ID de produs

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

După 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ăspuns

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

Parametrul ?url= acceptă linkuri de produs de pe Weidian, Taobao și 1688, precum și de la orice agent acceptat de convertorul de linkuri. Imaginile sunt întotdeauna URL-uri CDN.

Informații cont

GET/me

Contul tău, cheia care a făcut cererea și nivelul la care se rezolvă. Util ca verificare de funcționare.

Exemplu

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

Răspuns

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

Utilizare

GET/usage

Unde te afli în cele două praguri de limită de rată, cu marcaje de timp de resetare. La fel ca /me, acest endpoint se autentifică, dar nu este contorizat — a întreba despre cota ta nu o consumă.

Exemplu

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

Răspuns

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

Câmpuri

tierUnul dintre: basic, early_adopter, pro, pro_plus, custom.
limit / remainingnull la nivelul Custom, care este nelimitat.
usedCereri numărate în fereastra curentă. Contorul pe minut se resetează la fiecare 60 s, contorul lunar la trecerea în luna următoare, ora UTC.
reset_atISO 8601, UTC.
bucketCheie internă YYYYMM pentru contorul lunar.

Exemple de cod

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

Server MCP

Același API este oferit ca server Model Context Protocol găzduit, așa că Claude, Cursor, VS Code sau orice client MCP poate interoga produse și seturi QC fără să scrie cod HTTP. Cheia ta API, limitele de rată și regulile de nivel rămân neschimbate.

URL server

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

Transport

StreamableHTTP (POST)

Autentificare

Authorization: Bearer qc_live_…

Instrumente

Sunt înregistrate doar instrumentele pe care nivelul tău le poate apela, așa că o cheie Basic nu vede niciodată unul care i-ar fi refuzat.

get_productCaută un produs după magazin și ID de anunț.
search_productsCaută după nume, cu filtre pentru magazin și prezența QC.
get_products_batchCaută până la 100 de produse într-un singur apel.Pro+
random_productUn produs aleatoriu care are fotografii QC.
get_qcNumărul de fotografii QC și primele 3 miniaturi.
get_qc_imagesListă completă de imagini CDN, după ID sau URL.Pro+
get_meCheia, utilizatorul și nivelul curent.
get_usageStarea cotei pe minut și lunare.

Claude Desktop, Cursor și VS Code

Adaugă serverul în claude_desktop_config.json (Claude → Setări → Dezvoltator), sau în setările MCP ale editorului tău.

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

Clienții care acceptă descoperirea OAuth — printre care Claude.ai și ChatGPT — pot renunța complet la cheia codificată în cod: o cerere neautentificată primește ca răspuns un antet WWW-Authenticate care indică metadatele OAuth ale serverului, iar clientul îi ghidează pe utilizatorii tăi printr-o pagină de autentificare.

Verifică că funcționează

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

Planuri și niveluri

Nivelul tău este determinat din contul tău la fiecare cerere, așa că un upgrade se aplică de la următorul apel — fără să ai nevoie de o cheie nouă. Căutările în lot, listele complete de imagini QC și extragerea prin ?url= sunt singurele endpoint-uri restricționate peste Basic; tot restul diferă doar prin volum.

Plan/ minut/ lunăRezultate căutareLoturi + imagini
Basic301,0005
Early Adoptervechi403,00010
Pro30025,00050
Pro+1,000500,000100
CustomNelimitatNelimitat250

Early Adopter este un plan vechi — păstrat de conturile existente, dar nu se mai vinde. Ai nevoie de mai mult decât Pro+? [email protected] configurează limite Custom.

Vezi planurile complete, prețurile și avantajele
Caută

Cookie-uri

Le folosim ca să rămâi autentificat și să reținem produsele salvate. Analiza doar dacă accepți.