Guía de uso de API abierta y servicio MCP de UpSeller

Para qué sirve uso de API abierta y servicio MCP de UpSeller
UpSeller ahora admite API abierta y MCP (conexión con herramientas de IA).

 
Esta función está diseñada para usuarios que necesitan integrar sistemas o acceder a los datos de UpSeller mediante herramientas de IA.

 
Puedes integrar los datos de UpSeller en tus propios sistemas mediante la API abierta, o conectar MCP con herramientas de IA como Claude, Codex, ChatGPT y Cursor para consultar y gestionar los datos de UpSeller.

Alcance
Disponible para usuarios de los planes Pro, Enterprise, Enterprise Plus y Kit, sin costo adicional.

Límite de solicitudes
Nota: el límite se calcula por interfaz. Los límites según el plan son:

 

	

		

			
Plan
			
API/min
			
MCP/min
		
	
	

		

			
Pro
			
100
			
60
		
		

			
Enterprise
			
200
			
120
		
		

			
Enterprise Plus
			
500
			
300
		
	

 

 
 

Recursos disponibles
Actualmente, la API abierta y MCP de UpSeller permiten consultar los siguientes datos:

 

	

		

			
Función
			
API
			
Herramienta MCP
			
Descripción
		
	
	

		

			
Consultar almacenes
			
getWarehouseList/v1
			
get_warehouse_list_by_puid
			
Consulta la lista de almacenes de la cuenta
		
		

			
Consultar inventario SKU
			
pageWarehouseSku/v1
			
page_warehouse_sku_inventory_list
			
Consulta el inventario de todos o determinados SKU de un almacén
		
	

 

 

Cómo obtener las credenciales de autorización
Antes de configurar la API o MCP, accede al panel de UpSeller para obtener la información de autorización: ID de Cliente, API Token y MCP Token.

Paso 1: Activa la función
1. Inicia sesión en UpSeller y haz clic en Plataforma Abierta >> API / MCP

 
2. Si es la primera vez que utilizas la función, haz clic en el botón azul Generar




 

Paso 2: Copia las credenciales
Una vez generadas, el sistema mostrará la siguiente información. Guárdala de forma segura:


	
ID de Cliente: identificador único de tu cuenta.
	
API Token: clave de autenticación para las llamadas a la API.
	
MCP Token: clave de autenticación para conectar modelos de IA o herramientas de desarrollo de IA.


 
Nota: los Tokens son información confidencial. No los compartas con terceros. Si existe algún riesgo de seguridad, puedes volver a generarlos o eliminarlos desde la misma página.

Cómo conectar la API o MCP

1. Descripción de las interfaces de consulta de inventario
Estas interfaces permiten consultar los almacenes y el inventario, incluida la lista de almacenes de la cuenta y el inventario SKU de cada almacén.

Información básica


	
Protocolo: HTTP/HTTPS
	
Método: POST
	
Formato: JSON
	
Autenticación: mediante clave API en los encabezados de la solicitud


Encabezados comunes


	

		

			
Parámetro
			
Tipo
			
Obligatorio
			
Descripción
		
	
	

		

			
X-Upseller-Client-Id
			
String
			
Sí
			
ClientId de autenticación
		
		

			
X-Upseller-Api-Token
			
String
			
Sí
			
Token de autenticación
		
		

			
X-Upseller-Language
			
String
			
Sí
			
`en` Inglés / `es` Español / `pt` Portugués / `cn` Chino
		
	

 

 

Formato de respuesta común


 

Campos de respuesta comunes


	

		

			
Campo
			
Tipo
			
Obligatorio
			
Descripción
		
	
	

		

			
code
			
Integer
			
Sí
			
Código de estado. `0` = éxito
		
		

			
message
			
String
			
Sí
			
Mensaje de respuesta
		
		

			
data
			
Object
			
No
			
Datos de respuesta según la interfaz
		
		

			
requestId
			
String
			
Sí
			
ID único de la solicitud
		
	

 

 

Códigos de error comunes
 


	

		

			
Código
			
Descripción
		
	
	

		

			
0
			
Éxito
		
		

			
4001
			
Parámetros de solicitud faltantes, formato o valor no válido, o parámetros de negocio incorrectos
		
		

			
4003
			
Falta de autenticación, credenciales no válidas, identidad no coincidente o sesión expirada
		
		

			
4040
			
Usuario, almacén, Token, ruta, beneficio del plan o herramienta no disponible
		
		

			
5000
			
Error interno del servidor
		
	

 

 

Detalles de las interfaces

1. Consultar la lista de almacenes

