Pular para conteúdo

Compromisso de Versionamento

A Storefront API (storefront-bff, customer, checkout) segue um compromisso de versionamento /v1 estável, additive-only.

O que /v1 garante

Enquanto um endpoint viver sob o prefixo /v1 (implícito no path — ex.: /store/{slug}/cart, todos os paths do checkout e customer citados nas specs), a Gubee garante:

  • Campos novos e opcionais podem ser adicionados a qualquer momento em request ou response. Seu parser deve ignorar campos desconhecidos (comportamento default da maioria dos parsers JSON modernos).
  • Endpoints novos podem ser adicionados a qualquer momento.
  • Enums podem ganhar novos valores — trate valores desconhecidos com um fallback defensivo, não um switch exaustivo sem default.
  • Comportamento de negócio existente (regras de preço, cálculo de frete, fluxo de pagamento) não muda de forma incompatível sem nova versão.

O que constitui breaking change

Os itens abaixo nunca acontecem dentro de /v1 — exigem uma nova versão paralela (/v2):

  • Remoção de um campo existente em request ou response.
  • Renomeação de um campo (é, na prática, remoção + adição).
  • Mudança de tipo de um campo (ex.: string → number, objeto → array).
  • Mudança de semântica de um campo sem mudança de nome (ex.: status passa a ter um significado diferente para o mesmo valor).
  • Remoção de um endpoint.
  • Mudança de código HTTP de sucesso/erro esperado para um cenário já documentado.
  • Adição de um campo obrigatório em um request existente (isso quebra clientes que não o enviam).

Como uma breaking change seria comunicada

  1. A nova versão nasce em paralelo (/v2/...), nunca substituindo /v1 in place.
  2. /v1 continua funcionando durante um período de convivência anunciado (mínimo — a ser definido por release; segue o padrão de deprecação já usado na API de Integração).
  3. Anúncio no Changelog do portal e, quando aplicável, nas Referências de cada serviço afetado.

Escopo desta garantia

O compromisso /v1 cobre apenas as superfícies documentadas nas três specs da Visão Geral (as rotas públicas de storefront-bff, customer e checkout expostas em store-api.gubee.com.br). Rotas seller-ops, admin, B2B e internas (excluídas deliberadamente das specs publicadas) não têm esse compromisso — são superfície interna, mutável sem aviso.