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

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.