Descripción
Consulta la lista de almacenes de la cuenta actual.

Información de la solicitud


	
URL: https://openapi.upseller.com/erp/inventory/getWarehouseList/v1
	
Método: POST
	
Tipo de contenido: application/json


Encabezados
Consulta los Encabezados comunes.

Cuerpo de la solicitud


 

Parámetros de la solicitud


	

		

			
Parámetro
			
Tipo
			
Obligatorio
			
Máx.
			
Descripción
		
	
	

		

			
warehouseType
			
String
			
No
			
32
			
`ALL`: todos los almacenes; `SELF_OPERATED`: almacén propio; `THIRD_PARTY`: almacén 3PL
		
	

 

Ejemplo de solicitud




 

Campos de respuesta


	

		

			
Campo
			
Tipo
			
Descripción
		
	
	

		

			
warehouseId
			
String
			
ID del almacén
		
		

			
puid
			
Integer
			
ID de usuario
		
		

			
warehouseName
			
String
			
Nombre del almacén
		
		

			
warehouseType
			
String
			
Tipo de almacén (0: propio, 1: 3PL)
		
		

			
isDefault
			
Boolean
			
Si es predeterminado (true: sí, false: no)
		
		

			
serviceId
			
Long
			
ID del servicio
		
		

			
providerName
			
String
			
Nombre del proveedor
		
		

			
providerType
			
String
			
Tipo de proveedor
		
		

			
3plId
			
Long
			
ID del almacén 3PL no perteneciente a la plataforma
		
		

			
3plWarehouseCode
			
String
			
Código del almacén 3PL
		
		

			
3plWarehouseName
			
String
			
Nombre del almacén 3PL
		
		

			
serviceAuthName
			
String
			
Nombre de autorización del proveedor
		
		

			
country
			
String
			
País
		
		

			
province
			
String
			
Estado/Provincia
		
		

			
city
			
String
			
Ciudad
		
		

			
address
			
String
			
Dirección
		
		

			
postCode
			
String
			
Código postal
		
		

			
createTime
			
Date
			
Fecha de creación
		
		

			
updateTime
			
Date
			
Fecha de actualización
		
	

 

 

Ejemplo de respuesta




 

2. Consultar el inventario SKU por página

Información de la solicitud


	
URL: https://openapi.upseller.com/erp/inventory/pageWarehouseSku/v1
	
Método: POST
	
Tipo de contenido: application/json


Encabezados
Consulta los Encabezados comunes.

Cuerpo de la solicitud




 

Ejemplo de solicitud


 

Parámetros del cuerpo de la solicitud


	

		

			
Parámetro
			
Tipo
			
Obligatorio
			
Máx.
			
Descripción
		
	
	

		

			
warehouseIdList
			
List
			
Sí
			
-
			
Lista de IDs de almacén, máx. 100
		
		

			
skuList
			
List
			
No
			
-
			
Lista de SKU, máx. 300
		
		

			
updateTime
			
Long
			
No
			
-
			
Hora de actualización del inventario
		
		

			
pageNo
			
Integer
			
No
			
-
			
Cursor de paginación
		
		

			
pageSize
			
Integer
			
No
			
-
			
Registros por página, máx. 100
		
	

 

 

Campos de respuesta


	

		

			
Campo
			
Tipo
			
Descripción
		
	
	

		

			
warehouseId
			
Number
			
ID del almacén
		
		

			
warehouseName
			
String
			
Nombre del almacén
		
		

			
warehouseType
			
String
			
Tipo de almacén
		
		

			
isGroup
			
Number
			
Si es un grupo
		
		

			
skuId
			
Number
			
ID del SKU
		
		

			
sku
			
String
			
SKU
		
		

			
skuType
			
String
			
Tipo de SKU
		
		

			
skuTitle
			
String
			
Título/nombre del SKU
		
		

			
imgUrl
			
URL/Text
			
URL de imagen
		
		

			
categoryId
			
Number
			
ID de categoría
		
		

			
categoryName
			
String
			
Nombre de categoría
		
		

			
minStock
			
Number
			
Stock mínimo de alerta
		
		

			
maxStock
			
Number
			
Stock máximo
		
		

			
isMinStock
			
Checkbox/Boolean
			
Si está por debajo del mínimo (true/false)
		
		

			
unitCost
			
Number
			
Costo unitario
		
		

			
subTotal
			
Number
			
Importe subtotal
		
		

			
createTime
			
Number
			
Fecha de creación (timestamp)
		
		

			
updateTime
			
Number
			
