Qualit.ly API

Dane produktów, obrazy QC i metadane z Weidian, Taobao i 1688. Uwierzytelnianie bearer tokenem, hojne limity, plany wielopoziomowe.

Uzyskaj klucz API Szybki start

Pierwsze kroki

Wszystkie żądania trafiają do https://backend.qualit.ly/api/v1. Trzy kroki:

1
Uzyskaj klucz
Zaloguj się i utwórz klucz API w panelu dewelopera.
2
Wykonaj żądanie
Wyślij swój klucz jako bearer token w nagłówku Authorization.
3
Pobierz dane
Otrzymuj odpowiedzi JSON z danymi produktów i obrazami QC.

bash

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

Uwierzytelnianie

Dołącz prawidłowy klucz API w nagłówku Authorization, używając schematu Bearer.

http

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Format klucza

Klucze mają postać qc_{mode}_{random}, gdzie mode to live lub test, a random to 32 kryptograficznie losowe znaki.

Klucze są pokazywane tylko raz przy tworzeniu. Przechowujemy jedynie hash SHA-256, więc zgubionych kluczy nie można odzyskać — unieważnij go i wygeneruj nowy.

Lista dozwolonych IP

Opcjonalnie ogranicz klucze do konkretnych IP lub zakresów CIDR w panelu dewelopera. Żądania z niewymienionych IP otrzymują 403. Pusta lista dozwolonych zezwala na wszystkie IP.

Limity częstotliwości

Dwa koszyki: na minutę i na miesiąc. Twój poziom jest odczytywany z konta przy każdym żądaniu — ulepszenia działają natychmiast — a limity obowiązują dla wszystkich twoich kluczy.

Poziom/ minutę/ miesiąc

Basic301,000

Early Adopter403,000

Pro30025,000

Pro+1,000500,000

CustomBez limituBez limitu

/me i /usage wymagają uwierzytelnienia, ale nie są liczone do limitu: sprawdzenie, na czym stoisz, nie zużywa limitu, o który pytasz.

Nagłówki

Wysyłane w każdej odpowiedzi, nie tylko przy odrzuceniach.

NagłówekZnaczenie

X-RateLimit-LimitLiczba żądań dozwolonych na minutę w twoim planie, lub „bez limitu”.

X-RateLimit-RemainingLiczba żądań pozostałych w bieżącej minucie.

X-RateLimit-ResetLiczba sekund do zresetowania licznika, który cię zablokował.

Gdy zostaniesz ograniczony

API zwraca 429 — RATE_LIMITED dla przekroczenia limitu na minutę, QUOTA_EXCEEDED dla miesięcznego limitu — z liczbą sekund do odczekania w retry_after.

json

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

Błędy

Błędy zwracają status inny niż 2xx oraz obiekt error najwyższego poziomu ze stałym code i message. Dopasowuj po kodzie, nie po treści komunikatu — komunikaty mogą się zmieniać.

json

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

StatusKodZnaczenie

400BAD_REQUESTNieprawidłowe ciało żądania lub parametry.

401INVALID_KEYBrakujący, zniekształcony lub nieznany klucz API.

401REVOKED_KEYKlucz API został unieważniony w panelu.

403IP_NOT_AUTHORIZEDIP żądania nie znajduje się na liście dozwolonych klucza.

403FORBIDDENTwój poziom nie ma dostępu do tego endpointu.

404NOT_FOUNDŻądany zasób nie istnieje.

429RATE_LIMITEDPrzekroczono limit na minutę.

429QUOTA_EXCEEDEDMiesięczny limit wyczerpany; resetuje się przy zmianie miesiąca UTC.

500INTERNALNasza wina. Można bezpiecznie ponowić próbę ze wzrastającym opóźnieniem (backoff).

Endpointy

Poniższe ścieżki są względne wobec https://backend.qualit.ly/api/v1. Sklepy to weidian, taobao i 1688. Endpointy bez oznaczenia poziomu działają w każdym planie.

Pobierz produkt

GET/products/{storefront}/{listing_id}

Pojedyncza oferta według sklepu i ID. Zwraca jej metadane oraz do 5 miniatur podglądu QC. To endpoint, od którego zaczyna większość integracji.

ParametrTypOpis

storefrontwymaganestringJeden z: weidian, taobao, 1688.

listing_idwymaganestringWłasny identyfikator oferty w danym sklepie.

Przykład

bash

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

Odpowiedź

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

Szukaj produktów

GET/products/search

Przeszukuj katalog po nazwie produktu — dopasowywany jest też adres URL produktu. Brak paginacji: każdy plan zwraca do ustalonej liczby wyników.

ParametrTypOpis

qwymaganestringTekst wyszukiwania. Kilka słów jest dopasowywanych operatorem AND do nazwy i adresu URL produktu.

storefrontstringOgranicz do weidian, taobao lub 1688.

has_qcbooleanTylko oferty, które mają zdjęcia QC.

limitintegerPoproś o mniej niż limit twojego planu. Wartości powyżej niego są przycinane w dół, nigdy w górę.

Brak paginacji. Każdy plan zwraca do ustalonej liczby wyników na wyszukiwanie; limit może poprosić o mniej, nigdy o więcej.

PlanMaks. wyników

Basic5

Early Adopter10

Pro50

Pro+100

Custom250

Przykład

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"

Odpowiedź

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

Pola

PoleUwagi

max_resultsLimit twojego planu — pułap, do którego przycinany jest `limit`.

countIle wierszy faktycznie zawiera ta odpowiedź.

Produkty zbiorczo

Pro+

POST/products/batch

