UpSeller Central de Ajuda Arquivos de Ajuda MCP+API

[MCP] Guia de operação da OpenAPI e das ferramentas MCP do UpSeller

Atualize no 09 Nov,2026Copiar Link

O UpSeller agora oferece suporte a API aberta e à funcionalidade MCP (conexão de ferramentas de IA). Você pode integrar perfeitamente os recursos de dados do UpSeller aos seus próprios sistemas ou conectar-se a ferramentas de IA como Claude, Cursor, Codex, para realizar o gerenciamento inteligente de e-commerce por meio de linguagem natural.

1. Resumo

1.1 O que é a UpSeller OpenAPI

O UpSeller OpenAPI é uma interface HTTP padronizada (formato JSON) aberta para comerciantes. Você pode integrar dados como estoque, armazéns e pedidos do UpSeller ao seu próprio ERP, painel de loja independente, sistema de relatórios ou scripts automatizados, para implementar cenários programáticos como sincronização programada, processamento em lote e alertas de falta de estoque.

1.2 O que é a ferramenta inteligente UpSeller MCP

As ferramentas inteligentes MCP permitem que assistentes de IA como Claude, Cursor, Codex, Doubao / Coze se conectem diretamente aos dados da UpSeller. Após a ativação, não é necessário escrever código: basta fazer perguntas em linguagem natural (por exemplo, "verifique para mim quanto estoque resta no armazém de São Paulo para PORTA-MAQUIAGEM-G" ou "liste meus 10 pedidos manuais mais recentes"), e a IA irá acionar automaticamente as ferramentas correspondentes e retornar os resultados.

1.3 Distinção entre OpenAPI e MCP e cenários de aplicação

Recomendação de seleção：Se você precisa que os dados do UpSeller fluam de forma contínua e automática para um determinado sistema, utilize a OpenAPI; se for apenas uma consulta ou inserção de dados temporária e sob demanda, utilize a ferramenta inteligente MCP. Ambos podem ser usados em paralelo, sem interferir um no outro.

1.4 Pré-condições de utilização

1.5 Limites de solicitação

2. Visão geral da lista de competências

2.1 Descrição do Módulo de Negócio

2.2 Visão geral da interface OpenAPI

2.3 Visão geral da ferramenta MCP

3. Especificações Gerais de Integração

3.1 Endereço do Ambiente

3.2 Métodos de Autenticação

Primeiro passo: ative a funcionalidade. Faça login no painel da UpSeller e clique no menu à esquerda Plataforma Aberta → API / MCP e, na primeira utilização, clique no botão azul Gerar no lado direito.

Passo 2: Copie a credencial de autorização. Após a geração bem-sucedida, a página exibirá os três itens a seguir, guarde-os com cuidado:

Cabeçalhos de solicitação comuns da OpenAPI：

Informações de Acesso Geral do MCP：
{ "mcpServers": { "upseller": { "url": "https://openapi.upseller.com/mcp", "headers": { "Authorization": "Bearer {YOUR_MCP_TOKEN}", "X-Upseller-Language": "cn" } } } }
Segurança e redefinição do token：O token é informação sensível, não o divulgue a terceiros, nem o insira em código de front-end ou repositórios públicos. Caso detete riscos de segurança, pode a qualquer momento clicar em Redefinir ou Eliminar na página acima; após a redefinição, o token antigo deixa imediatamente de ser válido, pelo que deve atualizar em simultâneo as configurações no seu sistema.

3.4 Formato de retorno comum

Todas as interfaces retornam uniformemente a seguinte estrutura,data o conteúdo varia de acordo com a interface:
{ "code": 0, "message": "Success", "requestId": "0226bf438ffc44a8bbacc7718360719c", "timestamp": 1788857887, "data": {} }

3.5 Lógica de permissão de dados

A interface e as ferramentas MCP devolvem os dados dentro do escopo da autoridade de conta à qual o certificado pertence ; os dados visíveis do certificado de subconta seguem a permissão da subconta. Quando os dados não puderem ser consultados, confirme que o armazém / SKU / pedido de destino pertence à conta de login atual.

3.6 Log de Chamadas e Auditoria

Cada solicitação retorna um requestId exclusivo. Em caso de exceção, entre em contato com o suporte técnico informando o requestId e o horário da solicitação para que o problema seja localizado rapidamente.

4. Interface OpenAPI

4.1 Módulo de Estoque

4.1.1 Consultar lista de armazéns

Introdução do serviço：Consulta todos os cadastros de armazéns da conta atual (nome, tipo, país e cidade, endereço, se é o armazém padrão etc.), com retorno único e sem paginação. Recomenda-se como a primeira etapa da integração: primeiro obtenha o ID do armazém e depois chame a interface "Consulta paginada de lista de estoque do armazém".

Endereço da interface：POST https://openapi.upseller.com/erp/inventory/getWarehouseList/v1

Parâmetros de entrada da solicitação:

Parâmetros de saída de retorno：

Exemplo de solicitação：

curl -X POST "https://openapi.upseller.com/erp/inventory/getWarehouseList/v1" \ -H "Content-Type: application/json" \ -H "X-Upseller-Client-Id: {{YOUR_CLIENT_ID}}" \ -H "X-Upseller-Api-Token: {{YOUR_API_TOKEN}}" \ -H "X-Upseller-Language: cn" \ -d '{ "warehouseType": "ALL" }'

Exemplo de retorno bem-sucedido：

