Qualit.ly API

Dados de produtos, imagens QC e metadados da Weidian, Taobao e 1688. Autenticação por token Bearer, limites de taxa generosos, planos por níveis.

Obter uma chave de API Início rápido

Começar

Todos os pedidos vão para https://backend.qualit.ly/api/v1. Três passos:

1
Obtém uma chave
Inicia sessão e cria uma chave de API a partir do painel de programador.
2
Faz um pedido
Envia a tua chave como um token Bearer no cabeçalho Authorization.
3
Obtém dados
Recebe respostas JSON com dados de produtos e imagens QC.

bash

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

Autenticação

Inclui uma chave de API válida no cabeçalho Authorization usando o esquema Bearer.

http

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Formato da chave

As chaves seguem o formato qc_{mode}_{random}, onde mode é live ou test, e random são 32 caracteres criptograficamente aleatórios.

As chaves são mostradas uma vez, na criação. Guardamos apenas o hash SHA-256, por isso chaves perdidas não podem ser recuperadas — revoga e cria uma nova.

Lista de permissões de IP

Opcionalmente, restringe as chaves a IPs ou intervalos CIDR específicos a partir do painel de programador. Pedidos de IPs não listados recebem um 403. Uma lista de permissões vazia permite todos os IPs.

Limites de Taxa

Dois limites: por minuto e por mês. O teu nível é lido da tua conta em cada pedido — as melhorias de plano têm efeito imediato — e os limites aplicam-se a todas as tuas chaves.

Nível/ minuto/ mês

Basic301,000

Early Adopter403,000

Pro30025,000

Pro+1,000500,000

CustomIlimitadoIlimitado

/me e /usage autenticam mas não são contabilizados: perguntar onde estás não gasta a quota que estás a consultar.

Cabeçalhos

Enviados em todas as respostas, não só nas rejeições.

CabeçalhoSignificado

X-RateLimit-LimitPedidos permitidos por minuto no teu nível, ou "ilimitado".

X-RateLimit-RemainingPedidos restantes no minuto atual.

X-RateLimit-ResetSegundos até o contador que te bloqueou ser reposto.

Quando o limite é atingido

A API devolve 429 — RATE_LIMITED para o pico por minuto, QUOTA_EXCEEDED para a quota mensal — com os segundos de espera em retry_after.

json

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

Erros

Os erros devolvem um estado não-2xx e um objeto error de nível superior com um code estável e uma message. Faz a correspondência pelo code, não pela message — as mensagens podem mudar.

json

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

EstadoCódigoSignificado

400BAD_REQUESTCorpo do pedido ou parâmetros inválidos.

401INVALID_KEYChave de API em falta, malformada ou desconhecida.

401REVOKED_KEYA chave foi revogada no painel.

403IP_NOT_AUTHORIZEDO IP do pedido não está na lista de permissões da chave.

403FORBIDDENO teu nível não tem acesso a este endpoint.

404NOT_FOUNDO recurso pedido não existe.

429RATE_LIMITEDLimite por minuto excedido.

429QUOTA_EXCEEDEDQuota mensal esgotada; repõe-se na viragem do mês em UTC.

500INTERNALErro nosso. Podes tentar novamente com backoff.

Endpoints

Os caminhos abaixo são relativos a https://backend.qualit.ly/api/v1. As lojas são weidian, taobao e 1688. Os endpoints sem etiqueta funcionam em todos os planos.

Obter Produto

GET/products/{storefront}/{listing_id}

Uma única listagem, por loja e ID. Devolve os seus metadados e até 5 miniaturas de pré-visualização QC. É o endpoint por onde a maioria das integrações começa.

ParâmetroTipoDescrição

storefrontobrigatóriostringUm de: weidian, taobao, 1688.

listing_idobrigatóriostringO ID de listagem da própria loja.

Exemplo

bash

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

Resposta

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

Pesquisar Produtos

GET/products/search

Pesquisa o catálogo por nome de produto — o URL do produto também é correspondido. Não há paginação: cada plano devolve até um número fixo de resultados.

ParâmetroTipoDescrição

qobrigatóriostringTexto de pesquisa. Várias palavras são combinadas com AND contra o nome e o URL do produto.

storefrontstringRestringe a weidian, taobao ou 1688.

has_qcbooleanApenas listagens que tenham fotos QC.

limitintegerPede menos do que o limite do teu plano. Valores acima dele são reduzidos, nunca aumentados.

Sem paginação. Cada plano devolve até um número fixo de resultados por pesquisa; limit pode pedir menos, nunca mais.

PlanoMáx. de resultados

Basic5

Early Adopter10

Pro50

Pro+100

Custom250

Exemplo

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"

Resposta

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

Campos

CampoNotas

max_resultsO limite do teu plano — o teto ao qual `limit` é reduzido.

countQuantas linhas esta resposta traz de facto.

Produtos em Lote

Pro+

POST/products/batch

