Qualit.ly API

Produktdaten, QC-Bilder und Metadaten von Weidian, Taobao und 1688. Bearer-Token-Authentifizierung, großzügige Ratenlimits, gestufte Pläne.

API-Schlüssel erhalten Schnellstart

Erste Schritte

Alle Anfragen gehen an https://backend.qualit.ly/api/v1. Drei Schritte:

1
Schlüssel holen
Melde dich an und erstelle einen API-Schlüssel im Entwickler-Dashboard.
2
Anfrage senden
Sende deinen Schlüssel als Bearer-Token im Authorization-Header.
3
Daten erhalten
Erhalte JSON-Antworten mit Produktdaten und QC-Bildern.

bash

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

Authentifizierung

Füge einen gültigen API-Schlüssel im Authorization-Header mit dem Bearer-Schema ein.

http

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Schlüsselformat

Schlüssel folgen dem Format qc_{mode}_{random}, wobei mode entweder live oder test ist und random aus 32 kryptografisch zufälligen Zeichen besteht.

Schlüssel werden nur einmal bei der Erstellung angezeigt. Wir speichern nur den SHA-256-Hash, verlorene Schlüssel können daher nicht wiederhergestellt werden — widerrufen und einen neuen erstellen.

IP-Allowlist

Beschränke Schlüssel optional über das Entwickler-Dashboard auf bestimmte IPs oder CIDR-Bereiche. Anfragen von nicht gelisteten IPs erhalten einen 403. Eine leere Allowlist erlaubt alle IPs.

Ratenlimits

Zwei Kontingente: pro Minute und pro Monat. Deine Stufe wird bei jeder Anfrage aus deinem Konto gelesen — Upgrades wirken sofort — und die Limits gelten für alle deine Schlüssel.

Stufe/ Minute/ Monat

Basic301,000

Early Adopter403,000

Pro30025,000

Pro+1,000500,000

IndividuellUnbegrenztUnbegrenzt

/me und /usage authentifizieren, zählen aber nicht zum Kontingent: Nachzufragen, wo du stehst, verbraucht nicht das Kontingent, nach dem du fragst.

Header

Wird bei jeder Antwort gesendet, nicht nur bei Ablehnungen.

HeaderBedeutung

X-RateLimit-LimitErlaubte Anfragen pro Minute auf deiner Stufe, oder „unlimited“.

X-RateLimit-RemainingVerbleibende Anfragen in der aktuellen Minute.

X-RateLimit-ResetSekunden, bis der Zähler, der dich blockiert hat, zurückgesetzt wird.

Bei Ratenbegrenzung

Die API gibt 429 zurück — RATE_LIMITED für den Minuten-Burst, QUOTA_EXCEEDED für das Monatskontingent — mit der Wartezeit in Sekunden in retry_after.

json

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

Fehler

Fehler liefern einen Nicht-2xx-Status und ein Top-Level-Objekt error mit einem stabilen code und einer message. Prüfe auf den Code, nicht auf die Nachricht — Nachrichten können sich ändern.

json

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

StatusCodeBedeutung

400BAD_REQUESTUngültiger Anfragetext oder ungültige Parameter.

401INVALID_KEYFehlender, fehlerhafter oder unbekannter API-Schlüssel.

401REVOKED_KEYDer Schlüssel wurde im Dashboard widerrufen.

403IP_NOT_AUTHORIZEDDie Anfrage-IP ist nicht in der Allowlist des Schlüssels.

403FORBIDDENDeine Stufe hat keinen Zugriff auf diesen Endpunkt.

404NOT_FOUNDDie angeforderte Ressource existiert nicht.

429RATE_LIMITEDMinutenlimit überschritten.

429QUOTA_EXCEEDEDMonatskontingent erschöpft; wird beim UTC-Monatswechsel zurückgesetzt.

500INTERNALUnser Fehler. Mit Backoff sicher wiederholbar.

Endpunkte