{ "code": 0, "message": "Success", "requestId": "ddff4c98f6454a8da47dc1515361dacc", "timestamp": 1788832087, "data": [ { "warehouseId": "1168231147088", "puid": 17, "warehouseName": "Armazém Próprio-WHS-001", "warehouseType": "SELF_OPERATED", "isDefault": false, "serviceId": null, "serviceAuthName": null, "country": "BR", "city": "2", "address": "", "createTime": "2023-02-15T15:32:45.049+00:00", "updateTime": "2026-08-31T10:07:34.948+00:00", "providerName": null, "providerType": null, "3plWarehouseCode": null, "3plWarehouseName": null, "province": "2", "postCode": "2" }, { "warehouseId": "1168231147866", "puid": 17, "warehouseName": "SBL-WHS-001", "warehouseType": "SELF_OPERATED", "isDefault": true, "serviceId": null, "serviceAuthName": null, "country": "BR", "city": "SBL", "address": "test321313123123", "createTime": "2023-02-21T19:35:15.532+00:00", "updateTime": "2026-08-31T10:07:34.945+00:00", "providerName": null, "providerType": null, "3plWarehouseCode": null, "3plWarehouseName": null, "province": "test213", "postCode": "test123''" } ] }

4.1.2 Consulta paginada da lista de estoque do armazém

Introdução ao Negócio：Consultar a lista de inventário por página com base no armazém (podendo ser filtrada por SKU e horário de atualização), e retornar as quantidades em estoque, já alocadas, disponíveis e em trânsito (compra / transferência) de cada SKU, bem como as informações de estoque de segurança e custo.

Endereço da interface：POST https://openapi.upseller.com/erp/inventory/pageWarehouseSku/v1

Parâmetros de entrada da solicitação：

Parâmetros de saída de retorno：

Exemplo de solicitação：
# 首页请求：不携带 pageNo curl -X POST "https://openapi.upseller.com/erp/inventory/pageWarehouseSku/v1" \ -H "Content-Type: application/json" \ -H "X-Upseller-Client-Id: {{YOUR_CLIENT_ID}}" \ -H "X-Upseller-Api-Token: {{YOUR_API_TOKEN}}" \ -H "X-Upseller-Language: cn" \ -d '{ "warehouseIdList": ["1168231147046"], "skuList": ["PORTA-MAQUIAGEM-G"], "pageSize": 50 }'

Exemplo de retorno bem-sucedido (excerto, dados anonimizados):
{ "code": 0, "message": "Success", "requestId": "0226bf438ffc44a8bbacc7718360719c", "timestamp": 1788857887, "data": { "skuList": [ { "id": 10514289163511, "warehouseId": 10514079940622, "warehouseName": "São Paulo", "warehouseType": "self", "isGroup": 0, "skuId": 10514289163510, "sku": "li6787654321", "skuType": "SKU", "skuTitle": "li4356789087654323245", "imgUrl": "", "categoryId": null, "categoryName": null, "minStock": 11, "maxStock": 400, "isMinStock": false, "unitCost": 435435, "subTotal": 43543064565, "createTime": 1788489976, "updateTime": 1788531616, "up_info": { "onHand": 99999, "allocated": 0, "available": 99999, "inTransit": 0, "inTransitPurchase": 0, "inTransitTransfer": 0 }, "3pl_info": null }, { "id": 10514288996805, "warehouseId": 10514079940622, "warehouseName": "São Paulo", "warehouseType": "self", "isGroup": 0, "skuId": 10514288996804, "sku": "PORTA-MAQUIAGEM-G", "skuType": "SKU", "skuTitle": "PORTA-MAQUIAGEM", "imgUrl": "", "categoryId": null, "categoryName": null, "minStock": 11, "maxStock": 400, "isMinStock": false, "unitCost": 30, "subTotal": 0, "createTime": 1788461185, "updateTime": 1788461185, "up_info": { "onHand": 0, "allocated": 0, "available": 0, "inTransit": 0, "inTransitPurchase": 0, "inTransitTransfer": 0 }, "3pl_info": null } ], "nextPageNo": "v3.v1.S65DI_wD8s_UME9p.wWWTHFsF59YcAkpapvgo_AyoXmof_l1j2yAOclVb4t5qngxwFnzFrZwb2cGC3FxDdLaE-4sihAmIsYFlimVcClv54i_yHycCoEhkhd0r0-LXAruGkvbSuL1gBH_quE7LVdRxHk_S9SEIt74RRd13FIHCZMSYLDzzMkyRMS4fApFjz4v2fEnJ5sggZe6cPhkSR8Xb0WsXnTRQv106iO5M0oTjhDWvyLjmpvSyY6PBa2ckOPUpwUgHElnexcIYD7SQo6KVtVSazmd1KMSpOcU", "hasMore": true, "totalCount": 7065 } }

4.2 Módulo de Pedidos

4.2.1 Obter a lista de lojas manuais

Perfil do Negócio：Consulta a lista de lojas de pedidos manuais (platform=physical) disponíveis sob a conta autenticada atual.

Endereço da interface：POST https://openapi.upseller.com/erp/orders/getPhysicalStoreList/v1

Parâmetros de entrada da solicitação: Sem parâmetros

Parâmetros de saída de retorno：

Exemplo de solicitação：
curl --location --request POST 'https://openapi.upseller.com/erp/orders/getPhysicalStoreList/v1' \ --header 'X-Upseller-Api-Token: *****' \ --header 'X-Upseller-Client-Id: ***' \ --header 'X-Upseller-Language: cn' \ --data ''

