Pular para conteúdo

Changelog

Todos os cambios notáveis neste portal de desenvolvedor (conteúdo markdown + configuração Redocly) são documentados neste arquivo.

O formato é baseado em Keep a Changelog e este projeto adere a Semantic Versioning.

Escopo: este changelog rastreia apenas o portal (markdown em content/, configuração Redocly, scripts de build, CI). Ele não rastreia mudanças na API Gubee em si — o histórico da API é o log de commits do repositório gubee-api e das specs openapi-*.json consumidas por este portal.

Datas no formato ISO 8601 (YYYY-MM-DD).

Unreleased

Corrigido

  • content/mcp/tools.md e content/mcp/index.md — retirado o aviso de que ean, name e status de search_ads respondiam de um "índice de busca parcial". O diagnóstico estava errado (a busca omitia hasEan e via só anúncios sem EAN); corrigido no servidor, todos os filtros alcançam o catálogo inteiro, com o mesmo total do painel.

Alterado

  • Regras de escrita de ean + eans alinhadas ao que a API faz (journeys/erp/sync-catalog.md, seção "Lista de EANs", concepts/ad-vs-product.md e getting-started/quickstart.md):
  • quando os dois campos são enviados, cada um é comparado com o gravado: lista igual à gravada → vale o ean (antes o portal dizia 400 sempre que ean não estivesse em eans); lista diferente → vale a lista e o par tem de ser coerente, senão 400;
  • motivos de 400 documentados (MULTIPLE_MAIN, TOO_MANY, EAN_NOT_IN_EANS, EAN_NOT_MAIN_OF_EANS), com o type /invalid-ean-list no produto e a chave invalid.ean.list no anúncio; 409 /ean-patch-conflict no PATCH de variação;
  • valor repetido em eans é unificado, não recusado;
  • ean: "" junto com eans: lista igual à gravada → remove todos os EANs (quem lê, esvazia ean e devolve o corpo), assim como eans: []; lista com itens e diferente da gravada → 400 (EAN_NOT_MAIN_OF_EANS); com a gravação da lista desabilitada, ean: "" remove sempre. Antes o portal dizia que o ean: "" era ignorado. Reenviar o corpo lido com ean: "" devolve 400 na segunda vez e os EANs continuam removidos; só ean: "" pode ser repetido sem erro. Na criação, ean: "" com eans com itens grava a lista;
  • com a gravação da lista desabilitada, eans: [] sem ean só limpa em POST/PUT de produto: no PATCH de variação e no anúncio é ignorado (o portal dizia que limpava). A forma de remover que vale sempre é só ean: "";
  • PUT com variação sem skuId recria a variação e perde os EANs secundários;
  • a gravação de eans é habilitada por ambiente: os exemplos passam a enviar ean e eans juntos e coerentes, e um payload só com eans pode não gravar EAN.
  • Mudanças de comportamento documentadas junto com a lista de EANs (ver "Adicionado"):
  • Anúncio: em criar (POST /bffweb/ads), atualizar (PUT /bffweb/ads/{id}) e editar em lote (PUT /bffweb/ads/bulk-edit), ean nulo ou omitido deixa de apagar o EAN do anúncio. ean: "" remove (eans: [] só com a gravação da lista habilitada).
  • Produto: na atualização completa, omitir ean (ou enviar null) deixa de apagar o EAN da variação. Para remover, ean: "".
  • A busca por EAN (filtro ean de produtos e de anúncios) e a associação de anúncio a produto por EAN passam a casar com qualquer EAN da lista, principal ou secundário.
  • content/getting-started/quickstart.md — o token vem de um app OAuth2 (authorization code com PKCE), não mais do API Token descontinuado; tabela das permissões que o guia usa.
  • environments.md, journeys/erp/sync-catalog.md, reference/README.md e mcp/conexao.md — referências de "como obter o token" apontam para os apps OAuth2.

Depreciado

  • Campo ean da variação do produto e do anúncio: depreciado, sem data de remoção. Continua aceito na escrita e devolvido na leitura, sempre com o EAN principal da lista eans. Quem envia só ean não precisa mudar nada.

