API de Búsqueda de 1688
Salud de la API
- Salud 24 h
- 100 %
- Tiempo medio 24 h
- 12.71 s
- Saludable / normal
- Disponible
- Limitada
- Casi sin servicio
Últimas 24 horas
Últimos 30 días
Usa keyword para el producto y, si hace falta, city, min_price, max_price o sort para acotar la lista. Conserva price_min, price_max, currency, min_order_quantity y supplier_name; el orden y order_count no prueban ventas exactas ni una cotización final.
Envía POST https://api.everyinfra.com/api/v1/social con platform igual a alibaba1688 y action igual a search. Precio $2.78 por 1.000 solicitudes ($0.002778 por llamada). Las llamadas fallidas y los resultados vacíos no se cobran. Síncrona. Para tareas lentas añade "mode": "async" al cuerpo, recibe un job_id y consúltalo.
1688 Búsqueda encuentra productos al por mayor por keyword y devuelve de cada uno el título, el rango de precios, la cantidad mínima de pedido, las unidades vendidas, la tasa de recompra, el nombre del proveedor, su ubicación, su tipo de negocio y sus años en la plataforma, el estado del stock y si admite dropshipping. Sirve para ver qué proveedores tienen un producto y qué condiciones de pedido y precios manejan a grandes rasgos: es el primer paso para buscar proveedores, compararlos o elegir productos para una tienda de dropshipping.
Acota el precio con min_price y max_price, filtra por ciudad con city y ordena con sort (relevancia, más vendidos o precio de menor a mayor o al revés). Mira primero min_order_quantity, porque es el primer umbral de la compra mayorista; repurchase_rate y supplier_composite_score te permiten filtrar proveedores antes de abrir ningún producto. Los filtros de precio no garantizan que todas las variantes y tramos de cantidad queden dentro del rango; lo que cuenta son los precios escalonados del detalle del producto.
Prompt para IA
#Ayúdame a escribir un script de recopilación de datos con el endpoint de EveryInfra 1688: Búsqueda (alibaba1688/search).
Cómo funciona el endpoint:
- Solicitud: POST https://api.everyinfra.com/api/v1/social con la cabecera Authorization: Bearer <clave API>. Lee la clave de la variable de entorno EVERYINFRA_API_KEY y no la escribas en el código.
- En el cuerpo de la solicitud, pon platform en alibaba1688 y action en search, y los parámetros dentro de params.
- Parámetros obligatorios:
- keyword: Término de búsqueda de productos al por mayor en 1688, como «termo» o «caja de cartón». Se usa para search; no es el nombre de la tienda ni el offerId.
- Parámetros opcionales:
- city: Filtro de texto por ciudad para la búsqueda de productos en 1688. No es la ubicación de la cuenta ni modifica la dirección del proveedor devuelta.
- max_price: Límite superior numérico para el filtro de precios de productos al por mayor. Admite decimales.
- min_price: Límite inferior numérico para el filtro de precios de productos al por mayor. Admite decimales.
- sort: Orden de búsqueda de productos: relevance para relevancia, popular para los más vendidos, price_asc / price_desc para precio ascendente / descendente. Si no se envía, search usa relevance. (valores admitidos: popular / price_asc / price_desc / relevance)
- limit: Número máximo de filas que devuelve esta llamada, un entero de 1 a 100. Si no lo envías, se usa el valor predeterminado, y una llamada puede devolver menos filas. (por defecto: 20)
- Devuelve una lista de registros. Campos principales de cada registro: id, url, title, text, price_min (Límite inferior del rango de precios), price_max (Límite superior del rango de precios), currency, min_order_quantity (Cantidad mínima de pedido (MOQ)), order_count (Número de pedidos), repurchase_rate (Tasa de recompra), category (Nombre de la categoría según la taxonom…), city (Nombre de la ciudad en el idioma de la…); 68 campos en total, lista completa en https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688.
- Cuerpo de solicitud de ejemplo:
{
"platform": "alibaba1688",
"action": "search",
"params": {
"keyword": "不锈钢保温杯"
}
}
- Precio: $2.78 por 1.000 solicitudes; los resultados fallidos y vacíos no se cobran.
- Para decenas o cientos de objetivos, añade "mode": "async" al cuerpo: recibes un job_id al instante y consultas GET https://api.everyinfra.com/api/v1/jobs/{job_id} para obtener el resultado.
- Ante un 422, corrige la solicitud con los nombres de parámetros y los valores admitidos que sugiere el error; ante un 429 o un 503, espera lo que indique Retry-After y vuelve a intentarlo.
Antes de escribir código, pregúntame qué objetivos necesito, cuántos, qué campos y en qué formato quiero el resultado; luego confirma conmigo el plan y el coste aproximado.Parámetros de la solicitud
#| Nombre | Ubicación | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|---|
Authorization | header | string | Sí | - | Bearer seguido de tu clave de API. Créala en la consola; nunca la pongas en una URL ni en un repositorio de código. |
platform | body | string | Sí | alibaba1688 | Identificador de la plataforma, valor fijo. |
action | body | string | Sí | search | Identificador de la capacidad, valor fijo. |
keyword | body.params | string | Sí | - | Término de búsqueda de productos al por mayor en 1688, como «termo» o «caja de cartón». Se usa para search; no es el nombre de la tienda ni el offerId. La cantidad mínima de pedido y los precios por tramos forman parte de la información del producto devuelta. |
city | body.params | string | No | - | Filtro de texto por ciudad para la búsqueda de productos en 1688. No es la ubicación de la cuenta ni modifica la dirección del proveedor devuelta. Al especificar un producto concreto, no se puede dar por sentado que este filtro siga activo. |
max_price | body.params | number | No | - | Límite superior numérico para el filtro de precios de productos al por mayor. Admite decimales; si la llamada pasa a filtrar en yuanes enteros, se redondean hacia arriba (145.98 pasa a 146), así que el rango solo se amplía. No es el límite superior de cantidad en la tarificación por tramos. Se usa con min_price para limitar el rango de precios, pero no garantiza que cada SKU o tramo de cantidad esté dentro de dicho rango. |
min_price | body.params | number | No | - | Límite inferior numérico para el filtro de precios de productos al por mayor. Admite decimales; si la llamada pasa a filtrar en yuanes enteros, se redondean hacia abajo (39.81 pasa a 39), así que el rango solo se amplía. No es la cantidad mínima de pedido (MOQ) ni el presupuesto para llamadas a la API. Diferentes cantidades de compra pueden corresponder a diferentes precios por tramos, por lo que el precio filtrado no debe tomarse como la oferta final. |
sort | body.params | string (enum) | No | - | Orden de búsqueda de productos: relevance para relevancia, popular para los más vendidos, price_asc / price_desc para precio ascendente / descendente. Si no se envía, search usa relevance. El orden no garantiza la devolución del volumen de ventas o el importe exacto de las transacciones.Valores permitidospopularprice_ascprice_descrelevance |
limit | body.params | integer (1–100) | No | 20 | Número máximo de filas que devuelve esta llamada, un entero de 1 a 100. Si no lo envías, se usa el valor predeterminado, y una llamada puede devolver menos filas. Los valores mayores devuelven 422 antes de cualquier cobro. |
Ejemplos de código
#curl -X POST 'https://api.everyinfra.com/api/v1/social' \
-H "Authorization: Bearer $EVERYINFRA_API_KEY" \
-H 'Content-Type: application/json' \
--data-raw '{
"platform": "alibaba1688",
"action": "search",
"params": {
"keyword": "不锈钢保温杯"
}
}'Definición OpenAPI (JSON)Los ejemplos leen la clave de la variable de entorno EVERYINFRA_API_KEY; el código copiado nunca contiene tu clave.
Ejemplo de respuesta
#{ "id": "req_…", "platform": "alibaba1688", "action": "search", "results": [ { "id": "•••", "url": "https://detail.1688.com/offer/901095512547.html", "title": "跨境美式太空壶304不锈钢双层真空保温杯大容量运动水壶登山水壶", "price_min": 12.5, "currency": "CNY", "order_count": 33, "repurchase_rate": 20, "city": "永康市", "province": "浙江", "supplier_name": "永康市钛霖杯业有限公司", "images": [ "https://cbu01.alicdn.com/img/ibank/O1CN01LbpPbm2B0StIPXCWn_!!2219521848276-0-cib.jpg" ], "supplier_type": "生产加工", "supplier_years": 2, "supplier_shop_url": "https://shop81l5635to8463.1688.com", "sold_count_text": "已售1200+件", "service_tags": [ "退货包运费", "先采后付", "回头率54%" ], "product_badges": [ "先采后付" ], "platform": "1688" }, { "id": "•••", "url": "https://detail.1688.com/offer/1080785307425.html", "title": "新款彩色304不锈钢保温杯 便携手提弹跳盖户外便携运动水杯定 制", "price_min": 24, "currency": "CNY", "min_order_quantity": 1, "order_count": 49, "repurchase_rate": 14, "city": "金华市", "province": "浙江", "supplier_name": "永康市大表哥工贸有限公司", "images": [ "https://cbu01.alicdn.com/img/ibank/O1CN01NbBs3QLcV7L3thOC_!!2217763939489-0-cib.jpg" ], "supplier_type": "生产加工", "supplier_years": 3, "supplier_shop_url": "https://15727971454.1688.com", "sold_count_text": "已售500+件", "service_tags": [ "退货包运费", "先采后付", "回头率67%" ], "product_badges": [ "7×24H响应", "先采后付" ], "platform": "1688" } ], "count": 20, "billing": { "charged": …, "charged_usd": …, "balance_after_usd": …, … }, "quota": { … }}
Campos de la respuesta
#Los datos están en results. La tabla lista los campos que puede tener cada registro; los valores que la plataforma no muestra nunca se inventan.
| Campo | Significado |
|---|---|
id | Identificador único del registro en la plataforma. Solo es único dentro de una plataforma; puede repetirse entre plataformas. |
url | Enlace al registro en la plataforma. |
title | Título. null cuando la plataforma no usa títulos (por ejemplo publicaciones solo de texto). |
text | Texto del contenido sin HTML, completo y sin recortes (en algunas plataformas los resultados de listado solo traen un extracto; lo indican las notas de campos de la plataforma). |
price_min | Límite inferior del rango de precios. |
price_max | Límite superior del rango de precios. |
currency | Código de moneda del precio (por ejemplo CNY, USD). Si hay price pero currency es null, no supongas una moneda. |
min_order_quantity | Cantidad mínima de pedido (MOQ). Es el primer umbral de la compra mayorista en 1688: revísalo antes que nada. |
order_count | Número de pedidos. |
repurchase_rate | Tasa de recompra. Una de las señales más sólidas de la calidad de un proveedor en 1688. |
category | Nombre de la categoría según la taxonomía propia de la plataforma, sin normalizar entre plataformas. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
city | Nombre de la ciudad en el idioma de la plataforma, sin normalizar. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
province | Provincia donde está el proveedor. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_name | Nombre del proveedor. |
is_out_of_stock | Si el producto está agotado. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supports_dropship | Si el proveedor envía unidades sueltas en tu nombre (dropshipping). Es un filtro clave para vender sin tener stock. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
images | Enlaces de las imágenes principales del producto, en el orden de la página; en product_detail algunos anuncios incluyen también imágenes de variantes (SKU), y las imágenes de la descripción van en description_images. No aparece si no hay imágenes. |
supplier_type | Modo de negocio del proveedor (p. ej. fabricante, mayorista). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_years | Años del proveedor en la plataforma 1688. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_shop_url | Enlace a la tienda del proveedor. |
supplier_composite_score | Puntuación compuesta de servicio del proveedor (1-5). |
sold_count_text | Ventas tal como se muestran en las filas de búsqueda (texto original chino, p. ej. 100+ vendidos en toda la red). |
service_tags | Lista de etiquetas de servicio en las filas de búsqueda. |
product_badges | Lista de insignias del producto en las filas de búsqueda. |
rating | Valoración global del producto (1-5). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
rating_scale | Máximo de rating en la misma fila: 5 en escalas de cinco estrellas y 10 en escalas de diez puntos. Solo aparece si la fila tiene rating. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
review_count | Número total de reseñas. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
positive_rate | Tasa de reseñas positivas como fracción 0-1 (0,999 = 99,9 %). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
sold_count | Unidades vendidas. |
sold_display | Ventas tal como se muestran en el texto original chino (p. ej. 100k+ vendidos); para la cifra numérica usa sold_count. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
want_buy_count | Número de compradores que marcaron el anuncio como deseado (señal de demanda). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
stock | Stock. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
unit | Unidad de precio (pieza, artículo, caja, etc.). |
category_path | Ruta de categoría completa con los segmentos en el idioma de origen (chino). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
video_url | URL del video del producto, cuando el anuncio tiene uno. |
winport_url | Enlace a la tienda 1688 del proveedor. |
supplier_fans | Número de seguidores del proveedor. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_founded_year | Año de fundación del proveedor. |
price_tiers | Precios escalonados: el precio unitario baja a medida que sube la cantidad del pedido. Lee cada tramo junto con su cantidad mínima. |
specs | Tabla de especificaciones: lista de pares {name, value} (p. ej. Material: TPU). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
description_images | Lista de URLs de las imágenes de descripción del detalle, en el orden original del anuncio; null si el anuncio no tiene ninguna. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
coupons | Conserva el significado de la plataforma |
promotion_details | Conserva el significado de la plataforma |
service_details | Detalle de las garantías de servicio: code (código del servicio), name, description (la regla), rule_url (página de la regla). services / service_tags solo dan los nombres. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
purchase_limits | Conserva el significado de la plataforma |
mix_wholesale | Conserva el significado de la plataforma |
supports_mix | Si el anuncio admite pedidos mixtos (combinar distintos modelos para alcanzar el pedido mínimo). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
review_tags | Etiquetas de impresión de los compradores: [{tag, count}], por ejemplo «tela suave» ×2. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
refund_rate | Conserva el significado de la plataforma |
review_negative_count | Conserva el significado de la plataforma |
review_neutral_count | Conserva el significado de la plataforma |
review_with_photo_count | Número de reseñas con fotos; null significa que no se indicó, no que sea 0. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
review_with_text_count | Número de reseñas con texto; null significa que no se indicó, no que sea 0. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_stats | Perfil del proveedor (solo las claves con valor): employee_count, plant_area_sqm (superficie de la fábrica en m²), plant_type (por ejemplo, fábrica propia), equipment_count (equipos principales), product_count (productos a la venta), repeat_rate (tasa de recompra, 0-1), repeat_buyer_count_text / cross_border_buyer_count_text (compradores recurrentes y transfronterizos tal como aparecen, como 300+), response_rate (0-1), positive_review_rate (0-1), fulfillment_rate (0-1), certificate_count / certificates / management_certificates (número de certificados, nombres y certificaciones de sistemas de gestión), patent_count, oem_mode (OEM/ODM), own_brands (marcas propias tal como aparecen), brand_count, partner_brand, is_major_brand_partner (provee a grandes marcas), scale_tier (nivel de tamaño), honors. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_scores | Conserva el significado de la plataforma |
supplier_metric_tags | Conserva el significado de la plataforma |
supplier_rank | Conserva el significado de la plataforma |
supplier_industry_belt | Certificación de clúster industrial: description (por ejemplo, comerciante insignia certificado por 1688 de un clúster regional de ropa), link_url (página de la certificación). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_certification | Auditoría de fábrica o de empresa por terceros: agency (código del auditor, como sgs o tuv), report_number (número del informe tal como aparece), report_url (página del informe). En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_verification_tags | Conserva el significado de la plataforma |
supplier_inspection_report_url | Conserva el significado de la plataforma |
supplier_videos | Conserva el significado de la plataforma |
supplier_address | Dirección del proveedor tal como aparece. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_coordinates | Ubicación del proveedor: {longitude, latitude}. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
supplier_main_category | Categoría principal del proveedor. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
customization | Conserva el significado de la plataforma |
shipping | Conserva el significado de la plataforma |
unit_weight_kg | Peso de una unidad, en kilogramos. En los detalles del producto puede venir vacío en una llamada síncrona; una llamada asíncrona normalmente lo trae. |
platform | Identificador de la plataforma, igual que platform en la solicitud (por ejemplo xiaohongshu, tiktok). |
Preguntas frecuentes
#¿Por qué los precios filtrados no coinciden con la página del producto?
#En 1688 los precios son escalonados: el precio unitario depende de cuántas unidades compres. min_price y max_price filtran por el precio que muestra la búsqueda, sin garantizar que todas las variantes o tramos de cantidad queden dentro del rango. La cotización real son los precios escalonados del detalle del producto.
¿Sobre qué filtra city?
#Filtra los productos por el texto de una ciudad. No es la ubicación de tu cuenta ni cambia las direcciones de proveedor que se devuelven; mira desde dónde se envía la mercancía en los campos city y province de cada resultado.
¿Cómo encuentro proveedores que hagan dropshipping?
#Quédate con los resultados en los que supports_dropship sea true y después revisa min_order_quantity e is_out_of_stock para saber si puedes pedir cantidades pequeñas y si el artículo está disponible. Una repurchase_rate alta y unos supplier_years largos son buenas señales de que el proveedor cumple con regularidad.
Errores y facturación
#- 401
- Falta la clave o no es válida.
- 402
- Saldo insuficiente. Recarga primero.
- 422
- Nombre o valor de parámetro incorrecto. Corrígelo según las opciones indicadas en el error. Sin cargo.
- 429
- Se alcanzó el límite de solicitudes por minuto. Espera el tiempo indicado en Retry-After y vuelve a intentarlo.
- 503
- No se pudo completar. El cargo retenido vuelve a tu saldo. Si el resultado es incierto, compruébalo antes de reenviar.
- 200 vacío
- Sin datos. Sin cargo.