Exemplo de retorno bem-sucedido：
{ "code": 0, "message": "Success", "requestId": "e*************1", "timestamp": 1793880342, "data": [ { "store_name": "Test", "store_id": "8******4", "site": "BR" } ] }

4.2.2 Obter lista de pedidos manuais

Descrição do serviço：Consulta paginada da lista de pedidos manuais, com suporte apenas a pedidos recentes, não sendo compatível com pedidos históricos. Todos os parâmetros podem ser omitidos.

Endereço da interface：POST https://openapi.upseller.com/erp/orders/getManualOrderList/v1

Parâmetros de entrada da solicitação:

Parâmetros de saída de retorno：

Exemplo de solicitação：
curl -X POST 'https://openapi.upseller.com/erp/orders/getManualOrderList/v1' \ --header 'X-Upseller-Api-Token: ' \ --header 'X-Upseller-Client-Id: ' \ --header 'X-Upseller-Language: cn' \ --header 'Content-Type: application/json' \ --data '{}'

Exemplo de retorno bem-sucedido：
{ "code": 0, "message": "Success", "requestId": "d*****************7", "timestamp": 1793880601, "data": { "page_number": 1, "page_size": 10, "total": 1088, "has_more": true, "order_list": [ { "order_id": "UP*******2", "store_id": "5***4", "ordered_time": 1793879382, "create_time": 1793879406, "site": "BR", "order_status": 1 }, { "order_id": "UP*******5", "store_id": "9***6", "ordered_time": 1793865702, "create_time": 1793865702, "site": "BR", "order_status": 2 }, { "order_id": "UP*******3", "store_id": "5***4", "ordered_time": 1793859949, "create_time": 1793859949, "site": "BR", "order_status": 3 }, { "order_id": "UP*******8", "store_id": "5***1", "ordered_time": 1793781243, "create_time": 1793781277, "site": "PE", "order_status": 3 }, { "order_id": "UP*******3", "store_id": "7***3", "ordered_time": 1793714644, "create_time": 1793714645, "site": "BR", "order_status": 3 }, { "order_id": "UP*******2", "store_id": "5***4", "ordered_time": 1793714151, "create_time": 1793714330, "site": "BR", "order_status": 4 }, { "order_id": "UP*******0", "store_id": "2***3", "ordered_time": 1793168750, "create_time": 1793616843, "site": "BR", "order_status": 3 }, { "order_id": "UP*******1", "store_id": "2***3", "ordered_time": 1793168750, "create_time": 1793611665, "site": "BR", "order_status": 3 }, { "order_id": "UP*******0", "store_id": "2***3", "ordered_time": 1793168750, "create_time": 1793611589, "site": "BR", "order_status": 3 }, { "order_id": "UP*******7", "store_id": "2***3", "ordered_time": 1793168750, "create_time": 1793602694, "site": "BR", "order_status": 3 } ] } }

4.2.3 Obter detalhes do pedido manual

Introdução do serviço：Consulta os detalhes de um pedido manual individual pelo número de pedido UP, e retorna informações sobre o pedido, o destinatário, o produto, a logística e o pagamento.

Endereço da interface：POST https://openapi.upseller.com/erp/orders/getManualOrderDetail/v1

Parâmetros de entrada da solicitação:

Parâmetros de saída de retorno：

Exemplo de solicitação：
curl -X POST 'https://openapi.upseller.com/erp/orders/getManualOrderList/v1' \ --header 'X-Upseller-Api-Token: ****' \ --header 'X-Upseller-Client-Id: *****' \ --header 'X-Upseller-Language: cn' \ --header 'Content-Type: application/json' \ --data '{ "order_id":"UP4*******5" }'

Exemplo de retorno bem-sucedido：
{ "code": 0, "message": "Success", "requestId": "5****************9", "timestamp": 1793882389, "data": { "order_info": { "store_name": "****", "store_id": "****", "order_id": "****", "store_order_id": "****", "ordered_time": 1793601691, "create_time": 1793601691, "notes": null, "site": "BR", "order_status": 4, "voided": false, "warehouse_id": "****", "ind_final": 1 }, "recipient_info": { "recipient_name": "****", "phone": "****", "tax_num": "****", "company_name": "****", "ie": "****", "invoice_required": true, "invoice_type": 1, "cep": "****", "address_info": { "address1": "****", "address2": "****", "number": "****", "district": "****", "city": "****", "state": "****" } }, "product_list": [ { "sku": "98735465877765453HJW-White-M", "title": "98735465877765453HJW", "img_url": "", "quantity": 1, "currency": "BRL", "unit_price": 68.19 } ], "shipping_info": { "shipping_cost_method": 2, "package_species": null, "package_number": null, "shipping_method": "[Envia BR] correios pac", "tracking_number": null, "package_qty": 1, "weight": null, "dimension": null, "invoice_carrier_details": { "carrier_tax_number": "****", "carrier_name": "****", "carrier_ie": "****", "carrier_address": "****", "carrier_city": "****", "carrier_state": "****" } }, "payment_info": { "payment_method": 1, "payment_method_other": null, "buyer_shipping_cost": 10.0, "seller_shipping_cost": 0.0, "discount": 20.0, "product_price_total": 68.19, "currency": "BRL" } } }

4.2.4 Criar pedido manual

Descrição do serviço：Cria um pedido manual (apenas um pedido por chamada).

Endereço da interface：POST https://openapi.upseller.com/erp/orders/createManualOrder/v1

