Plataforma Abierta HIOBuy

HIOBuy es un socio tecnológico autorizado oficialmente de Taobao, 1688 y Weidian. Conectamos fuentes de suministro chinas con tu plataforma mediante una API unificada: no solo datos de producto, sino todo el recorrido desde la sincronización del catálogo hasta la compra automatizada y, opcionalmente, la entrega internacional.

Qué proporciona HIOBuy

A diferencia de los scrapers genéricos de marketplaces o de los feeds de datos de solo lectura, HIOBuy está construido alrededor del fulfillment de extremo a extremo. Tu integración debe impulsar transacciones reales en tu tienda y a través de nuestras API de compras.

Diagrama (HIOBuy conecta fuentes chinas con tu plataforma: sincronización de productos, recepción de pedidos, compra automática y sincronización de estado)

HIOBuy se sitúa entre los marketplaces chinos y tu negocio: sincroniza productos, recibe pedidos, compra automáticamente y devuelve el estado a tu panel.

Capacidad	Qué significa para ti
Sincronización de productos	Búsqueda, detalle, búsqueda por imagen, SKU/stock/precio desde 1688, Taobao y Weidian mediante /v1/products/*
Recepción de pedidos	Tu backend envía los pedidos de clientes a HIOBuy cuando ocurre una venta en tu sitio
Compra automática	HIOBuy coloca el pedido correspondiente en el marketplace de origen mediante /v1/orders/*
Sincronización de estado	El progreso de compra, la logística nacional y, en modo almacén, el tracking internacional vuelven a tus sistemas; consulta Webhooks
Fulfillment internacional	Opcional: paquetes entrantes en almacén enviados al extranjero mediante /v1/fulfillment/* (solo modo almacén)

En qué nos diferenciamos de otras API

• Acceso por canales oficiales: integraciones con socios autorizados, no scraping no oficial.
• Orientada a transacciones: las API de productos existen para apoyar el sourcing y el checkout; las API de compras completan el ciclo de compra.
• Respuestas estándar unificadas: un esquema para 1688, Taobao y Weidian; consulta Formato de respuesta.
• Fulfillment integral opcional: modo propio para compradores que gestionan su propia logística; modo almacén cuando HIOBuy debe almacenar y enviar internacionalmente.

Uso aceptable y cuotas {#acceptable-use}

El acceso a la API no es ilimitado. Las cuotas y los límites de tasa están vinculados a tu acuerdo comercial y al volumen transaccional (GMV) esperado a través de la plataforma.

HIOBuy está pensado para integraciones en las que el descubrimiento de productos conduce a pedidos reales: los clientes compran en tu sitio y tu backend llama a /v1/orders/* para abastecerse. Las aplicaciones que solo consumen búsqueda/detalle de productos sin actividad de compra significativa, o que evitan HIOBuy para las compras mientras usan nuestras API de catálogo, no son compatibles y pueden suspenderse tras una revisión.

Los encabezados técnicos de límites de tasa y los códigos de error están documentados en Límites de tasa. Los términos comerciales se acuerdan durante el onboarding; no se repiten en las páginas individuales de endpoints.

Flujos de integración {#integration-flows}

Elige un modo de fulfillment en el portal de desarrolladores cuando autorices tu app. La ruta de la API de productos es similar; las compras y el envío internacional difieren.

Fulfillment propio: tú operas la compra

Recomendado cuando ya tienes cuentas de marketplace y gestionas el almacenamiento por tu cuenta.

1. Sincronización de productos: 1688 / Taobao / Weidian → Gateway HIOBuy: búsqueda, detalle, imágenes, SKU, stock
2. Visualización: Gateway HIOBuy → Tu tienda
3. Pedido del cliente: Tu cliente → Tu sitio web
4. Compra: Tu backend → Gateway HIOBuy: POST /v1/orders/preview → crear → pagar
5. Compra automática: Gateway HIOBuy → Marketplace (tu OAuth)
6. Retorno de estado: Marketplace → Gateway HIOBuy: compra y logística nacional
7. Sincronización del panel: Gateway HIOBuy → Tu panel

El envío internacional (/v1/fulfillment/*) no está disponible en modo propio. Tú gestionas la entrega al extranjero.

Fulfillment con almacén HIOBuy: extremo a extremo

Un único código de almacén vincula todos los canales; HIOBuy compra, almacena y envía internacionalmente.

1. API de productos: siguen llamando directamente a los marketplaces (baja latencia)
2. Sincronización de productos: hacia tu sitio orientado al cliente
3. Pedido del cliente: en tu sitio web
4. Compra: POST /v1/orders/* (reenviado al almacén HIOBuy)
5. Compra automática: almacén HIOBuy → Marketplace con tokens gestionados
6. Entrada: llegan los productos; parcel_nos en el detalle del pedido
7. Internacional: freight/estimate → preview → create → pay
8. Entrega: seguimiento mediante /v1/fulfillment/shipments/logistics/trace

Las API de compras e internacionales se enrutan a través de HIOBuy. Las API de productos permanecen directas a las plataformas por velocidad.

Comparación de modos

	Fulfillment propio	Almacén HIOBuy
Tokens de canal	Tú gestionas OAuth por canal	Un código de almacén vincula todos los canales
/v1/products/*	Gateway → marketplace	Gateway → marketplace (directo, baja latencia)
/v1/orders/*	Gateway → marketplace (tus tokens)	Gateway → API de almacén HIOBuy
/v1/fulfillment/*	No disponible	Envío internacional + saldo

Cómo convertirse en desarrollador {#become-a-developer}

1. Regístrate con tu empresa, sitio web y caso de uso (por ejemplo, agente de compras, tienda transfronteriza).
2. Verifica tu dirección de correo electrónico.
3. Inicia sesión y crea una App en el portal de desarrolladores: describe tu integración y el tráfico esperado.
4. Espera la revisión de HIOBuy. Aprobamos apps alineadas con sourcing basado en transacciones; recibirás la cuota y el acceso a canales correspondientes.
5. Tras la aprobación: autoriza canales (OAuth propio o código de almacén), luego crea una clave API en API Keys.
6. Integra: detalle de producto → checkout del cliente → preview/create de compra → pago → webhooks de estado. En modo almacén, añade el flujo de envío internacional.

¿Necesitas un código de desarrollador de almacén? Contacta con operaciones de HIOBuy después de que tu app sea aprobada para fulfillment de almacén.

Mapa de referencia de la API

URL base: https://api.hiobuy.com/v1

Área	Prefijo	Docs
Productos	/v1/products/*	Productos
Compras	/v1/orders/*	Pedidos de compra
Fulfillment	/v1/fulfillment/*	Envíos y saldo

Dos tipos de pedido; no los mezcles: la compra (/v1/orders/*) compra a vendedores chinos hacia un almacén nacional; el envío internacional (/v1/fulfillment/shipments/*) envía paquetes entrantes al extranjero.

Orden de lectura recomendado {#reading-order}

1. Convertirse en desarrollador: registro, aprobación de app, clave API
2. Autenticación + Autorización del portal
3. Productos → Pedidos de compra
4. Opcional: Fulfillment (modo almacén)
5. Errores y Límites de tasa al endurecer producción

Alcance de la API pública {#public-api-scope}

Esta documentación describe la superficie soportada de la API pública. Algunas rutas pueden aparecer en openapi.json  para uso interno o obsoleto (por ejemplo, rutas heredadas /v1/shipments, rutas de reembolso); si un endpoint no aparece aquí, trátalo como no disponible.

Convenciones técnicas {#technical-conventions}

• Auth: Authorization: Bearer YOUR_API_KEY: Autenticación
• language de producto en el cuerpo JSON: Idiomas
• Precios: yuanes CNY en productos, fen en pedidos y envíos
• response_format: "standard" (predeterminado) o "upstream": Formato de respuesta

Especificación OpenAPI: api.hiobuy.com/openapi.json 

Documentación publicada: hiobuy.com/api-docs