Qualit.ly
Qualit.ly
InícioBot do DiscordPesquisar

Referência da API

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 Chave de API

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.

Exemplo rápido

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

Autenticação

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

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Formato da chave

As chaves seguem 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.

Lista de permissões de IP

Opcionalmente, restringe as chaves a IPs ou intervalos CIDR específicos através 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. Os limites estão associados ao nível da tua conta e aplicam-se a todas as chaves.

Nível
/ minuto
/ mês
Basic
30
1,000
Early Adopter
40
3,000
Pro
300
25,000
Pro+
1,000
500,000

Quando o limite é atingido

A API devolve 429 com o cabeçalho Retry-After.

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

Erros

Todos os erros devolvem um objeto error de nível superior com code e message.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
400BAD_REQUESTCorpo do pedido ou parâmetros inválidos.
401INVALID_KEYChave de API em falta, malformada ou desconhecida.
401REVOKED_KEYA chave de API 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, verifica Retry-After.
429QUOTA_EXCEEDEDQuota mensal esgotada; repõe-se na viragem do mês em UTC.
500INTERNALErro do servidor. Tenta novamente ou contacta o suporte.

Endpoints

Base: https://backend.qualit.ly/api/v1. Lojas: weidian, taobao, 1688.

GET/products/:storefront/:listingIdBasic

Consulta um único produto por loja e ID de listagem. Devolve metadados e até 5 miniaturas de pré-visualização QC.

Parâmetros

storefrontobrigatório

Um de: weidian, taobao, 1688

listingIdobrigatório

O ID de listagem do produto na 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/...",
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qc_count": 12,
    "qc_preview": [
      "https://cdn.qualit.ly/qc/...",
      "https://cdn.qualit.ly/qc/..."
    ]
  }
}
GET/products/searchBasic

Pesquisa o catálogo por nome de produto (também corresponde ao URL do produto). Opcionalmente, filtra por loja ou por produtos que tenham fotos QC. Sem paginação — a contagem de resultados é limitada pelo teu plano.

Parâmetros de consulta

qobrigatório

Texto de pesquisa. Várias palavras são combinadas com AND contra o nome e o URL do produto. (obrigatório)

storefront

Opcional. Limita os resultados a um de: weidian, taobao, 1688

has_qc

Opcional. Define como true para devolver apenas produtos que tenham fotos QC

limit

Opcional. Menos resultados do que o limite do teu plano. Valores acima do limite são reduzidos — nunca aumentados.

Limites de resultados

Sem paginação. Cada plano devolve até um número fixo de resultados por pesquisa. Passa um limite menor para obter menos; não podes exceder o limite do teu plano.

Plano
Máx. de resultados
Basic
5
Early Adopter
10
Pro
50
Pro+
100
Custom
250

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/...",
      "product_url": "https://weidian.com/item.html?itemID=7231368393",
      "qc_count": 12,
      "qc_preview": ["https://cdn.qualit.ly/qc/..."]
    }
  ]
}
POST/products/batchPro+

Consulta vários produtos num único pedido (até 100). Cada resultado é independente, por isso um produto em falta não faz o lote falhar.

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",
        "qc_count": 12,
        "qc_preview": ["..."]
      }
    },
    { "error": { "code": "NOT_FOUND" } }
  ]
}
GET/qc/:storefront/:listingIdBasic

Obtém os metadados QC e os primeiros 3 URLs de miniatura de um produto.

Exemplo

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/weidian/7231368393
json
{
  "data": {
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qc_count": 12,
    "thumbnails": ["..."]
  }
}
GET/qc/:id/imagesPro+

Lista completa de imagens QC. Aceita um ID numérico de produto ou um parâmetro de consulta ?url= para consultas por URL.

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",
    "qc_count": 12,
    "images": [
      "https://cdn.qualit.ly/qc/img1.jpg",
      "https://cdn.qualit.ly/qc/img2.jpg",
      "..."
    ]
  }
}
Apenas Pro+. O parâmetro ?url= aceita URLs completos de produtos da Weidian, Taobao, 1688 e agentes suportados.
GET/meBasic

Devolve as informações da tua conta, a chave usada no pedido e o teu nível atual.

Exemplo

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/me
json
{
  "user": { "id": 12345, "username": "you" },
  "key": { "id": 1, "mode": "live" },
  "tier": "basic"
}
GET/usageBasic