Parâmetros de entrada da solicitação:

Parâmetros de saída de retorno：

Exemplo de solicitação：
curl --location 'https://openapi.upseller.com/erp/orders/createManualOrder/v1' \ --header 'X-Upseller-Api-Token: ****' \ --header 'X-Upseller-Client-Id: ****' \ --header 'X-Upseller-Language: cn' \ --header 'Content-Type: application/json' \ --data '{ "order_info": { "store_id": "****", "store_order_id": "****", "ordered_time": 1793168750, "notes": "****", "warehouse_id": "****", "ind_final": 1 }, "recipient_info": { "recipient_name": "****", "phone": "****", "tax_type": "cnpj", "tax_num": "****", "company_name": "****", "ie": "****", "invoice_required": true, "invoice_type": 1, "cep": "****", "address_info": { "address1": "****", "address2": "****", "number": "****", "district": "****", "city": "****", "state": "****" } }, "product_list": [ { "sku": "****", "quantity": 1, "unit_price": 333, "currency": "BRL" } ], "shipping_info": { "shipping_cost_method": 2, "package_qty": 1, "weight": { "gross_weight": 33 }, "dimension": { "length": 6, "width": 5, "height": 4 }, "invoice_carrier_details": { "carrier_tax_type": "cnpj", "carrier_tax_number": "****", "carrier_name": "****", "carrier_ie": "****", "carrier_address": "****", "carrier_city": "****", "carrier_state": "****" } }, "payment_info": { "payment_method": 1, "buyer_shipping_cost": 10.0, "seller_shipping_cost": 10.0, "discount": 20.0 } }'

Exemplo de retorno bem-sucedido：
{ "code": 0, "message": "Success", "requestId": "88*********************7d", "timestamp": 1793883429, "data": { "order_id": "UP******4", "store_id": "2*****3" } }

5. Utilização da ferramenta MCP

5.1 Integração de cada IA com a ferramenta MCP

Preparativos gerais antes da integração:
Independentemente da ferramenta utilizada, é necessário preparar previamente o MCP TOKEN (para detalhes, consulte a seção 3.2 - Métodos de Autenticação - Gerar Token):

5.1.1 Cursor

Ponto de entrada da interface gráfica: Abra o Cursor

Clique em Customize

Clique em MCPS --> Clique em Novo Servidor MCP

Copie o conteúdo a seguir para mcp.json

Aplicação global:~/.cursor/mcp.json
Apenas o projeto atual: diretório raiz do projeto .cursor/mcp.json

{ "mcpServers": { "upseller": { "url": "https://openapi.upseller.com/mcp", "headers": { "Authorization": "Bearer {YOUR_MCP_TOKEN}", "X-Upseller-Language": "cn" } } } }

Clique em Salvar e verifique se o serviço UpSeller MCP foi adicionado

5.1.2 Claude

Método 1: Adicionar diretamente na linha de comando
claude mcp add --transport http UpSeller https://openapi.upseller.com/mcp --header "Authorization: Bearer {YOUR_MCP_TOKEN}" --header "X-Upseller-Language: cn" --header "Accept: application/json, text/event-stream"

Método 2 No arquivo .claude.json no diretório inicial do usuário (para configuração de nível de projeto, pode-se usar o arquivo .mcp.json no diretório raiz do projeto)
{ "mcpServers": { "upseller": { "type": "http", "url": "https://openapi.upseller.com/mcp", "headers": { "Authorization": "Bearer {YOUR_MCP_TOKEN}", "X-Upseller-Language": "cn", "Accept": "application/json,text/event-stream" } } } }

5.1.3 Codex

Clique em Plugins para acessar o mercado de plugins

Clique em Definições para aceder aos MCPs

Clique em Adicionar Servidor

Selecione o tipo HTTP

Preencha as informações correspondentes

Name: Upseller-MCP Type: HTTP URL: https://openapi.upseller.com/mcp Headers: Bearer令牌环境变量: {YOUR_MCP_TOKEN} X-Upseller-Language: "cn"（Tipo de idioma, opcional`cn` `en` `es` `pt`）

5.1.4 Verificação de Conectividade (MCP Inspector)

Após a conclusão da configuração, você pode usar o MCP Inspector para uma verificação rápida:

Adicionar Servidor

Configurações — Cabeçalhos personalizados

Servidor Mcp Conectado

Ferramentas

Executar ferramenta [get_warehouse_list_by_puid]

Executar ferramenta Resultados [get_warehouse_list_by_puid]

Executar ferramenta [page_warehouse_sku_inventory_list]

Executar ferramenta Resultados [page_warehouse_sku_inventory_list]

5.2 Lista de ferramentas MCP

5.2.1 Ferramentas de Inventário

5.2.1.1 Consulta de lista de armazéns (get_warehouse_list_by_puid)

Descrição da capacidade de negócio：Com uma única consulta, você pode visualizar todos os armazéns da sua conta: nome, tipo (próprio / terceiro), país e cidade onde se localizam, endereço e se é o armazém padrão. Geralmente é o primeiro passo para consultar o estoque — primeiro obtenha o ID do armazém e depois consulte o estoque por esse ID.

Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Quais armazéns estão vinculados à minha conta? E quais deles são armazéns próprios?"
2. “Verifique a minha lista de armazéns terceirizados, incluindo as informações dos prestadores de serviços.”
3. "Qual armazém padrão eu configurei? Onde ele está?"
4. (inglês)"Liste meus armazéns no Brasil."
Descrição de restrição : somente leitura, somente consulta arquivos de armazém, não retorne a quantidade de estoque (verifique o inventário, use "consulta de SKU de inventário"); somente retorne o armazém sob a conta de certificado atual; retorne a lista completa de uma só vez, sem paginação.