Adicionado

  • Vários EANs por variação e por anúncio — campo eans: [{ "value", "main" }], até 20 itens, exatamente um principal, na leitura e na escrita. Regras completas em Lista de EANs (journeys/erp/sync-catalog.md): campo ausente ou null não altera; só ean com valor vira o principal e mantém os secundários; ean: "" sem eans e eans: [] removem todos; eans com itens substitui a lista; 400 para mais de um main, mais de 20 itens, ou par ean/eans incoerente quando a lista difere da gravada (ver "Alterado"). Também em getting-started/quickstart.md, concepts/glossario.md, concepts/sku-vs-skuid.md, concepts/ad-vs-product.md (seção "EANs do anúncio": eans omitido quando nulo e [] quando vazio nas respostas de anúncio) e mcp/tools.md (as tools de consulta mostram os demais EANs; as de alteração não editam EAN). A Referência da API passa a mostrar eans e ean depreciado quando o gubee-api publicar a spec.

  • 2026-09-30 — Alterações pelo MCP (content/mcp/escrita.md): as 6 tools de alteração do servidor MCP, todas em produção — update_price, update_stock, update_product, update_ad, manage_ad_tags e issue_invoice. Fluxo em dois passos (pré-visualização com antes → depois, confirmação com código válido por cerca de 10 minutos, confirmação adicional do aplicativo quando houver), o que cada tool altera e o que não altera, quando repetir uma confirmação é seguro, as permissões (price:edit, stock:edit, product:edit, ad:edit, invoice:issue, concedidas só a quem as tem no painel) e os erros comuns. Entrada no menu MCP.

  • 2026-09-30 — content/mcp/tools.md, content/mcp/index.md e content/mcp/conexao.md: o catálogo passa de 16 para 22 tools (seção "Alteração"); a visão geral troca "Somente leitura" por "Alterações"; a conexão ganha a seção "Alterações" com os escopos a acrescentar.

  • content/oauth2/escopos.md — catálogo das 27 permissões de app OAuth2, as ações sensíveis com permissão própria (invoice:issue, invoice:cancel, order:cancel, order:customer-data), a convivência de 90 dias iniciada em 27/09/2026 e o corte em 26/12/2026.

  • content/oauth2/referencia.md e content/mcp/tools.md — required_scope no 403 e dado do comprador sujeito à permissão a partir do corte.

  • Guia de compatibilidade veicular: listagem paginada dos anúncios pendentes de compatibilidade (GET /pending, campo pendingTag em /platforms), descoberta de canais e contas, filtros, veículos, posições, aplicação, consulta, substituição e remoção; escopos OAuth2, limites e resultados parciais.

  • Conectar um cliente MCP reescrita para o lojista conseguir sozinho: Client ID gubee-mcp-desktop publicado, configurações prontas para copiar com caminho do arquivo por sistema, como é o login, dados do comprador e tabela "se der errado". Separa as conversas do ChatGPT (modo desenvolvedor) do Codex dentro do ChatGPT desktop, que lê outro lugar.

  • Em Conectar um cliente MCP, a seção Conectar o seu assistente: passo a passo para ChatGPT, opencode, Codex CLI, Claude Code, Claude (web e Desktop), Cursor, VS Code e Gemini CLI, com a callback fixa de cada um e as duas armadilhas do Codex (escopos obrigatórios, oauth_resource duplicando resource).

  • Seção MCP (Assistentes de IA) documentando o servidor Model Context Protocol da Gubee, em content/mcp/:

  • content/mcp/index.md — visão geral, público-alvo, o recorte somente-leitura e as garantias de comportamento (escopo por lojista, resposta parcial declarada, falha que não vira lista vazia, redação de dado do comprador, fuso do lojista, recusa de argumento desconhecido).
  • content/mcp/conexao.md — endpoint, transporte Streamable HTTP, descoberta automática por RFC 9728, as duas formas de autenticar (authorization_code + PKCE e client_credentials) e o formato da chamada crua.
  • content/mcp/tools.md — as 16 tools agrupadas por domínio, com argumentos e as armadilhas de cada uma.
  • Entrada de MCP na tabela de audiências e nos próximos passos da página inicial.