Rozwiąż do 100 ofert w jednym wywołaniu. Każdy element jest rozwiązywany niezależnie, więc brakujący produkt nie powoduje niepowodzenia całej partii — wraca jako wpis błędu na tej samej pozycji.

ParametrTypOpis

itemswymaganearrayTablica obiektów { storefront, listing_id }. Ograniczona do 100 lub do limitu na stronę w twoim planie, jeśli jest niższy.

Ciało żądania

json

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

Przykład

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

Odpowiedź

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

Losowy produkt

POST/products/random

Jedna losowa oferta ze zdjęciami QC — do prezentacji, kanałów lub próbkowania katalogu. Ciało żądania nie jest potrzebne.

Przykład

bash

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

Odpowiedź

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

Metadane QC

GET/qc/{storefront}/{listing_id}

Liczba zdjęć QC dla oferty, plus pierwsze trzy miniatury — bez pobierania pełnej listy obrazów.

ParametrTypOpis

storefrontwymaganestringJeden z: weidian, taobao, 1688.

listing_idwymaganestringWłasny identyfikator oferty w danym sklepie.

Przykład

bash

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

Odpowiedź

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

Obrazy QC

Pro+

GET/qc/{id}/images

Każde zindeksowane zdjęcie QC dla oferty. Przyjmuje numeryczne ID produktu albo parametr ?url= z dowolnym obsługiwanym linkiem do produktu — API rozwiąże go samodzielnie.

ParametrTypOpis

idwymaganeintegerNumeryczne ID produktu. Przekaż 0 przy wyszukiwaniu przez ?url=.

urlstringPełny adres URL produktu do rozwiązania zamiast ID. Ma pierwszeństwo, gdy jest podany.

Według ID produktu

bash

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

Według 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"

Odpowiedź

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

Parametr ?url= akceptuje linki do produktów z Weidian, Taobao i 1688 oraz od każdego agenta obsługiwanego przez konwerter linków. Obrazy to zawsze adresy URL CDN.

Informacje o koncie

GET/me

Twoje konto, klucz użyty do żądania i poziom, do którego się rozwiązuje. Przydatne jako szybka kontrola stanu.

Przykład

bash

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

Odpowiedź

json

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

Wykorzystanie

GET/usage

Twój stan w obu koszykach limitów, ze znacznikami czasu resetu. Podobnie jak /me, ten endpoint wymaga uwierzytelnienia, ale nie jest liczony do limitu — sprawdzenie limitu go nie zużywa.

Przykład

bash

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

Odpowiedź

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

Pola

PoleUwagi

tierJeden z: basic, early_adopter, pro, pro_plus, custom.

limit / remainingnull na poziomie Custom, który jest nieograniczony.

usedŻądania zliczone w bieżącym oknie. Licznik na minutę resetuje się co 60s; miesięczny przy zmianie miesiąca UTC.

reset_atZnacznik czasu UTC ISO 8601.

bucketWewnętrzny klucz YYYYMM dla licznika miesięcznego.

Przykłady kodu

bash

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

Serwer MCP

To samo API jest udostępniane jako hostowany serwer Model Context Protocol, dzięki czemu Claude, Cursor, VS Code lub dowolny klient MCP może odpytywać oferty i zestawy QC bez pisania HTTP. Twój klucz API, limity częstotliwości i zasady poziomów pozostają bez zmian.

URL serwera

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

Transport

StreamableHTTP (POST)

Uwierzytelnianie

Authorization: Bearer qc_live_…

Narzędzia

Rejestrowane są tylko narzędzia dostępne dla twojego poziomu, więc klucz Basic nigdy nie widzi narzędzia, do którego i tak nie miałby dostępu.

NarzędzieOpisPlan

get_productWyszukaj produkt według sklepu i ID oferty.

search_productsSzukaj po nazwie, z filtrami sklepu i posiadania zdjęć QC.

get_products_batchWyszukaj do 100 produktów w jednym wywołaniu.Pro+

random_productLosowy produkt ze zdjęciami QC.

get_qcLiczba zdjęć QC i pierwsze 3 miniatury.

get_qc_imagesPełna lista obrazów CDN, według ID lub URL.Pro+

get_meAktualny klucz, użytkownik i poziom.

get_usageStatus limitu na minutę i miesięcznego.

Claude Desktop, Cursor i VS Code

Dodaj serwer do claude_desktop_config.json (Claude → Ustawienia → Deweloper) albo do ustawień MCP swojego edytora.

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

Klienci obsługujący automatyczne wykrywanie OAuth — w tym Claude.ai i ChatGPT — mogą całkowicie pominąć zakodowany na stałe klucz: nieuwierzytelnione żądanie otrzymuje w odpowiedzi nagłówek WWW-Authenticate wskazujący na metadane OAuth serwera, a klient prowadzi twoich użytkowników przez stronę logowania zamiast tego.

Sprawdź, czy działa

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

Plany i poziomy

Twój poziom jest ustalany na podstawie konta przy każdym żądaniu, więc ulepszenie planu obowiązuje już od następnego wywołania — bez potrzeby nowego klucza. Wyszukiwania zbiorcze, pełne listy obrazów QC i ekstrakcja przez ?url= to jedyne endpointy zablokowane powyżej planu Basic; wszystko inne różni się tylko wolumenem.

Plan	/ minutę	/ miesiąc	Wyniki wyszukiwania
Basic	30	1,000	5
Early Adopterlegacy	40	3,000	10
Pro	300	25,000	50
Pro+	1,000	500,000	100
Custom	Bez limitu	Bez limitu	250

Early Adopter to plan legacy — utrzymywany przez istniejące konta, nigdy niesprzedawany. Potrzebujesz więcej niż Pro+? [email protected] ustali limity Custom.

Pełne plany, ceny i korzyści