Pular para conteúdo

Glossário PT-BR ↔ API

Esta página mapeia os termos usados na interface da Gubee (em português) para as entidades da API. Use como referência ao integrar — quando ler "Etiqueta" no painel, saberá exatamente qual campo buscar no JSON de pedido.

Convenções

  • A coluna API Entity usa o nome do campo/enum em inglês conforme aparece no JSON retornado por /integration/* e /bffweb/*.
  • A coluna Onde aparece indica a superfície e o recurso principal onde o termo é exposto.
  • Termos marcados com (legacy) são herdados de versões anteriores e ainda aparecem em campos antigos; evite usá-los em código novo.

Por que este glossário?

A interface Gubee é 100% em português brasileiro, mas a API expõe entidades em inglês (Padrão REST internacional). Erros de tradução são a fonte #1 de bugs em integrações iniciantes — especialmente Etiqueta, que NÃO é tag.

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Produto Product Entidade de catálogo, marketplace-agnóstica. Fonte da verdade. /integration/products/*
Variação Variation / Sku Unidade vendável de um produto. Tem skuId e sku. product.variations[]
SKU sku (seller) / skuId (Gubee) Identificador da variação. sku é do seller; skuId é nosso. /integration/skus/by-sku
Anúncio Ad Publicação de produto em um marketplace. Identificado por adId. /integration/ads/*
Categoria Category Categoria do produto no marketplace-alvo. product.categories[]
Categoria Gubee InternalCategory Categoria interna (taxonomia Gubee). Mapeada para marketplace. /integration/categories/*
Atributo Attribute Especificação marketplace-specific (Cor, Tamanho, Voltagem). variation.attributes[]
Marca Brand Fabricante do produto. product.brand
EAN / GTIN ean / gtin Código de barras da variação. variation.ean
NBM / NCM nbm / ncm Código fiscal do produto. product.nbm
Tabela de Medidas SizeChart Tabela de medidas obrigatória para moda (ML, Shopee). product.sizeChart
Compatibilidade CompatibilityList Lista de compatibilidade (autopeças, veículos). product.compatibility
Imagem Image Imagem da variação do produto. variation.images[]
Vídeo Video / VideoDTO Vídeo enriquecido via mediaservice. variation.videos[]
Dimensões Dimensions Peso, altura, largura, comprimento, cubagem. product.dimensions

Veja Ad vs Produto e SKU vs SkuId para o modelo de dados completo.

Pedidos

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Pedido Order Pedido recebido de um marketplace. /integration/orders/*
Item de pedido OrderItem Linha de produto dentro do pedido. order.items[]
Status do pedido OrderStatus Enum: CREATED, PAID, INVOICED, SHIPPED, DELIVERED, CANCELED. order.status
Faturar / Faturado INVOICED Ação de emitir nota fiscal; status pós-emissão. POST /integration/orders/invoice/{id}
Despachar / Despacho SHIPPED Ação de expedir; status pós-envio. POST /integration/orders/ship/{id}
Nota Fiscal Invoice Documento fiscal brasileiro (NF-e/NFS-e). order.invoice
Chave de acesso accessKey Chave de 44 dígitos da NF-e. invoice.accessKey
DANFE danfeUrl PDF do DANFE. invoice.danfeUrl
Comprador Buyer Dados do comprador (nome, CPF/CNPJ, contato). order.buyer
Endereço de entrega ShippingAddress Endereço completo para expedição. order.shippingAddress
Comissão totalCommission Comissão cobrada pelo marketplace. order.totalCommission
Total líquido netValue / totalNet Valor repassado ao seller após taxas e comissões. order.netValue
Total bruto totalAmount / grossValue Valor total do pedido. order.totalAmount
Valor do frete freightValue / shippingCost Custo de frete pago pelo comprador. order.freightValue
Rastreamento tracking Código e URL de rastreio da transportadora. order.tracking
Justificativa de cancelamento cancellationReason Motivo do cancelamento (obrigatório em alguns marketplaces). order.cancellationReason
Tag (de pedido) tag Marcador livre aplicado ao pedido pela Gubee ou ERP. order.tags[]

Etiqueta ≠ Tag

Etiqueta (UI) = Shipping Label (API) = order.shippingLabel. É a etiqueta de postagem da transportadora (Correios, Intelipost), em PDF ou ZPL — NÃO é uma tag de classificação. Confundir os dois é o erro mais comum: a tag "de pedido" (order.tags[]) é um marcador textual livre, enquanto a etiqueta é um documento físico para colar na caixa.

Veja o guia Etiquetas para o fluxo de impressão e download de PDF/ZPL.

Estoque

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Estoque Stock Quantidade física por warehouse. /integration/stocks/*
Quantidade qty Saldo físico (inteiro, >= 0). stock.qty
Prioridade priority Ordem do warehouse no rateio (1 = mais prioritário). stock.priority
Centro de Distribuição Warehouse CD físico onde o item está armazenado. stock.warehouseId
CD Warehouse Abreviação de Centro de Distribuição. stock.warehouseId
Warehouse padrão "DEFAULT" Warehouse virtual único quando o seller não rateia por CD. warehouseId: "DEFAULT"
Cross-docking crossDockingTime Tempo de preparação antes do envio (ex.: 1 dia). stock.crossDockingTime
Estoque reservado reservedQty (legacy) Quantidade reservada para pedidos pendentes. Somente leitura. stock.reservedQty

Preço

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Preço Price Objeto de preço de uma variação. /integration/prices/*
Preço default DEFAULT (priceType) Preço base, sem janela de validade. Único por SKU. price.priceType: "DEFAULT"
Preço promocional PROMOTION (priceType) Preço com validityPeriod (início e fim). price.priceType: "PROMOTION"
Preço por plataforma PlatformPrice Preço que sobrepõe o default para um marketplace específico. /integration/prices/platforms/v2
Formação de Preço PriceFormationRule Regra dinâmica que recalcula preços a partir de custo. /bffweb/price-formation/*
Margem de Contribuição CONTRIBUTION_MARGIN Objetivo da regra: lucro por unidade após custos variáveis. rule.objective.driver
Mark-up MARKUP Multiplicador aplicado sobre o custo. rule.objective.driver
Estrutura de Custo CostStructure Custos de canal + custos de produto. rule.costStructure
Comissão commission Comissão percentual do marketplace. costStructure.channelCosts.commission
Custo cost Custo unitário do SKU (do ERP). costStructure.cost

Veja Formação de Preço para o motor de pricing dinâmico e Estoque e preço por SKU para o fluxo simples de PUT.

Frete e Logística

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Frete Freight Custo/logística de envio. order.freightValue
Transportadora Carrier Empresa de logística (Correios, Jadlog, Intelipost). order.carrier
Etiqueta de postagem ShippingLabel PDF/ZPL para colar na caixa. order.shippingLabel
Código de rastreio trackingCode Código de tracking da transportadora. order.tracking.trackingCode
Modalidade de envio ShippingMethod PAC, SEDEX, Express, Standard. order.shippingMethod
Prazo de entrega deliveryTime Prazo estimado em dias úteis. order.deliveryTime

Marketplace / Plataforma

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Marketplace Platform Canal de venda (ML, Amazon, Shopee...). {platform} em path params
Plataforma Platform Sinônimo de Marketplace — cobre também ERP/ecommerce. {platform} em path params
Conta MarketplaceAccount Conta do seller no marketplace (1 seller, N contas). account.id
Integração Integration Conexão autorizada entre seller e plataforma. /bffweb/integrations/*
Publicação Publish (publishType) Ato de criar anúncio: SIMPLE ou VARIATION. platform.publishType
Multi-conta multiAccount: true Plataforma que permite múltiplas contas por seller. platformConfiguration.multiAccount
Blacklist de criação blacklist Plataformas que não suportam criação de pedido. /integration/platforms/blacklist/created
Sugestão de categoria CategorySuggestion Predição de categoria por IA para marketplaces sem preditor. /integration/categories/suggest

Plataform vs Platform — legado de digitação

O codebase antigo da Gubee grafava a entidade como Plataform (sem o "f" final, refletindo a transliteração literal de "Plataforma"). Alguns enums e DTOs legados ainda usam essa grafia. Na API pública e em endpoints novos, use sempre Platform (com "f"). Se você vir Plataform em código-fonte antigo, é o mesmo conceito — não tente "corrigir" sem checar compatibilidade.

Em paths /integration/{platform}/..., o nome canônico é sempre Platform (ex.: MERCADOLIVRE, SHOPEE). Veja Integrações e Plataformas suportadas.

Conta / Seller

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Seller / Vendedor Seller Conta Gubee (empresa cliente). Identificada por sellerId. JWT claim, todas as rotas
Conta de marketplace MarketplaceAccount Credencial de plataforma cadastrada. account.id, account.platform
Authorization code authorizationCode Código OAuth retornado pelo marketplace. fluxo de OAuth
Refresh token refreshToken Token de renovação OAuth (armazenado criptografado). fluxo de OAuth

sellerId NUNCA vem do body

O sellerId é extraído do JWT por TokenCapturingJwtFilter e armazenado em TokenContextHolder. Nunca aceite sellerId no corpo de uma requisição de integrador — ele é silenciosamente ignorado pelos downstream services. Endpoints que parecem aceitar sellerId no body fazem isso por legacia e o campo é descartado.

Para descobrir seu sellerId: decodifique o JWT (claim seller_id) ou chame GET /bffweb/users/me.

Operações em lote

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Operações por planilha SpreadsheetOperation Importação/exportação via XLSX (UI admin). UI admin, sem endpoint público
Importação Import Carga inicial de catálogo. UI admin
Exportação Export Geração de relatório em XLSX/CSV. UI admin
Job Job / RuleExecutionJob Processamento assíncrono com jobId para acompanhamento. /bffweb/price-formation/.../jobs/{id}
Progresso de job BatchProgress Progresso em % e itens processados. job.progress, BatchProgressDrawer
Operação em lote Batch / Bulk Atualização de múltiplos itens em uma chamada. /integration/prices/list/bysku
Erros parciais partialFailure Itens que falharam em um lote (detalhe no response). batch.errors[]

Publicação e templates

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Publicação Publish Ato de criar anúncio em marketplace a partir de produto. UI admin
Publicação simples SIMPLE (publishType) Anúncio sem variações (1 SKU = 1 anúncio). platform.publishType
Publicação por variação VARIATION (publishType) Anúncio com múltiplas variações (tamanho, cor). platform.publishType
Template de anúncio AdTemplate Template de título/descrição aplicado ao publicar. ad.templateId
Enriquecimento Enrichment Aplicação de template a campos (título, descrição). /integration/ads/full/{id}
Status do anúncio AdStatus ACTIVE, INACTIVE, PAUSED, UNDER_REVIEW. ad.status
Pausar anúncio PAUSED Anúncio pausado pelo seller (não visível no marketplace). ad.status: "PAUSED"

Webhooks e eventos

Termo (UI PT-BR) API Entity (English) Descrição Onde aparece
Webhook WebhookSubscription Inscrição para receber eventos da Gubee. /integration/webhooks/*
Evento Event Notificação disparada (pedido, preço, estoque). payload de webhook
Tipo de evento eventType Enum: order.created, price.updated, stock.updated, etc. event.eventType
Idempotência eventId ID único do evento para deduplicação. event.eventId
Retry retryPolicy Política de reenvio em caso de falha (expo backoff). configuração do webhook
Assinatura signature HMAC para validação do payload. header X-Gubee-Signature

Termos obsoletos / legacy

Termo (UI PT-BR) API Entity (legacy) Substituído por Observação
Plano Plan Subscription Ainda aparece em UI legada.
Sub-categoria SubCategory Category (hierarquia via parentId) Modelagem atual é hierárquica.
Etiqueta (produto) Tag Attribute (se for espec) / tag (se for marcador livre) Ambíguo — sempre desambiguar pelo contexto.

Estratégia de busca rápida

Quando você vir um termo no painel e não souber o campo:

  1. Abra o DevTools do navegador → aba Network.
  2. Reproduza a ação no painel.
  3. Veja qual endpoint /bffweb/* foi chamado e qual campo no JSON corresponde ao termo.
  4. Valide com o endpoint equivalente em /integration/* (muitas vezes existe um mirror).

Para descobrir o espelho /integration de um endpoint /bffweb, consulte a Referência da API (specs OpenAPI separadas por superfície).

Mapeamentos não óbvios

Algumas traduções não são literais e confundem integradores:

UI PT-BR Tradução ingênua Tradução correta (API) Por quê?
Etiqueta Tag Shipping Label (order.shippingLabel) Etiqueta é documento de postagem, não marcador textual.
Plataforma Platform Platform (mas código legado usa Plataform) Erro de digitação histórico no enum.
Faturar Invoice (verbo) Status INVOICED + criar Invoice Em PT-BR é ação; em API é estado + entidade.
Despachar Dispatch Status SHIPPED + tracking Idem.
Margem de Contribuição Contribution Margin objective.driver: CONTRIBUTION_MARGIN Termo contábil brasileiro, sem equivalente direto.
Pedido Request Order (Order) "Pedido" no contexto varejo = ordem de compra, não requisição HTTP.
Conta Account Depende do contexto: MarketplaceAccount ou Seller Nunca é livre — sempre desambiguar.
Operação por planilha Spreadsheet Operation SpreadsheetOperation Não confundir com "operação matemática".

Convenções de nomeação em paths de API

  • Singular vs plural: GET /integration/products (lista) vs GET /integration/products/{id} (detalhe). Padrão RESTful.
  • Verbos em paths: byOriginSkuId, bysku, full, list/v2 — nomeação híbrida REST + RPC. Não é canônica, mas estável.
  • Case em enums: UPPER_SNAKE_CASE (MERCADOLIVRE, CONTRIBUTION_MARGIN).
  • Case em campos JSON: camelCase (orderStatus, priceType).

Próximos passos