Verifica a tua utilização atual de limite de taxa e quota. Devolve contadores por minuto e por mês com marcas temporais de reposição. A própria chamada consome 1 pedido de ambos os contadores.

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-04-17T18:42:00.000Z"
  },
  "month": {
    "limit": 500000,
    "used": 1843,
    "remaining": 498157,
    "reset_in_seconds": 1159200,
    "reset_at": "2026-05-01T00:00:00.000Z",
    "bucket": 202604
  }
}

Campos

tier

Um de: basic, early_adopter, pro, pro_plus, custom

limit / remaining

null no nível custom (ilimitado)

used

Pedidos contados na janela atual. O contador de minuto repõe-se a cada 60s; o contador de mês repõe-se na viragem do mês em UTC.

reset_at

Marca temporal ISO 8601 UTC

bucket

Chave interna YYYYMM para o contador do mês

Erros

Iguais às de outras rotas /api/v1/*:401 INVALID_KEY /REVOKED_KEY,403 IP_NOT_AUTHORIZED,429 RATE_LIMITED /QUOTA_EXCEEDED.

Exemplos de Código

Excertos de início rápido em linguagens populares.

const res = await fetch(
  'https://backend.qualit.ly/api/v1/products/weidian/7231368393',
  { headers: { Authorization: 'Bearer ' + process.env.QUALITLY_KEY } }
);
const { data } = await res.json();
console.log(data.name, data.qc_count, 'QC images');

Servidor MCP

A API da Qualit.ly está disponível como um servidor Model Context Protocol (MCP). Liga-o ao Claude Desktop, Cursor, VS Code ou a qualquer cliente compatível com MCP e consulta produtos, imagens QC e dados de utilização diretamente do teu assistente de IA, sem HTTP manual. Aplicam-se a mesma chave de API, os mesmos limites de taxa e as mesmas regras de nível.

URL do servidor

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

Transporte

StreamableHTTP (POST)

Autenticação

Authorization: Bearer qc_live_…

Ferramentas disponíveis

Ferramenta
Descrição
Nível
get_product
Consulta um produto por loja e ID de listagem
Basic
search_products
Pesquisa produtos por nome, com filtros de loja / com QC
Basic
get_products_batch
Consulta até 100 produtos numa só chamada
Pro+
get_qc
Contagem de QC e 3 URLs de miniatura
Basic
get_qc_images
Lista completa de imagens do CDN (por ID ou URL)
Pro+
get_me
Chave, utilizador e nível atuais
Basic
get_usage
Estado da quota por minuto e mensal
Basic
OAuth 2.0 suportado. Os clientes que suportam a descoberta automática de OAuth (Claude.ai, ChatGPT, etc.) irão pedir automaticamente aos teus utilizadores que autorizem através de uma página de início de sessão, sem necessidade de chave fixa no código. O servidor anuncia os seus endpoints OAuth em https://backend.qualit.ly/.well-known/oauth-authorization-server.

Claude Desktop (chave fixa no código)

Adiciona isto ao teu claude_desktop_config.json (Claude → Definições → Programador):

json
{
  "mcpServers": {
    "qualitly": {
      "url": "https://backend.qualit.ly/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor / VS Code (chave fixa no código)

json
{
  "mcp": {
    "servers": {
      "qualitly": {
        "url": "https://backend.qualit.ly/api/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Verificação rápida

bash
# List available tools
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 em cada pedido, por isso as melhorias têm efeito imediato. Os endpoints de lote e de imagens completas requerem Pro+.

Plano
/ minuto
/ mês
Lote + Imagens
Basic
30
1,000
—
Early Adopter
40
3,000
—
Pro
300
25,000
—
Pro+
1,000
500,000
Incluído

Precisas de limites mais altos? [email protected]

Vê os planos completos, preços e vantagens
Qualit.ly

Free QC photos and the Discord link converter for Taobao, Weidian and 1688.

Tools

  • Search QC photos
  • QC photo finder
  • Discord link converter
  • Order tracking
  • Public REST API

Marketplaces

  • Weidian QC photos
  • Taobao QC photos
  • 1688 QC photos

Resources

  • Plans & pricing
  • About Qualit.ly
  • Contact
  • Terms of Service
  • Privacy Policy
  • Discord community
  • r/qualitly
  • Telegram channel

© Qualit.ly. Free for the rep finds community.

Questions? [email protected]