Fecha de actualización (timestamp)
		
		

			
Inventario de almacén propio(up_info)
		
		

			
up_info.onHand
			
Number
			
Almacén propio - stock total
		
		

			
up_info.allocated
			
Number
			
Almacén propio - stock ocupado
		
		

			
up_info.available
			
Number
			
Almacén propio - stock disponible
		
		

			
up_info.inTransit
			
Number
			
Almacén propio - stock total en tránsito
		
		

			
up_info.inTransitPurchase
			
Number
			
Almacén propio - compras en tránsito
		
		

			
up_info.inTransitTransfer
			
Number
			
Almacén propio - transferencias en tránsito
		
		

			
Inventario de almacén 3PL(3pl_info)
		
		

			
3pl_info.3plOnHand
			
Number
			
3PL - stock actual
		
		

			
3pl_info.3plAvailable
			
Number
			
3PL - stock disponible
		
		

			
3pl_info.3plTotalAllocated
			
Number
			
3PL - stock ocupado
		
		

			
3pl_info.3plOtherAllocated
			
Number
			
3PL - otras unidades ocupadas
		
		

			
3pl_info.3plUnavailable
			
Number
			
3PL - stock no disponible
		
	

 

 

Ejemplo de respuesta




 

Errores frecuentes
1. Error de autenticación: comprueba que los encabezados estén configurados correctamente.

 
2. Error de parámetros: comprueba el formato y los parámetros obligatorios.

 
3. Error del servidor: contacta con Soporte Técnico e indica el `requestId` para facilitar el seguimiento.

Notas
1. Todos los campos de fecha utilizan el formato ISO 8601, por ejemplo, 2023-01-01T12:00:00Z.

 
2. Se recomienda configurar reintentos adecuados, especialmente cuando la conexión de red sea inestable.

 
3. En las consultas paginadas, configura pageNo y pageSize de forma adecuada para evitar problemas de rendimiento.

Documentación del servicio MCP

Información del servicio


	
Transport = streamable-http
	
URL = https://openapi.upseller.com/mcp


Encabezados comunes


	

		

			
Parámetro
			
Tipo
			
Obligatorio
			
Descripción
		
	
	

		

			
X-Upseller-Client-Id
			
String
			
Sí
			
ClientId de autenticación
		
		

			
X-Upseller-Api-Token
			
String
			
Sí
			
Token de autenticación
		
		

			
Accept
			
String
			
Sí
			
text/event-stream, application/json
		
		

			
Content-Type
			
String
			
Sí
			
application/json
		
		

			
X-Upseller-Language
			
String
			
Sí
			
`en` Inglés / `es` Español / `pt` Portugués / `cn` Chino
		
	

 

 

Herramientas disponibles

1. get_warehouse_list_by_puid
Función: Consulta la lista de almacenes de la cuenta autenticada.

 
Nombre de la herramienta: `get_warehouse_list_by_puid

 
Parámetros: warehouseType (String): tipo de almacén. Valores disponibles: ALL, SELF_OPERATED, THIRD_PARTY.

 
Descripción: Obtiene la información de los almacenes de la cuenta autenticada. Admite chino, inglés, portugués y español.

 
Palabras clave:


	
Inglés: view warehouses, get warehouses, list warehouses, my warehouses, warehouse list
	
Español: ver almacenes, listar almacenes, mis almacenes, lista de almacenes

Valor de retorno: McpResult

 
Uso: se utiliza cuando el usuario solicita consultar, obtener o listar los almacenes de su cuenta. No se utiliza para consultar el inventario SKU.

2. page_warehouse_sku_inventory_list
Función: Consulta la lista de inventario SKU de un almacén específico de la cuenta autenticada.

 
Nombre de la herramienta: page_warehouse_sku_inventory_list

 
Parámetros: PageWarehouseSkuQuery (objeto):


	
warehouseIdList: lista de IDs de almacén (1-100)
	
skuList: lista de SKU, opcional
	
pageNo: cursor de paginación
	
pageSize: registros por página (1-100, predeterminado: 20)
	
updateTime: hora de actualización

Descripción: Consulta por página el inventario SKU de un almacén específico. Admite chino, inglés, portugués y español.

 
Palabras clave:


	
Inglés: view inventory, query inventory, get inventory, list inventory, SKU stock, warehouse stock
	
Español: ver inventario, consultar inventario, obtener inventario, listar inventario, stock SKU

Valor de retorno: McpResult

 
Uso: se utiliza cuando el usuario solicita consultar, obtener o listar el inventario SKU de un almacén. No se utiliza para obtener la lista de almacenes.