Naar de inhoud

Meer

Taal en valuta

Qualit.ly API

Productdata, QC-afbeeldingen en metadata van Weidian, Taobao en 1688. Bearer-tokenauth, royale rate limits, gelaagde abonnementen.

API-sleutel ophalenSnelstart

Aan de slag

Alle verzoeken gaan naar https://backend.qualit.ly/api/v1. Drie stappen:

  1. 1

    Haal een sleutel

    Log in en maak een API-sleutel aan vanuit het developer-dashboard.

  2. 2

    Doe een verzoek

    Stuur je sleutel als Bearer-token in de Authorization-header.

  3. 3

    Krijg data

    Ontvang JSON-antwoorden met productdata en QC-afbeeldingen.

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

Authenticatie

Neem een geldige API-sleutel op in de Authorization-header met het Bearer-schema.

http
Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Sleutelformaat

Sleutels hebben de vorm qc_{mode}_{random}, waarbij mode live of test is, en random 32 cryptografisch willekeurige tekens is.

Sleutels worden bij het aanmaken één keer getoond. We bewaren alleen de SHA-256-hash, dus verloren sleutels kunnen niet worden hersteld — trek ze in en maak een nieuwe aan.

IP-allowlisting

Beperk sleutels optioneel tot specifieke IP's of CIDR-bereiken via het developer-dashboard. Verzoeken van niet-vermelde IP's krijgen een 403. Een lege allowlist staat alle IP's toe.

Rate limits

Twee buckets: per minuut en per maand. Je niveau wordt bij elk verzoek uit je account gelezen — upgrades gaan meteen in — en de limieten gelden voor al je sleutels.

Niveau/ minuut/ maand
Basic301,000
Early Adopter403,000
Pro30025,000
Pro+1,000500,000
CustomOnbeperktOnbeperkt

/me en /usage vereisen authenticatie maar tellen niet mee: vragen waar je staat, verbruikt niet het quotum waar je naar vraagt.

Headers

Wordt bij elk antwoord meegestuurd, niet alleen bij afwijzingen.

X-RateLimit-LimitToegestane verzoeken per minuut op je niveau, of "unlimited".
X-RateLimit-RemainingResterende verzoeken in de huidige minuut.
X-RateLimit-ResetAantal seconden tot de teller die je blokkeerde, reset.

Bij rate limiting

De API geeft 429 terug — RATE_LIMITED voor de piek per minuut, QUOTA_EXCEEDED voor het maandquotum — met het aantal te wachten seconden in retry_after.

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

Fouten

Fouten geven een non-2xx-status en een top-level error-object terug met een stabiele code en een message. Match op de code, niet op het bericht — berichten kunnen veranderen.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
400BAD_REQUESTOngeldige verzoekbody of -parameters.
401INVALID_KEYOntbrekende, onjuist opgemaakte of onbekende API-sleutel.
401REVOKED_KEYDe sleutel is ingetrokken in het dashboard.
403IP_NOT_AUTHORIZEDVerzoek-IP staat niet op de allowlist van de sleutel.
403FORBIDDENJe niveau heeft geen toegang tot dit endpoint.
404NOT_FOUNDDe gevraagde resource bestaat niet.
429RATE_LIMITEDLimiet per minuut overschreden.
429QUOTA_EXCEEDEDMaandquotum uitgeput; wordt gereset bij de UTC-maandwisseling.
500INTERNALOnze fout. Veilig om opnieuw te proberen met backoff.

Endpoints

Onderstaande paden zijn relatief ten opzichte van https://backend.qualit.ly/api/v1. Storefronts zijn weidian, taobao en 1688. Endpoints zonder chip werken op elk abonnement.

Product ophalen

GET/products/{storefront}/{listing_id}

Eén listing op storefront en ID. Geeft de metadata en tot 5 QC-previewthumbnails terug. Dit is het endpoint waarmee de meeste integraties beginnen.

storefrontvereiststringEen van: weidian, taobao, 1688.
listing_idvereiststringDe product-listing-ID van de storefront.

Voorbeeld

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

Antwoord

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

Producten zoeken

GET/products/search

Doorzoek de catalogus op productnaam — de product-URL wordt ook gematcht. Er is geen paginering: elk abonnement geeft tot een vast aantal resultaten terug.

qvereiststringZoektekst. Meerdere woorden worden met AND gematcht tegen de naam en de product-URL.
storefrontstringBeperk tot weidian, taobao of 1688.
has_qcbooleanAlleen listings die QC-foto's hebben.
limitintegerVraag om minder dan het maximum van je abonnement. Waarden erboven worden omlaag bijgesteld — nooit omhoog.

Geen paginering. Elk abonnement geeft tot een vast aantal resultaten per zoekopdracht terug; limit kan om minder vragen, nooit om meer.

AbonnementMax. resultaten
Basic5
Early Adopter10
Pro50
Pro+100
Custom250

Voorbeeld

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"

Antwoord

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

Velden

max_resultsHet maximum van je abonnement — het plafond waartoe `limit` wordt begrensd.
countHoeveel rijen dit antwoord daadwerkelijk bevat.

Batch-producten

Pro+
POST/products/batch