5.2.1.2 Consulta de SKU de estoque (page_warehouse_sku_inventory_list)

Descrição da capacidade de negócio：Consultar o inventário com uma única frase — especifique um ou vários armazéns para visualizar as quantidades em stock, alocadas, disponíveis e em trânsito (compras / transferências) de cada SKU, bem como os limites superior e inferior de stock de segurança e o custo. Adequado para responder a perguntas como "quantas unidades restam de um determinado SKU" e "quais produtos neste armazém estão prestes a ficar sem stock".

Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Por favor, verifique para mim o estoque disponível restante do SKU PORTA-MAQUIAGEM-G no armazém de São Paulo?"
2. "Quais SKUs no armazém 1168231147046 já acionaram o alerta de estoque baixo?"
3. "Liste os 50 primeiros itens da lista de estoque do armazém no Brasil e marque a quantidade em trânsito."
4. "Consultar o estoque do SKU PORTA-MAQUIAGEM-G no armazém de São Paulo."
Restrições: Somente leitura, não é possível modificar estoque, entrada de mercadorias ou transferência; Limite de filtragem por chamada: 100 armazéns, 300 SKUs, 100 registros por página; Alguns campos do SKU de kits (KIT) podem estar vazios; O escopo dos dados retornados segue as permissões da conta à qual o documento pertence.

5.2.2 Ferramentas de Pedidos

5.2.2.1 Consulta de lista de pedidos manuais (get_manual_order_list)

Descrição da capacidade de negócio：Visualiza a lista de pedidos manuais da sua conta e retorna os resumos dos pedidos paginados em ordem decronológica. É adequado para consultas diárias como "quais pedidos foram registrados recentemente" e "quantos pedidos manuais existem atualmente".
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Liste meus 10 pedidos artesanais mais recentes."
2. “Qual é o pedido manual criado mais recentemente?”
3. "Continue a ver os pedidos manuais na página seguinte."
Descrição da restrição : somente leitura; somente devolução de ordens manuais dentro da autoridade de conta corrente; a lista é um campo de resumo, peça detalhes da ordem para ver as informações completas de uma única transação.

5.2.2.2 Consulta de detalhes de pedido manual (get_manual_order_detail)

Descrição da capacidade comercial：Consultar os detalhes de um pedido manual associado à conta atual pelo número de pedido UP, incluindo informações do pedido, destinatário, produtos, logística e pagamento. É adequado para verificar o status do pedido, o número de pedido da loja, as informações de recebimento e envio, bem como todos os valores; caso não saiba o número de pedido UP, pode obtê-lo primeiro através da função "Consultar lista de pedidos manuais".
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. “Veja os detalhes do pedido UPxxxxxx.”
2. “Por favor, confira o status e o valor deste pedido.” (continua a perguntar com base nos resultados da consulta da lista)
3. “Verifique o endereço do destinatário, os detalhes do produto e o número de rastreio do UPxxxxxx.”
4. (inglês)“Mostre os detalhes do pedido manual UPxxxxxx.”
Descrição das restrições: Somente leitura, apenas uma ordem manual pode ser consultada de cada vez, e a consulta de paginação ou lote não é suportada; número de ordem UP deve ser fornecido, e o número de ordem da loja não pode ser usado diretamente para perguntar, e o número da ordem não deve ser adivinhado; somente ordens manuais sob a conta certificada atual são retornadas e "ordem manual não encontrada" é retornada quando a ordem não existe. anulado = true indica que a ordem foi colocada em espera e o order _ status é o status do processo antes da prateleira; o método de pagamento e o status da ordem são retornados em código digital e todos os campos de tempo são segundos Unix (UTC).Campos como o número da ordem da loja, armazém, facturação, etc. poderão estar vazios devido à situação real da ordem; quando a consulta expirar ou falhar, deverá ser explicada de forma verdadeira, poderá tentar de novo, e os dados da ordem não deverão ser fabricados. Não é necessário chamar a interface de detalhes um por um para os resultados da consulta da lista, e esta só é usada quando o utilizador necessita de ver os detalhes da ordem indicados.

5.2.2.3 Verificação prévia da criação de pedido manual（preview_manual_order）

Descrição da capacidade de negócio：Antes de criar formalmente um pedido manual, realizaremos uma verificação completa e um cálculo experimental do valor com base nas informações que você fornecer verbalmente (sem gerar pedidos nem dados), para ajudar você a confirmar se as informações estão completas e se o valor está correto. Mesmo que as informações estejam incompletas, você pode acionar essa função, que retornará de uma só vez todos os campos ausentes ou incorretos e guiará você para preenchê-los; somente após a pré-verificação ser aprovada e você confirmar, a IA criará o pedido formalmente.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. “Faça uma pré-verificação para mim de um pedido manual: Loja BR, SKU li6787654321, quantidade 2, preço unitário 50,00.”
2. “Pré-visualize um pedido para a 'Loja de Teste de Pedidos Manuais': 1 unidade do SKU A123 a 99,9, frete do comprador de 10, pagamento via PIX.”
3. (inglês)“Visualizar um pedido manual para minha loja no Brasil: SKU li6787654321, quantidade 2, preço unitário 50,00.”
Restrições e Esclarecimentos：