Resolve até 100 listagens numa só chamada. Cada item é resolvido de forma independente, por isso um produto em falta não faz o lote falhar — volta como uma entrada de erro na mesma posição.

ParâmetroTipoDescrição

itemsobrigatórioarrayArray de objetos { storefront, listing_id }. Limitado a 100, ou ao limite por página do teu plano, se for mais baixo.

Corpo do pedido

json

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

Exemplo

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

Resposta

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

Produto Aleatório

POST/products/random

Uma listagem aleatória que tenha fotos QC — para vitrines, feeds ou amostragem do catálogo. Sem corpo necessário.

Exemplo

bash

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

Resposta

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

Metadados QC

GET/qc/{storefront}/{listing_id}

O número de fotos QC de uma listagem, mais as primeiras três miniaturas — sem obter a lista completa de imagens.

ParâmetroTipoDescrição

storefrontobrigatóriostringUm de: weidian, taobao, 1688.

listing_idobrigatóriostringO ID de listagem da própria loja.

Exemplo

bash

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

Resposta

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

Imagens QC

Pro+

GET/qc/{id}/images

Todas as fotos QC indexadas de uma listagem. Aceita o ID numérico do produto, ou passa ?url= com qualquer link de produto suportado e deixa a API resolvê-lo.

ParâmetroTipoDescrição

idobrigatóriointegerID numérico do produto. Passa 0 quando estiveres a consultar por ?url=.

urlstringURL completo do produto a resolver em vez de um ID. Tem prioridade quando presente.

Por ID do produto

bash

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

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

Resposta

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

O parâmetro ?url= aceita links de produtos da Weidian, Taobao e 1688, e de todos os agentes suportados pelo conversor de links. As imagens são sempre URLs de CDN.

Info da Conta

GET/me

A tua conta, a chave que fez o pedido e o nível a que corresponde. Útil como verificação de estado.

Exemplo

bash

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

Resposta

json

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

Utilização

GET/usage

Onde estás em ambos os limites de taxa, com marcas temporais de reposição. Tal como /me, este endpoint autentica mas não é contabilizado — perguntar pela tua quota não a gasta.

Exemplo

bash

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

Resposta

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

Campos

CampoNotas

tierUm de: basic, early_adopter, pro, pro_plus, custom.

limit / remainingnull no nível Custom, que é ilimitado.

usedPedidos na janela atual. O contador do minuto repõe-se a cada 60s, o contador do mês na viragem do mês em UTC.

reset_atISO 8601, UTC.

bucketChave interna YYYYMM para o contador do mês.

Exemplos de Código

bash

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

Servidor MCP

A mesma API é disponibilizada como um servidor Model Context Protocol alojado, para que o Claude, o Cursor, o VS Code ou qualquer cliente MCP possam consultar listagens e conjuntos de QC sem escrever HTTP. A tua chave de API, os limites de taxa e as regras de nível mantêm-se sem alterações.

URL do servidor

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

Transporte

StreamableHTTP (POST)

Autenticação

Authorization: Bearer qc_live_…

Ferramentas

Só são registadas as ferramentas que o teu nível pode chamar, por isso uma chave Basic nunca vê uma que lhe seria recusada.

FerramentaDescriçãoPlano

get_productConsulta um produto por loja e ID de listagem.

search_productsPesquisa por nome, com filtros de loja e de QC.

get_products_batchConsulta até 100 produtos numa só chamada.Pro+

random_productUm produto aleatório que tenha fotos QC.

get_qcContagem de QC e as primeiras 3 miniaturas.

get_qc_imagesLista completa de imagens do CDN, por ID ou URL.Pro+

get_meChave, utilizador e nível atuais.

get_usageEstado da quota por minuto e mensal.

Claude Desktop, Cursor e VS Code

Adiciona o servidor ao claude_desktop_config.json (Claude → Definições → Programador), ou às definições MCP do teu 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"
        }
      }
    }
  }
}

Os clientes que suportam a descoberta automática de OAuth — entre eles o Claude.ai e o ChatGPT — podem dispensar totalmente a chave fixa no código: um pedido não autenticado responde com um cabeçalho WWW-Authenticate que aponta para os metadados OAuth do servidor, e o cliente guia os teus utilizadores por uma página de início de sessão.

Confirma que funciona

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

Planos e Níveis

O teu nível é resolvido a partir da tua conta em cada pedido, por isso uma melhoria de plano já se aplica na chamada seguinte — sem precisares de uma chave nova. As consultas em lote, as listas completas de imagens QC e a extração por ?url= são os únicos endpoints reservados acima do Basic; tudo o resto varia apenas em volume.

Plano	/ minuto	/ mês	Resultados de pesquisa
Basic	30	1,000	5
Early Adopterlegado	40	3,000	10
Pro	300	25,000	50
Pro+	1,000	500,000	100
Custom	Ilimitado	Ilimitado	250

Early Adopter é legado — mantido por contas existentes, nunca vendido. Precisas de mais do que o Pro+? [email protected] configura limites Custom.

Planos completos, preços e vantagens