Los tot 100 listings op in één aanroep. Elk item wordt onafhankelijk opgelost, dus een ontbrekend product laat de batch niet mislukken — het komt terug als een foutmelding op dezelfde positie.

itemsvereistarrayArray van { storefront, listing_id }-objecten. Begrensd op 100, of de paginalimiet van je abonnement als die lager is.

Verzoekbody

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

Voorbeeld

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

Antwoord

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

Willekeurig product

POST/products/random

Eén willekeurige listing met QC-foto's — voor showcases, feeds of het steekproefsgewijs doorbladeren van de catalogus. Geen body nodig.

Voorbeeld

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

Antwoord

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

GET/qc/{storefront}/{listing_id}

Het aantal QC-foto's voor een listing, plus de eerste drie thumbnails — zonder de volledige afbeeldingslijst op te halen.

storefrontvereiststringEen van: weidian, taobao, 1688.
listing_idvereiststringDe product-listing-ID van de storefront.

Voorbeeld

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

Antwoord

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

Pro+
GET/qc/{id}/images

Elke geïndexeerde QC-foto voor een listing. Accepteert het numerieke product-ID, of geef ?url= mee met een ondersteunde productlink en laat de API die herleiden.

idvereistintegerNumeriek product-ID. Geef 0 op bij opzoeken via ?url=.
urlstringVolledige product-URL om te herleiden in plaats van een ID. Heeft voorrang wanneer aanwezig.

Op product-ID

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

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

Antwoord

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

De ?url=-parameter accepteert productlinks van Weidian, Taobao en 1688, en van elke agent die de linkconverter ondersteunt. Afbeeldingen zijn altijd CDN-URL's.

Accountinfo

GET/me

Je account, de sleutel waarmee het verzoek is gedaan en het niveau waartoe die herleidt. Handig als health check.

Voorbeeld

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

Antwoord

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

Gebruik

GET/usage

Waar je staat in beide rate-limit-buckets, met reset-tijdstempels. Net als /me authenticeert dit endpoint wel, maar telt het niet mee — vragen naar je quotum verbruikt het niet.

Voorbeeld

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

Antwoord

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

Velden

tierEen van: basic, early_adopter, pro, pro_plus, custom.
limit / remainingnull op de Custom-tier, die onbeperkt is.
usedVerzoeken geteld in het huidige venster. De minutenteller reset elke 60s; de maandteller reset bij de UTC-maandwisseling.
reset_atISO 8601, UTC.
bucketInterne YYYYMM-sleutel voor de maandteller.

Codevoorbeelden

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

MCP-server

Dezelfde API wordt ook gehost als een Model Context Protocol-server, zodat Claude, Cursor, VS Code of elke MCP-client listings en QC-sets kan opvragen zonder zelf HTTP te schrijven. Je API-sleutel, rate limits en niveauregels blijven ongewijzigd gelden.

Server-URL

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

Transport

StreamableHTTP (POST)

Auth

Authorization: Bearer qc_live_…

Tools

Alleen de tools die je niveau mag aanroepen worden geregistreerd, zodat een Basic-sleutel er nooit een ziet die geweigerd zou worden.

get_productZoek een product op storefront en listing-ID.
search_productsZoek op naam, met storefront- en has-QC-filters.
get_products_batchZoek tot 100 producten op in één aanroep.Pro+
random_productHaal een willekeurig product met QC-foto's op.
get_qcQC-aantal en de eerste 3 thumbnails.
get_qc_imagesVolledige CDN-afbeeldingslijst, op ID of URL.Pro+
get_meHuidige sleutel, gebruiker en niveau.
get_usageQuotumstatus per minuut en per maand.

Claude Desktop, Cursor en VS Code

Voeg de server toe aan je claude_desktop_config.json (Claude → Instellingen → Ontwikkelaar), of aan de MCP-instellingen van je editor.

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 die OAuth-discovery ondersteunen — waaronder Claude.ai en ChatGPT — kunnen de hardgecodeerde sleutel helemaal overslaan: een ongeauthenticeerd verzoek krijgt een WWW-Authenticate-header terug die naar de OAuth-metadata van de server wijst, en de client leidt je gebruikers in plaats daarvan langs een inlogpagina.

Controleer of het werkt

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

Abonnementen & niveaus

Je niveau wordt bij elk verzoek bepaald op basis van je account, dus een upgrade geldt meteen voor de volgende aanroep — geen nieuwe sleutel nodig. Batchopzoekingen, volledige QC-afbeeldingslijsten en ?url=-extractie zijn de enige endpoints die boven Basic zijn afgeschermd; al het andere verschilt alleen in volume.

Abonnement/ minuut/ maandZoekresultatenBatch + afbeeldingen
Basic301,0005
Early Adopterlegacy403,00010
Pro30025,00050
Pro+1,000500,000100
CustomOnbeperktOnbeperkt250

Early Adopter is legacy — bestaande accounts behouden het, het wordt niet meer verkocht. Meer nodig dan Pro+? [email protected] stelt Custom-limieten voor je in.

Volledige abonnementen, prijzen & extra's
Zoeken

Cookies

We gebruiken ze om je ingelogd te houden en opgeslagen producten te onthouden. Analytics alleen als je akkoord gaat.