Modo somente leitura: apenas verifica sem criar; após a aprovação da pré-verificação e a sua confirmação, a IA irá criar o pedido oficialmente.
A loja, o armazém e o SKU devem ser reais; a IA não adivinhará o ID da loja nem decidirá por você informações comerciais como emissão de nota fiscal e métodos de pagamento.

5.2.2.4 Criação manual de pedidos (create_manual_order)

Descrição da capacidade de negócio：Cria um pedido manual por meio de interação, sendo que cada chamada cria apenas um pedido. Antes da criação, é obrigatório realizar a validação completa de campos e o cálculo experimental de valores por meio da interface "Pré-verificação de criação de pedido manual (preview_manual_order)"; o pedido só será efetivamente registrado após a IA repetir o resultado do cálculo experimental e você confirmar expressamente; após a conclusão bem-sucedida, será retornado o número do pedido do sistema (número UP).
Âmbito de competências:

Exemplos de perguntas recomendadas：
1. "Criar pedido manual: SKU PORTA-MAQUIAGEM-G, quantidade 1, preço unitário 30, utilize o que acabou de ser aprovado na verificação."
2. "Confirme a criação, utilize o número de loja xxxxxxxx e coloque a observação 'retirada na loja'."
3. "Confirma a criação do pedido manual que acabei de revisar."
Restrições e Esclarecimentos：

Operação de gravação: serão gerados dados de pedidos reais. É necessário primeiro confirmar que as informações estão corretas por meio da "Verificação prévia para criação manual de pedidos", e executar a criação somente após a confirmação por repetição da IA; os parâmetros de entrada para criação devem ser exatamente iguais aos da verificação prévia aprovada, e qualquer alteração exige uma nova verificação prévia;
Cada chamada cria apenas um pedido, não há suporte para operações em lote;
Limite de frequência de chamada: 1 pedido por segundo por conta, 50 pedidos por hora e 1000 pedidos por dia; a ultrapassagem do limite resultará no retorno de um erro de limitação de tráfego;
O SKU deve já existir na base de dados de produtos e não pode ser repetido no mesmo pedido; o número de referência da loja é exclusivo por loja, e a duplicação resultará em falha na criação;
Após a criação do pedido, não é possível modificá-lo através desta ferramenta; proceda ao processamento no painel de administração do UpSeller;

5.2.3 Ferramentas de categoria de dados

5.2.3.1 Consultar desempenho de vendas por data (page_sales_performance_by_date)

Descrição da capacidade comercial：Visualize o desempenho de vendas da conta atual por data, com uma linha retornada para cada data, sendo adequado para analisar o número de pedidos, o valor de vendas, os pedidos válidos, o valor de vendas válido, os pedidos cancelados, o valor de vendas cancelado, o número de clientes e o valor médio por cliente por dia durante um determinado período.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Consulte o desempenho de vendas diário dos últimos 7 dias."
2. "Veja o número de pedidos, o valor das vendas e o valor médio por cliente de 1º de outubro de 2026 a 7 de outubro de 2026."
3. "Consultar o valor de vendas válido da plataforma brasileira e das lojas especificadas nos últimos 7 dias."
Observações sobre restrições：Somente leitura; o intervalo de datas não deve exceder 7 dias consecutivos; os valores correspondem aos montantes na moeda original, ao somar valores em múltiplas moedas os montantes são somados diretamente, e o campo de moeda retornado não representa a moeda unificada do valor total; não são retornados dados de comparação anual, comparação mensal e estoque, nem é utilizado para consultas por loja, produto ou depósito.

5.2.3.2 Consultar desempenho de vendas por loja (page_sales_performance_by_shop)

Descrição da capacidade comercial：Visualiza o desempenho de vendas da conta atual por página de loja, utilizado para comparar o número de pedidos, o valor de vendas, o valor de vendas efetivo, o valor de cancelamento, o número de clientes e o valor médio por cliente de cada loja no intervalo de datas especificado.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Visualize as vendas dos últimos 7 dias por loja, classificadas da maior para a menor."
2. "Liste os pedidos válidos e o valor médio por cliente de todas as lojas entre 1 de outubro de 2026 e 7 de outubro de 2026."
3. "Verifique o número de pedidos cancelados de todas as lojas na plataforma do Brasil nos últimos 7 dias."
Observações sobre restrições：Somente leitura; o intervalo de datas não deve exceder 7 dias consecutivos; os IDs de loja devem pertencer à conta atual, com um máximo de 100; quando nenhuma loja for especificada, a consulta será feita para todas as lojas da conta atual; os valores são expressos na moeda original, e ao somar valores de múltiplas moedas, eles são adicionados diretamente; não são retornados dados de comparação anual, comparação mensal nem de estoque, e também não é possível realizar consultas por data, produto ou armazém.

5.2.3.3 Consultar vendas por produto (page_product_sales_by_product)

Descrição da capacidade de negócio：Visualiza as vendas da conta atual no intervalo de datas especificado, paginadas por produto, e retorna informações como loja, plataforma, produto, SKU, pedidos e valor de vendas, sendo adequado para analisar quais produtos têm melhor desempenho de vendas.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Consulte as vendas e a receita de cada produto nos últimos 7 dias, ordenados por volume de vendas em ordem decrescente."
2. "Verifique quantas unidades do produto com SKU ABC123 foram vendidas nos últimos 7 dias."
3. "Visualize os 20 produtos com maior volume de vendas nos últimos 7 dias da loja especificada."
Descrição de restrição : somente leitura; a data deve estar dentro de um intervalo de não mais de 7 dias consecutivos; ID do produto, correspondência exata de vários valores do SKU desduplicar até 100, texto de pesquisa cadeia inteira até 512 caracteres; padrão 20 por página, até 50; quantias de várias moedas são adicionadas diretamente e o preço médio é retornado de acordo com o resultado da consulta; ano a ano, mês a mês e estoque não são retornados e não são usados para resumir por variante ou por SKU.

