Qualit.ly API

Datos de productos, imágenes QC y metadatos de Weidian, Taobao y 1688. Autenticación con token Bearer, límites de tasa generosos, planes por niveles.

Obtener clave de API Inicio rápido

Primeros pasos

Todas las solicitudes van a https://backend.qualit.ly/api/v1. Tres pasos:

1
Obtén una clave
Inicia sesión y crea una clave de API desde el panel de desarrollador.
2
Haz una solicitud
Envía tu clave como token Bearer en el encabezado Authorization.
3
Obtén los datos
Recibe respuestas JSON con los datos del producto e imágenes QC.

bash

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

Autenticación

Incluye una clave de API válida en el encabezado Authorization usando el esquema Bearer.

http

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Formato de la clave

Las claves siguen qc_{mode}_{random}, donde mode es live o test, y random son 32 caracteres criptográficamente aleatorios.

Las claves se muestran una sola vez al crearse. Solo almacenamos el hash SHA-256, así que una clave perdida no se puede recuperar — revócala y crea una nueva.

Lista de IP permitidas

Opcionalmente, restringe las claves a IP o rangos CIDR específicos desde el panel de desarrollador. Las solicitudes desde IP no incluidas reciben un 403. Una lista vacía permite todas las IP.

Límites de tasa

Dos contadores: por minuto y por mes. Tu nivel se lee de tu cuenta en cada solicitud — las mejoras de plan surten efecto de inmediato — y los límites se aplican a todas tus claves.

Nivel/ minuto/ mes

Basic301,000

Early Adopter403,000

Pro30025,000

Pro+1,000500,000

PersonalizadoIlimitadoIlimitado

/me y /usage requieren autenticación pero no consumen cuota: preguntar dónde estás no gasta la cuota por la que preguntas.

Encabezados

Se envían en todas las respuestas, no solo en los rechazos.

EncabezadoSignificado

X-RateLimit-LimitSolicitudes permitidas por minuto en tu nivel, o «ilimitado».

X-RateLimit-RemainingSolicitudes restantes en el minuto actual.

X-RateLimit-ResetSegundos hasta que se reinicie el contador que te bloqueó.

Al alcanzar el límite

La API devuelve 429 — RATE_LIMITED para el pico por minuto, QUOTA_EXCEEDED para la cuota mensual — con los segundos de espera en retry_after.

json

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

Errores

Los errores devuelven un estado que no es 2xx y un objeto error de nivel superior con un code estable y un message. Compara por el código, no por el mensaje — el mensaje puede cambiar.

json

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

EstadoCódigoSignificado

400BAD_REQUESTCuerpo o parámetros de la solicitud no válidos.

401INVALID_KEYClave de API ausente, malformada o desconocida.

401REVOKED_KEYLa clave fue revocada en el panel.

403IP_NOT_AUTHORIZEDLa IP de la solicitud no está en la lista permitida de la clave.

403FORBIDDENTu nivel no tiene acceso a este endpoint.

404NOT_FOUNDEl recurso solicitado no existe.

429RATE_LIMITEDLímite por minuto superado.

429QUOTA_EXCEEDEDCuota mensual agotada; se reinicia al cambiar de mes en UTC.

500INTERNALError nuestro. Puedes reintentar con backoff sin problema.

Endpoints

Las rutas siguientes son relativas a https://backend.qualit.ly/api/v1. Las tiendas son weidian, taobao y 1688. Los endpoints sin etiqueta funcionan en todos los planes.

Obtener producto

GET/products/{storefront}/{listing_id}

Un listado por tienda e ID. Devuelve sus metadatos y hasta 5 miniaturas de vista previa QC. Es el endpoint por el que empiezan la mayoría de las integraciones.

ParámetroTipoDescripción

storefrontobligatoriostringUna de: weidian, taobao, 1688.

listing_idobligatoriostringEl ID del artículo en la propia tienda.

Ejemplo

bash

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

Respuesta

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

Buscar productos

GET/products/search

Busca en el catálogo por nombre de producto — también se compara con la URL del producto. No hay paginación: cada plan devuelve hasta un número fijo de resultados.

ParámetroTipoDescripción

qobligatoriostringTexto de búsqueda. Varias palabras se combinan con AND contra el nombre y la URL del producto.

storefrontstringRestringe a weidian, taobao o 1688.

has_qcbooleanSolo listados que tengan fotos QC.

limitintegerPide menos que el máximo de tu plan. Los valores por encima se recortan hacia abajo, nunca hacia arriba.

Sin paginación. Cada plan devuelve hasta un número fijo de resultados por búsqueda; limit puede pedir menos, nunca más.

PlanMáx. resultados

Basic5

Early Adopter10

Pro50

Pro+100

Personalizado250

Ejemplo

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"

Respuesta

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_resultsEl máximo de tu plan — el techo al que se recorta `limit`.

countCuántas filas trae realmente esta respuesta.

Productos por lote

Pro+

POST/products/batch

Resuelve hasta 100 listados en una sola llamada. Cada elemento se resuelve de forma independiente, así que un producto que falte no hace fallar el lote — vuelve como una entrada de error en la misma posición.