Planejado

  • Páginas do diretório content/concepts/ (SKU vs. skuId, modelo de produto, categorias por canal).
  • Páginas do diretório content/journeys/erp/ (receber pedidos, sincronizar estoque, atualizar preço, emitir nota).
  • Páginas do diretório content/journeys/media/ (upload de vídeo, ciclo de processamento, replicação produto → anúncio).
  • Guias de content/getting-started/ (obter token JWT, primeira chamada, paginação, tratamento de erros).
  • Exemplos de código em mais linguagens (atualmente cURL; planejado: Kotlin, Java, C#, PHP).
  • Seção de migração do Postman com mapeamento request-a-request.

1.0.0 - 2026-07-07

Adicionado

  • Release inicial do Portal do Desenvolvedor Gubee em https://developers.gubee.com.br.
  • Estrutura de conteúdo sob content/ com seções: webhooks/, reference/, journeys/, concepts/, getting-started/.
  • Pipeline de build do portal com Redocly (redocly.yaml, package.json).
  • Pipeline de CI no GitLab (.gitlab-ci.yml) para validação de markdown, build estático e deploy.
  • Documentação completa da seção Webhooks com 4 páginas:
  • content/webhooks/events.md — catálogo de eventos por domínio.
  • content/webhooks/payload-schema.md — referência campo a campo do payload.
  • content/webhooks/retry-policy.md — política de retentativa e recuperação de notificações perdidas.
  • content/webhooks/idempotency.md — modelo de deduplicação at-least-once.
  • Página inicial de Referência da API (content/reference/README.md) descrevendo as três specs OpenAPI (integration, bff, all), cobertura por 14 domínios e formatos HAL+JSON / JSON plano.

Alterado

  • Migração da documentação de integração do Postman (coleção estática compartilhada via link) para um portal versionado, navegável e automaticamente renderizado a partir da spec OpenAPI do gubee-api.
  • A coleção Postman continua disponível internamente para testes pontuais, mas não é mais a fonte oficial de documentação para parceiros.

Removido

  • Dependência de coleção Postman como única documentação pública. O Postman não versionava com o código, não era pesquisável em larga escala, não tinha binding automático para a spec OpenAPI e era propenso a drift entre o que estava publicado e o que a API de fato entregava.

Documentação

Cobertura inicial dos 14 domínios da API de Integração /integration/*:

  1. product — produtos, variações, imagens, atributos.
  2. ad — anúncios, anúncios por produto, atualização em massa.
  3. order — pedidos, fila por status, fatura, envio.
  4. stock — consulta e atualização de estoque (V2).
  5. price — consulta e atualização de preço (V2).
  6. invoice — anexar nota fiscal a pedido.
  7. tag — agrupamentos lógicos de produtos.
  8. freight — tabelas de frete.
  9. video — upload, commit, status de processamento de vídeo.
  10. platform — marketplaces conectados ao vendedor.
  11. marketplace — catálogo de canais disponíveis.
  12. attribute — atributos customizados por categoria.
  13. category — árvore de categorias por marketplace.
  14. brand — marcas cadastradas.

A referência navegável para todos esses domínios é gerada automaticamente pela Redocly a partir de openapi-integration.json.

Convenções deste changelog

  • Adicionado para novas funcionalidades ou páginas.
  • Alterado para mudanças em funcionalidades/páginas existentes.
  • Depreciado para funcionalidades ainda funcionais mas que serão removidas.
  • Removido para funcionalidades/páginas removidas.
  • Corrigido para correção de bugs ou erros factuais.
  • Segurança para vulnerabilidades no portal (não na API).
  • Documentação para mudanças puramente de conteúdo.

Os releases seguem SemVer: mudança major quando há reestruturação que quebra links públicos ou navegação, minor para novas seções, patch para correções.