Pular para conteúdo

Storefront API (Tier 2)

A Storefront API é a API pública headless do canal de comprador Gubee (WhatsApp AI Checkout + loja própria). Diferente da API de Integração (voltada a ERPs/hubs do lado do vendedor), a Storefront API é voltada a agências e integradores que constroem um front de comprador (browse → PDP → carrinho → checkout → conta) por cima do motor de comércio da Gubee.

Host público: store-api.gubee.com.br (TLS, CORS allowlist por agência onboardada, rate-limit na borda — ver Ambientes).

Três serviços, três specs

A Storefront API é composta por três serviços independentes, cada um com sua própria spec OpenAPI:

Serviço Spec Responsabilidade
storefront-bff Referência ↗ Agregação: browse/PLP/PDP, carrinho, conta (Qute Tier 1 + API JSON Tier 2), auth (email/Google), conexão com marketplaces
customer Referência ↗ Identidade do comprador: cadastro, OTP, sessões, endereços, métodos de pagamento, consentimento LGPD
checkout Referência ↗ Sessão de checkout, carrinho transacional, pagamento (PIX/boleto/cartão), webhook do gateway

Cada spec documenta apenas as rotas públicas desse serviço — endpoints seller-ops/admin/B2B/internos são deliberadamente excluídos (não fazem parte do contrato Tier 2).

Fluxo de referência (browse → PIX)

  1. Browse/PDP — storefront-bff (/store/{slug}/products, /store/{slug}/plp)
  2. Auth do comprador — customer (OTP ou email/senha) via storefront-bff (/store/{slug}/auth/*)
  3. Carrinho — storefront-bff (/store/{slug}/cart)
  4. Checkout — checkout diretamente ou via storefront-bff (/store/{slug}/checkout), incluindo OTP de confirmação e QR PIX inline
  5. Conta do comprador — saldo de cashback, assinaturas, pedidos, 2ª via de boleto (storefront-bff /store/{slug}/account/*)

Autenticação

Todos os endpoints de comprador exigem Bearer JWT do comprador (emitido pelo customer após OTP/login), audience customer. Nunca envie sellerId em header ou body — ele é derivado do slug da loja/token, server-side.

Versionamento

Ver Compromisso de Versionamento — /v1 é estável, additive-only.

Publicação da spec

As specs publicadas aqui são estáticas (geradas via quarkus.smallrye-openapi.store-schema-directory no build de cada serviço e commitadas em specs/) — o host público store-api.gubee.com.br não expõe /q/openapi (superfície de management fica fora do Ingress público). Atualização é manual por ora; automação via pipeline (padrão trigger_docs_portal do gubee-api) é follow-up documentado, não desta fase.