ParámetroTipoDescripción

itemsobligatorioarrayArray de objetos { storefront, listing_id }. Limitado a 100, o al límite por página de tu plan si es menor.

Cuerpo de la solicitud

json

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

Ejemplo

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

Respuesta

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

Producto aleatorio

POST/products/random

Un listado aleatorio que tenga fotos QC — para vitrinas, feeds o muestrear el catálogo. No hace falta cuerpo de solicitud.

Ejemplo

bash

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

Respuesta

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

Metadatos QC

GET/qc/{storefront}/{listing_id}

El número de fotos QC de un listado, más las tres primeras miniaturas — sin traer la lista completa de imágenes.

ParámetroTipoDescripción

storefrontobligatoriostringUna de: weidian, taobao, 1688.

listing_idobligatoriostringEl ID del artículo en la propia tienda.

Ejemplo

bash

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

Respuesta

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

Imágenes QC

Pro+

GET/qc/{id}/images

Todas las fotos QC indexadas de un listado. Acepta el ID numérico del producto, o pasa ?url= con cualquier enlace de producto compatible y deja que la API lo resuelva.

ParámetroTipoDescripción

idobligatoriointegerID numérico del producto. Pasa 0 si buscas por ?url=.

urlstringURL completa del producto a resolver en lugar de un ID. Tiene prioridad cuando está presente.

Por ID de producto

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"

Respuesta

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

El parámetro ?url= acepta enlaces de producto de Weidian, Taobao y 1688, y de todos los agentes que admite el conversor de enlaces. Las imágenes son siempre URL de CDN.

Datos de la cuenta

GET/me

Tu cuenta, la clave que hizo la solicitud y el nivel al que resuelve. Útil como comprobación de estado.

Ejemplo

bash

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

Respuesta

json

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

Uso

GET/usage

Dónde te encuentras en ambos contadores de límite de tasa, con las marcas de tiempo de reinicio. Igual que /me, este endpoint requiere autenticación pero no consume cuota — consultar tu cuota no la gasta.

Ejemplo

bash

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

Respuesta

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

tierUno de basic, early_adopter, pro, pro_plus, custom.

limit / remainingnull en el nivel Custom, que es ilimitado.

usedSolicitudes dentro de la ventana actual. El contador por minuto se reinicia cada 60 s, el contador mensual al cambiar de mes en UTC.

reset_atISO 8601, UTC.

bucketClave interna AAAAMM del contador mensual.

Ejemplos 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

La misma API se sirve como un servidor Model Context Protocol alojado, así que Claude, Cursor, VS Code o cualquier cliente MCP pueden consultar listados y conjuntos de QC sin escribir HTTP. Tu clave de API, tus límites de tasa y las reglas de tu nivel se mantienen sin cambios.

URL del servidor

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

Transporte

StreamableHTTP (POST)

Autenticación

Authorization: Bearer qc_live_…

Herramientas

Solo se registran las herramientas que tu nivel puede usar, así que una clave Basic nunca ve una que le sería rechazada.

HerramientaDescripciónPlan

get_productBuscar un producto por tienda e ID de listado.

search_productsBuscar por nombre, con filtros de tienda y de fotos QC.

get_products_batchBuscar hasta 100 productos en una llamada.Pro+

random_productUn producto aleatorio que tenga fotos QC.

get_qcNúmero de fotos QC y las 3 primeras miniaturas.

get_qc_imagesLista completa de imágenes CDN, por ID o URL.Pro+

get_meClave, usuario y nivel actuales.

get_usageEstado de la cuota por minuto y mensual.

Claude Desktop, Cursor y VS Code

Añade el servidor a tu claude_desktop_config.json (Claude → Configuración → Desarrollador), o a la configuración MCP de tu 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"
        }
      }
    }
  }
}

Los clientes que admiten el descubrimiento de OAuth — entre ellos Claude.ai y ChatGPT — pueden prescindir por completo de la clave codificada: una solicitud sin autenticar recibe un encabezado WWW-Authenticate que apunta a los metadatos OAuth del servidor, y el cliente guía a tus usuarios por una página de inicio de sesión en su lugar.

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

Planes y niveles

Tu nivel se resuelve a partir de tu cuenta en cada solicitud, así que una mejora de plan se aplica ya en la siguiente llamada — no hace falta una clave nueva. Las búsquedas por lotes, las listas completas de imágenes QC y la extracción por ?url= son los únicos endpoints restringidos por encima de Basic; el resto solo varía en volumen.

Plan	/ minuto	/ mes	Resultados de búsqueda
Basic	30	1,000	5
Early Adopterheredado	40	3,000	10
Pro	300	25,000	50
Pro+	1,000	500,000	100
Personalizado	Ilimitado	Ilimitado	250

Early Adopter es un plan heredado — solo lo conservan las cuentas que ya lo tenían, nunca se vende. ¿Necesitas más que Pro+? Escribe a [email protected] para configurar límites personalizados.

Ver todos los planes, precios y ventajas