Die folgenden Pfade sind relativ zu https://backend.qualit.ly/api/v1. Shops sind weidian, taobao und 1688. Endpunkte ohne Chip funktionieren mit jedem Plan.

Produkt abrufen

GET/products/{storefront}/{listing_id}

Ein einzelner Eintrag nach Shop und ID. Gibt seine Metadaten und bis zu 5 QC-Vorschau-Thumbnails zurück. Dies ist der Endpunkt, mit dem die meisten Integrationen beginnen.

ParameterTypBeschreibung

storefronterforderlichstringEines von: weidian, taobao, 1688.

listing_iderforderlichstringDie eigene Artikel-ID des Shops.

Beispiel

bash

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

Antwort

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

Produkte suchen

GET/products/search

Durchsuche den Katalog nach Produktnamen — die Produkt-URL wird ebenfalls abgeglichen. Es gibt keine Paginierung: Jeder Plan liefert bis zu einer festen Anzahl Ergebnisse.

ParameterTypBeschreibung

qerforderlichstringSuchtext. Mehrere Wörter werden per UND gegen den Namen und die Produkt-URL abgeglichen.

storefrontstringAuf einen dieser Storefronts beschränken: weidian, taobao, 1688.

has_qcbooleanNur Einträge mit QC-Fotos.

limitintegerFordere weniger an, als das Limit deines Plans erlaubt. Werte darüber werden nach unten begrenzt, nie nach oben.

Keine Paginierung. Jeder Plan liefert pro Suche bis zu einer festen Anzahl Ergebnisse; limit kann weniger anfordern, nie mehr.

PlanMax. Ergebnisse

Basic5

Early Adopter10

Pro50

Pro+100

Individuell250

Beispiel

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"

Antwort

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

Felder

FeldHinweise

max_resultsDas Limit deines Plans — die Obergrenze, auf die `limit` begrenzt wird.

countWie viele Zeilen diese Antwort tatsächlich enthält.

Produkt-Batch

Pro+

POST/products/batch

Löst bis zu 100 Einträge in einem Aufruf auf. Jedes Element wird unabhängig aufgelöst, ein fehlendes Produkt lässt den Batch also nicht scheitern — es kommt als Fehlereintrag an derselben Position zurück.

ParameterTypBeschreibung

itemserforderlicharrayArray von { storefront, listing_id }-Objekten. Begrenzt auf 100 oder das Limit pro Seite deines Plans, falls das niedriger ist.

Anfragetext

json

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

Beispiel

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

Antwort

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

Zufälliges Produkt

POST/products/random

Ein zufälliger Eintrag mit QC-Fotos — für Showcases, Feeds oder Katalog-Stichproben. Kein Body nötig.

Beispiel

bash

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

Antwort

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

QC-Metadaten

GET/qc/{storefront}/{listing_id}

Die Anzahl der QC-Fotos für einen Eintrag, plus die ersten drei Thumbnails — ohne die vollständige Bildliste abzurufen.

ParameterTypBeschreibung

storefronterforderlichstringEines von: weidian, taobao, 1688.

listing_iderforderlichstringDie eigene Artikel-ID des Shops.

Beispiel

bash

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

Antwort

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

QC-Bilder

Pro+

GET/qc/{id}/images

Jedes indexierte QC-Foto für einen Eintrag. Nimmt die numerische Produkt-ID entgegen, oder übergib ?url= mit einem beliebigen unterstützten Produktlink und lass die API ihn auflösen.

ParameterTypBeschreibung

iderforderlichintegerNumerische Produkt-ID. Übergib 0, wenn du über ?url= suchst.

urlstringVollständige Produkt-URL, die anstelle einer ID aufgelöst wird. Hat Vorrang, wenn angegeben.

Nach Produkt-ID

bash

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

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

Antwort

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

Der Parameter ?url= akzeptiert Produktlinks von Weidian, Taobao und 1688 sowie von jedem vom Link-Konverter unterstützten Agenten. Bilder sind immer CDN-URLs.