5.2.3.4 Consultar vendas por variação (page_product_sales_by_variation)

Descrição da capacidade de negócio：Visualiza as vendas da conta atual no intervalo de datas especificado, paginadas por variante. Além das informações do produto, também retorna o ID da variante, o SKU da variante, os atributos da variante e o SKU pai, sendo adequado para analisar as vendas de especificações ou cores específicas.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Consultar as vendas de todas as variantes nos últimos 7 dias, ordenadas por volume de vendas em ordem decrescente."
2. "Verifique a situação de vendas dos SKUs de todas as variantes do produto ABC nos últimos 7 dias."
3. "Consulte o volume de vendas e a receita do SKU de variante ABC123-Red."
Observações sobre restrições：Somente leitura; o intervalo de datas não deve exceder 7 dias consecutivos; após a correspondência exata e a remoção de duplicatas de valores múltiplos, no máximo 100 itens, e o texto de pesquisa completo não deve ultrapassar 512 caracteres; o padrão é 20 itens por página, com um máximo de 50 itens; não retorna dados de comparação anual, comparação mensal e estoque, e não se aplica à agregação apenas por produto ou apenas por SKU.

5.2.3.5 Consultar vendas por SKU do produto (page_product_sales_by_product_sku)

Descrição da capacidade comercial: Consulta as vendas da conta atual no intervalo de datas especificado, agregadas por SKU do produto, e retorna o nome do SKU, imagem, pedidos válidos, valor de vendas e preço médio, sendo adequado para comparar rapidamente o desempenho de vendas a partir da dimensão do SKU do produto.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Consulte o volume de vendas, o valor de vendas e o preço médio do SKU de produto ABC123 nos últimos 7 dias."
2. "Consulte em lote o desempenho de vendas dos SKUs ABC123 e DEF456 nos últimos 7 dias."
3. "Identifique os SKUs dos produtos com as maiores vendas nos últimos 7 dias."
Descrição das restrições: somente leitura; o intervalo de datas não deve exceder 7 dias consecutivos; não é possível transmitir simultaneamente um SKU difuso e vários SKUs exatos, e o número máximo de SKUs após a remoção de duplicatas é 100; o comprimento do texto de pesquisa e o número de itens por página estão sujeitos às restrições da ferramenta, com padrão de 20 itens por página e máximo de 50 itens; quando o mesmo SKU abrange várias lojas, não é retornada uma única loja; não são retornados dados de comparação anual, comparação mensal e estoque, e não é utilizado para consultas por SKU de variante.

5.2.3.6 Consultar vendas por SKU de variação (page_product_sales_by_variation_sku)

Descrição da capacidade comercial：Consolida e consulta o volume de vendas da conta atual no intervalo de datas especificado por variante de SKU, e retorna o nome da variante de SKU, a imagem, os pedidos válidos, o valor de vendas e o preço médio, sendo adequado para comparar o desempenho de vendas a partir da dimensão de variante de SKU.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Consulte as vendas e o valor de vendas da variante de SKU ABC123-Red nos últimos 7 dias."
2. "Consulte em lote o desempenho de vendas das variantes de SKU ABC123-Red e DEF456-Blue nos últimos 7 dias."
3. "Ver os produtos com maior volume de vendas nos últimos 7 dias, classificados por variante de SKU."
Observações sobre restrições：Somente leitura; o intervalo de datas não deve exceder 7 dias consecutivos; não é possível transmitir simultaneamente um SKU difuso e vários SKUs exatos, e o número máximo de SKUs após a remoção de duplicatas é 100; o padrão é 20 itens por página, com um máximo de 50 itens; quando o mesmo SKU variante abrange várias lojas, não é retornada uma única loja; não são retornados dados de comparação anual, comparação mensal e estoque, e não é utilizado para consultas por SKU de produto.

5.2.3.7 Consultar vendas de produtos (page_warehouse_sales)

Descrição de competências operacionais：Consultar as vendas da conta atual por página com base na dimensão dos produtos do armazém, suportar a visualização de todos os produtos, produtos novos ou produtos mais vendidos, e devolver armazém, SKU, SPU, título, imagem, volume de vendas, número de encomendas, valor de vendas e data de colocação à venda.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Consulte as vendas de produtos em todos os armazéns nos últimos 7 dias e ordene-as por volume de vendas, do maior para o menor."
2. "Ver as vendas de produtos novos lançados nos últimos 30 dias."
3. "Identifique os produtos com as maiores vendas e exiba o armazém, o SKU e o valor das vendas."
Descrição das restrições : Somente leitura; Tipo 4 não é usado para esta ferramenta para perguntar sobre mercadorias não vendáveis, use "Consultar mercadorias não vendáveis"; até 100 cada após o armazém e ID da categoria desduplicar e deve pertencer à conta corrente; texto de pesquisa até 512 caracteres; padrão 20 por página, até 50; não retornar moeda, ano a ano, mês a mês e inventário; análise de classificação em tempo real pela propriedade atual do SKU.

