Pular para conteúdo

Referência da API

Esta seção é a referência automática da API de Integração Gubee.

Referência interativa (Redoc)

A referência completa e navegável da API está disponível em:

Abrir Referência da API (Redoc)

Inclui todos os 125+ endpoints sob /integration/*, com schemas de request/response, exemplos de cURL, e busca. Atualizada automaticamente a cada deploy do gubee-api.

Domínios cobertos

Domínio Endpoints Descrição
Products 25+ CRUD de produtos, variações, imagens, vídeos, SKU mapping
Ads 6 Consulta de anúncios por originSkuId, busca, mapeamento
Orders 9 + queue Ciclo de vida do pedido (criar→pago→faturado→enviado→entregue)
Prices 11 Preço por SKU, por plataforma, em lote
Stocks 8 Estoque por SKU, por warehouse, por plataforma
Promotions 10 CRUD de promoções/ajustes de preço
Images 2 Redimensionamento de imagens
Invoices 2 + 14 Notas fiscais (legacy + invoicer completo)
Tags 11 Etiquetas de envio (Correios/Intelipost)
Quotes 1 Cotação de frete
Videos 5 Upload de vídeo (presigned + commit)
Platforms 2 Lista de plataformas suportadas + blacklist
Categories 7 CRUD de categorias + bulk
Attributes 10 CRUD de atributos + bulk
Brands 10 CRUD de marcas
Notifications 2 Webhooks perdidos (recuperação)
Tokens 1 Renovação de token de API

As três specs OpenAPI

A gubee-api (o BFF stateless da Gubee) produz três specs OpenAPI no build, expostas em /openapi.json, /openapi-bff.json e /openapi-integration.json:

Spec Prefixo Público Disponível neste portal?
openapi-integration.json /integration/* Parceiros, ERPs, hubs, integradores Sim — é o foco
openapi-bff.json /bffweb/* Frontend web interno da Gubee Não
openapi.json ambos combinados Interno (debug, QA) Não

A separação existe porque o BFF tem dois surfaces distintos com contratos diferentes:

  • /integration/* — API pública versionada, estável, voltada para máquinas. É a única que importa para integradores.
  • /bffweb/* — otimizada para o frontend da Gubee (agregações, formato conveniente para UI, mutável sem aviso). Não construa integração em cima dela.

Se você está construindo um integrador ERP, use apenas openapi-integration.json. O portal inteiro, as jornadas e os exemplos assumem isso.

Cobertura por domínio

A API de integração cobre 14 domínios funcionais, totalizando mais de 100 endpoints:

Domínio Exemplos de endpoints
product /integration/products, variações, imagens, atributos por SKU
ad /integration/ads, anúncios por produto, atualização em massa
order /integration/orders, filas por status, pedido por ID, fatura, envio
stock /integration/stock, consulta e atualização de estoque (V2: JSON plano)
price /integration/prices, consulta e atualização de preço (V2: JSON plano)
invoice /integration/orders/{orderId}/invoice, anexar nota fiscal
tag /integration/tags, agrupamentos lógicos de produtos
freight /integration/freight, tabelas de frete por região
video /integration/videos, upload, commit, status de processamento
platform /integration/platforms, marketplaces conectados ao vendedor
marketplace /integration/marketplaces, catálogo de canais disponíveis
attribute /integration/attributes, atributos customizados por categoria
category /integration/categories, árvore de categorias por marketplace
brand /integration/brands, marcas cadastradas

Cada domínio tem pelo menos uma jornada de uso documentada em ../journeys/. Para o ciclo de venda, veja especificamente ../journeys/erp/.

Formatos de resposta: HAL+JSON vs. JSON plano

A gubee-api mistura dois estilos de resposta. Saber qual esperar evita parsing errado:

HAL+JSON (application/hal+json)

A maioria das respostas — produtos, categorias, atributos, marcas, tags, pedidos, notificações perdidas — retorna em HAL+JSON. Os recursos individuais vêm envelopados em EntityModel, e listas paginadas em PagedModel, com hyperlinks HATEOAS em _links:

{
  "skuId": "sku-ABC123",
  "name": "Camiseta Polo",
  "status": "ACTIVE",
  "_links": {
    "self":      { "href": "https://api.gubee.com.br/integration/products/variations/sku-ABC123" },
    "product":   { "href": "https://api.gubee.com.br/integration/products/P-001" },
    "images":    { "href": "https://api.gubee.com.br/integration/products/P-001/variations/sku-ABC123/images" }
  }
}

Listas paginadas têm o envelope PagedModel:

{
  "_embedded": {
    "productApiDTOList": [
      { "skuId": "sku-ABC123", "_links": { "self": { "href": "..." } } },
      { "skuId": "sku-DEF456", "_links": { "self": { "href": "..." } } }
    ]
  },
  "page": {
    "size": 20,
    "totalElements": 137,
    "totalPages": 7,
    "number": 0
  },
  "_links": {
    "self":  { "href": "...?page=0&size=20" },
    "next":  { "href": "...?page=1&size=20" },
    "last":  { "href": "...?page=6&size=20" }
  }
}

O nome da chave dentro de _embedded varia por domínio (productApiDTOList, missedNotificationApiDTOList, orderApiDTOList, etc.). Sempre inspecione a chave real ou use o campo page para paginação.

Use o header Accept: application/hal+json para receber no formato enriquecido; Accept: application/json devolve o objeto puro sem _links quando o endpoint suporta ambos.

JSON plano (application/json)

Endpoints V2 de estoque, preço e vídeo retornam JSON plano, sem envelope HATEOAS:

{
  "skuId": "sku-ABC123",
  "stock": 42,
  "updatedAt": "2026-07-07T14:30:00Z"
}

Esse formato é mais direto para integrações ponto-a-ponto (consultar preço, atualizar estoque). Não há _links; você precisa conhecer os caminhos das operações relacionadas.

Paginação

Os endpoints paginados seguem o padrão HAL+JSON: query parameters page (0-based) e size. Alguns aceitam também sort=campo,asc|desc.

curl -sS \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Accept: application/hal+json' \
  'https://api.gubee.com.br/integration/products?size=50&page=0&sort=createdAt,desc'

Os campos de paginação (totalElements, totalPages) são confiáveis para estimar volume, mas em sistemas eventualmente consistentes o número pode variar entre páginas — não assuma que a página 1 tem exatamente os mesmos itens da consulta anterior se houver inserções/remoções concorrentes.

SKU vs. skuId

Vários endpoints operam sobre o conceito de SKU, mas há duas variantes que aparecem na API e precisam ser distinguidas:

  • SKU — o código legado, livre (definido pelo vendedor, alfanumérico).
  • skuId — o identificador interno canônico da Gubee, usado na maioria dos endpoints V2.

Alguns endpoints aceitam ambos, outros só um. Veja a explicação completa em ../concepts/sku-vs-skuid.md antes de modelar o mapeamento no seu integrador.

Autenticação

Todos os endpoints /integration/* exigem JWT no header Authorization:

curl -H 'Authorization: Bearer <JWT>' https://api.gubee.com.br/integration/...

O JWT carrega o sellerId e é emitido pela Gubee. Endpoints que filtram por vendedor usam o sellerId do token — nunca passe sellerId no corpo da requisição, ele será ignorado. Veja ../getting-started/quickstart.md para obter o token.

Versionamento

A política de versionamento é:

  • Quebra de contrato ocorre com nova versão de spec (gubee-api major bump).
  • Novos campos opcionais podem ser adicionados a qualquer momento — seu desserializador deve ignorar campos desconhecidos (configuração default na maioria dos parsers JSON modernos).
  • Remoção de campos ou mudança de tipo são quebras e vêm versionadas.

O changelog deste portal (sobre o conteúdo markdown e a config Redocly) está em ../CHANGELOG.md. O changelog da API é o histórico do repositório gubee-api e não é replicado aqui.

Como usar a referência Redocly

A referência renderizada neste portal é navegável por:

  • Tag — agrupa endpoints por domínio (Product, Order Integration Queues, Notification, etc.).
  • Operation ID — identificador estável (ex.: listOrdersByStatusQueue) útil para gerar clients.
  • Search — busca por path, summary ou descrição.

Para cada endpoint você encontra: parâmetros (path, query, header), schema da requisição e da resposta, códigos HTTP esperados e exemplos. Use o botão "Try it" para chamadas autenticadas diretas durante o desenvolvimento.

Próximos passos