Kontoinfo

GET/me

Dein Konto, der Schlüssel, der die Anfrage gestellt hat, und die Stufe, die sich daraus ergibt. Nützlich als Health-Check.

Beispiel

bash

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

Antwort

json

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

Nutzung

GET/usage

Wo du in beiden Ratenlimit-Kontingenten stehst, mit Reset-Zeitstempeln. Wie /me authentifiziert dieser Endpunkt, zählt aber nicht zum Kontingent — die Frage nach deinem Kontingent verbraucht es nicht.

Beispiel

bash

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

Antwort

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

Felder

FeldHinweise

tierEines von: basic, early_adopter, pro, pro_plus, custom.

limit / remainingnull auf der Custom-Stufe, die unbegrenzt ist.

usedIm aktuellen Zeitfenster gezählte Anfragen. Der Minutenzähler wird alle 60 s zurückgesetzt, der Monatszähler beim UTC-Monatswechsel.

reset_atISO 8601, UTC.

bucketInterner JJJJMM-Schlüssel für den Monatszähler.

Code-Beispiele

bash

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

MCP-Server

Dieselbe API wird auch als gehosteter Model Context Protocol-Server bereitgestellt, sodass Claude, Cursor, VS Code oder jeder MCP-Client Einträge und QC-Sets abfragen kann, ohne HTTP-Code zu schreiben. Dein API-Schlüssel, deine Ratenlimits und Stufenregeln gelten unverändert weiter.

Server-URL

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

Transport

StreamableHTTP (POST)

Auth

Authorization: Bearer qc_live_…

Tools

Es werden nur die Tools registriert, die deine Stufe aufrufen darf — ein Basic-Schlüssel sieht also nie eines, das ihm verweigert würde.

ToolBeschreibungPlan

get_productEin Produkt nach Shop und Listing-ID abrufen.

search_productsProdukte nach Namen suchen, mit Storefront- und Hat-QC-Filtern.

get_products_batchBis zu 100 Produkte in einem Aufruf abrufen.Pro+

random_productEin zufälliges Produkt mit QC-Fotos.

get_qcQC-Anzahl und die ersten 3 Thumbnails.

get_qc_imagesVollständige CDN-Bildliste, nach ID oder URL.Pro+

get_meAktueller Schlüssel, Nutzer und Stufe.

get_usageStatus von Minuten- und Monatskontingent.

Claude Desktop, Cursor und VS Code

Füge den Server zu deiner claude_desktop_config.json hinzu (Claude → Einstellungen → Entwickler), oder zu den MCP-Einstellungen deines Editors.

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

Clients mit Unterstützung für OAuth-Discovery — darunter Claude.ai und ChatGPT — können den fest codierten Schlüssel komplett überspringen: Eine nicht authentifizierte Anfrage antwortet mit einem WWW-Authenticate-Header, der auf die OAuth-Metadaten des Servers verweist, und der Client führt deine Nutzer stattdessen durch eine Anmeldeseite.

Schnelle Überprüfung

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

Pläne & Stufen

Deine Stufe wird bei jeder Anfrage aus deinem Konto ermittelt, ein Upgrade gilt also schon beim nächsten Aufruf — kein neuer Schlüssel nötig. Batch-Abfragen, vollständige QC-Bildlisten und die ?url=-Extraktion sind die einzigen Endpunkte, die mehr als Basic voraussetzen; alles andere unterscheidet sich nur im Umfang.

Plan	/ Minute	/ Monat	Suchergebnisse
Basic	30	1,000	5
Early AdopterLegacy	40	3,000	10
Pro	300	25,000	50
Pro+	1,000	500,000	100
Individuell	Unbegrenzt	Unbegrenzt	250

Early Adopter ist Legacy — nur bestehende Konten haben ihn, er wird nicht mehr verkauft. Brauchst du mehr als Pro+? [email protected] richtet individuelle Custom-Limits ein.

Alle Pläne, Preise & Vorteile