Pular para conteúdo

Plataformas suportadas

A Gubee integra com dezenas de marketplaces. Este documento explica como descobrir quais plataformas estão disponíveis, qual a configuração de cada uma e como o roteamento dinâmico funciona para endpoints que aceitam {platform} no path.

Endpoints canônicos

Configuração completa

curl -X GET "$GUBEE_API/integration/platforms/configuration" \
  -H "Authorization: Bearer $JWT"

Retorna List<PlatformConfigurationApiDTO> com todas as plataformas suportadas:

[
  {
    "code": "MERCADOLIVRE",
    "label": "Mercado Livre",
    "logoUrl": "https://cdn.gubee.com.br/logos/ml.png",
    "type": "MARKETPLACE",
    "publishType": ["SIMPLE", "VARIATION"],
    "orderStatus": {
      "CREATED": true,
      "PAID": true,
      "INVOICED": true,
      "SHIPPED": true,
      "DELIVERED": true
    }
  },
  {
    "code": "SHEIN",
    "label": "Shein",
    "logoUrl": "https://cdn.gubee.com.br/logos/shein.png",
    "type": "MARKETPLACE",
    "publishType": ["SIMPLE"],
    "orderStatus": {
      "CREATED": false,
      "PAID": true,
      "INVOICED": true,
      "SHIPPED": true,
      "DELIVERED": true
    }
  }
]

Campos:

Campo Descrição
code Identificador canônico da plataforma (usado em paths {platform}).
label Nome amigável para exibição.
logoUrl URL do logotipo.
type Tipo da plataforma (MARKETPLACE, HUB, etc.).
publishType Modalidades de publicação suportadas (SIMPLE, VARIATION).
orderStatus Mapa indicando quais status de pedido a plataforma suporta.

Blacklist de criação de pedido

Algumas plataformas não suportam criação de pedido (apenas atualizações de status posteriores). Para descobrir quais:

curl -X GET "$GUBEE_API/integration/platforms/blacklist/created" \
  -H "Authorization: Bearer $JWT"

[
  { "name": "SHEIN", "status": "CREATED" },
  { "name": "TIKTOKSHOP", "status": "CREATED" }
]

Para essas plataformas, o pedido é criado diretamente no marketplace e a Gubee apenas recebe a notificação. Tentar chamar POST /integration/orders/create com platform: SHEIN em sandbox falha.

Roteamento dinâmico por {platform}

Muitos endpoints aceitam {platform} como variável de path. O BFF usa o nome da plataforma para resolver dinamicamente a URL do serviço downstream, transformando MERCADOLIVRE em mercadolivreservice:

GET /integration/stocks/all/MERCADOLIVRE/ITEM123
                                 |
                                 v
BFF resolve: <platform.lowercase()>service
                                 |
                                 v
Microservico interno do marketplace MERCADOLIVRE

A resolução é case-insensitive e segue a convenção <platform.lowercase()>service. Internamente, cada marketplace suportado tem uma entrada correspondente na configuração do BFF (nome lógico como mercadolivreservice, b2wservice, shopeeservice, etc.). Você não precisa saber os nomes dos serviços downstream — apenas o code (canônico, em maiúsculas, ex.: MERCADOLIVRE, SHOPEE, AMAZONV2) que aparece nos endpoints públicos.

Lista de marketplaces

A lista abaixo reflete os endpoints configurados em produção. Plataformas marcadas com (v2) indicam uma segunda versão do conector coexistente.

Code Serviço downstream
MERCADOLIVRE mercadolivreservice
B2W (Americanas) b2wservice
SHOPEE shopeeservice
SHEIN sheinservice
AMAZON amazonservice
AMAZONV2 amazonv2service
CNOVA cnovaservice
CARREFOUR carrefourservice
CARREFOURV2 carrefourv2service
MAGAZINELUIZA magazineluizaservice
MAGALU magaluservice
DAFITI / GFG dafitiservice / gfgservice
NETSHOES netshoesservice
CENTAURO centauroservice
ZOOM zoomservice
LOJASCOLOMBO lojascolomboservice
MADEIRAMADEIRA madeiramadeiraservice
MADEIRAMADEIRAV2 madeiramadeirav2service
LEROYMERLIN leroymerlinservice
LEROYMERLINV2 leroymerlinv2service
KABUM kabumservice
VIAVAREJO viavarejoservice
MAGENTO magentoservice
BLING blingservice
ALIEXPRESS aliexpressservice
TEMU temuservice
TIKTOKSHOP tiktokshopservice

A lista canônica é sempre a retornada por GET /integration/platforms/configuration — use-a como fonte de verdade em runtime, não hardcode esta tabela no seu integrador.

Plataformas com sugestão de categoria via IA

Alguns marketplaces não oferecem preditor nativo de categoria. Para esses, a sugestão de categoria é roteada para o serviço de IA (gubee-ai) internamente:

services:
  ai-category-suggest-platforms:
    - MAGALU
    - VIAVAREJO
    - MADEIRAMADEIRAV2
    - KABUM
    - LEROYMERLINV2

Isso é transparente para o integrador: o endpoint de sugestão de categoria continua sendo o mesmo; o BFF decide para onde rotear.

Como usar em código

Descobrir plataformas suportadas pelo seller

const platforms = await fetch(
  `${API}/integration/platforms/configuration`,
  { headers: { Authorization: `Bearer ${jwt}` } }
).then(r => r.json());

const marketplaces = platforms.filter(p => p.type === "MARKETPLACE");
const canCreateOrder = platforms.filter(
  p => p.orderStatus.CREATED === true
);

Verificar se uma plataforma suporta criação de pedido

const blacklist = await fetch(
  `${API}/integration/platforms/blacklist/created`,
  { headers: { Authorization: `Bearer ${jwt}` } }
).then(r => r.json());

const blocked = new Set(blacklist.map(b => b.name));
function canCreateOrder(platform: string): boolean {
  return !blocked.has(platform.toUpperCase());
}

Roteamento para um marketplace específico

# Preço para um anúncio específico no Mercado Livre
curl -X GET "$GUBEE_API/integration/prices/MERCADOLIVRE/ITEM123" \
  -H "Authorization: Bearer $JWT"

# Estoque do mesmo item, todos os warehouses
curl -X GET "$GUBEE_API/integration/stocks/all/MERCADOLIVRE/ITEM123" \
  -H "Authorization: Bearer $JWT"

Considerações

  • Case-insensitive no path: MERCADOLIVRE, mercadolivre e MercadoLivre são equivalentes. Use o code retornado pelo endpoint de configuração para consistência.
  • Plataforma não listada: se {platform} não tem entrada em services.endpoints, o BFF retorna 404 ou 502 dependendo do fallback.
  • Conta precisa estar autorizada: mesmo com a plataforma suportada, o seller precisa ter credenciais válidas cadastradas no painel Gubee para operar. A falta de credencial retorna 403 no downstream.

Próximos passos