5.2.3.8 Consultar produtos com vendas estagnadas (page_warehouse_unsold_sales)

Descrição de capacidade de negócio：Consultar produtos estagnados por dimensão de mercadorias no armazém, com suporte para seleção de janela de tempo de estagnação e limite superior de vendas, ajudando a localizar rapidamente SKUs que estão em exposição há muito tempo mas com vendas baixas recentemente.
Âmbito de competências：

Exemplos de perguntas recomendadas：
1. "Ver os produtos com venda parada há 30 dias, ordenados por número de dias sem venda em ordem decrescente."
2. "Identifique os SKU de baixa rotatividade com vendas não superiores a 2 unidades nos últimos 60 dias."
3. "Verifique os produtos que estão parados há 90 dias no armazém especificado."
Observações sobre restrições：Somente leitura; não utiliza intervalo de datas, e as datas de início ou fim informadas serão ignoradas; o período padrão de produtos estagnados é de 30 dias; o armazém e a categoria devem pertencer à conta atual; o padrão é 20 itens por página, com no máximo 50 itens; não retorna moeda, taxa de comparação anual, taxa de comparação mensal e estoque; se precisar consultar as vendas de produtos por intervalo de datas, utilize a função "Consultar Vendas de Produtos".

6. Relatório de erros e autodiagnóstico

6.1 Tabela de códigos de erro comuns

6.2 Perguntas frequentes sobre o OpenAPI

1. O que fazer quando a autenticação falhar (código 4003)? Verifique sequencialmente se os dois cabeçalhos de solicitação obrigatórios (X-Upseller-Client-Id / X-Upseller-Api-Token) estão presentes, se seus valores estão corretos e se o Token foi redefinido sem que a configuração correspondente fosse atualizada.
2. Como obter dados completos por paginação? A interface de lista de estoque usa paginação por cursor: na página inicial não é necessário enviar pageNo, depois disso passe o valor de nextPageNo da resposta exatamente como está, até que hasMore=false. Não calcule os números de página por conta própria, nem busque o volume completo com alta frequência.
3. Falhas ocasionais / instabilidade na rede? Implemente tentativas de retorno moderadas (como o recuo exponencial); quando erros do servidor (5000) ocorrerem continuamente, forneça o requestId ao suporte técnico para feedback.
4. Como analisar os campos de tempo? A lista de repositórios utiliza cadeias de caracteres no formato ISO 8601, enquanto o inventário e o horário do pedido usam carimbos de data/hora em segundos; processe-os separadamente.

6.3 Perguntas frequentes sobre o MCP

1. Não é possível conectar：verifique se a URL é https://openapi.upseller.com/mcp, se o tipo de transporte selecionado é Streamable HTTP e se o Authorization está usando o MCP Token (e não o API Token).
2. Consegue conectar mas não consegue detectar a ferramenta：Confirme que o pacote da conta atende aos requisitos de ativação (versão profissional ou superior / Kit) e que você clicou em "Gerar" no painel para concluir a ativação; reinicie o cliente e recarregue a lista de ferramentas.
3. Após a consulta, nenhum dado foi encontrado：primeiro confirme se o armazém / SKU / pedido pertence às permissões da conta atual, depois verifique se os critérios de filtro estão muito restritos (por exemplo, erro de digitação no código do SKU, ID do armazém incorreto); você pode começar perguntando "quais armazéns eu tenho" para verificar o escopo visível.
4. Erro na chamada：geralmente ocorre quando os critérios de filtro excedem os limites (mais de 100 armazéns, mais de 300 SKUs, mais de 100 itens por página). Reduza o escopo e faça consultas em lotes; para cenários complexos, use o MCP Inspector para conexão direta e identifique se o problema está nas credenciais ou nos dados.

7. Normas de segurança e isenção de responsabilidade

Normas de Segurança

Token (Token de API / Token MCP) equivale às suas credenciais de acesso a dados: é estritamente proibido compartilhá-lo com terceiros, inseri-lo em páginas de front-end, aplicativos clientes ou repositórios de código públicos;
De acordo com o princípio da "necessidade mínima", utilize credenciais independentes para diferentes sistemas ou subcontas; redefina imediatamente o Token correspondente quando o pessoal sair da empresa ou o sistema for desativado;
Caso seja detectado um vazamento, redefina ou exclua imediatamente em "Plataforma Aberta → API / MCP" e atualize as configurações dos sistemas afetados;
A capacidade de escrita (criação manual de pedidos) é concedida apenas aos colaboradores que realmente necessitam registar pedidos;
O chamador é responsável por todas as chamadas iniciadas pelo seu sistema. Não utilize os recursos abertos para obter dados que excedam as suas permissões nem revenda dados.

Aviso de isenção de responsabilidade

Os dados retornados pelas interfaces e ferramentas têm como referência os dados em tempo real do sistema UpSeller; caso existam divergências de dados causadas por cache ou atrasos de processamento no lado do comerciante, prevalecerão os dados do painel de administração do UpSeller.
As análises e sugestões geradas pelo assistente de IA com base nos resultados da consulta são apenas para referência; verifique manualmente antes de tomar decisões operacionais.
Quaisquer prejuízos decorrentes da divulgação de credenciais por parte do estabelecimento comercial serão da sua exclusiva responsabilidade.

Prévia: [MCP] Guia de configuração do MCP do UpSeller

Prévia:[MCP] Guia de configuração do MCP do UpSeller

Esse conteúdo te ajudou？

Voltar ao topo