Desenvolvedores

Referência da Storefront API

68 endpoints sob https://SUA-LOJA.meweb.com.br/api/v1. Rotas marcadas com sessão de cliente exigem os cookies de autenticação do cliente; as demais são públicas.

Loja e site

Dados institucionais da loja, layout publicado do site (seções da home), menus e o gate do modo em construção.

GET/storefront/store
GET/storefront/site/layout
GET/storefront/site/preview-session
GET/storefront/site/gate
GET/storefront/site/order-tracking
POST/storefront/site/unlock
GET/storefront/menus/:handle

GET/storefront/store

Dados públicos da loja (nome, contatos, checkoutEnabled e os campos do checkout) para header/footer e checkout.

Resposta `(publicStoreInfoSchema)`

Campo	Tipo	Obrigatório
name	string	sim
email	string \| null	sim
phone	string \| null	sim
whatsapp	string \| null	sim
address	objeto \| null	sim
checkoutEnabled	boolean	não
checkoutFields	objeto	não

Exemplo (payload de "data")

{
  "name": "Minha Loja",
  "checkoutEnabled": true,
  "checkoutFields": {
    "cpfCnpj": "optional",
    "phone": "required",
    "company": "off",
    "birthDate": "off"
  },
  "email": "contato@minhaloja.com.br",
  "phone": "(11) 4000-0000",
  "whatsapp": "(11) 99999-0000",
  "address": {
    "street": "Av. Paulista",
    "number": "1000",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "cep": "01310-100"
  }
}

checkoutEnabled: false (spec 19 RN-20, vitrine congelada) significa que a loja está no ar e navegável mas NÃO vende: esconda botões de compra, carrinho e "comprar agora". O checkout responde 422 PLAN_CHECKOUT_DISABLED de qualquer forma: a flag existe para o cliente final não bater no erro.
checkoutFields (spec 15 RN-08) diz o que a etapa de identificação deve pedir: off = não renderize, optional = renderize sem asterisco, required = renderize com asterisco e bloqueie o avanço. **Já vem resolvido**: o cpfCnpj chega required sozinho quando o lojista habilita boleto ou emissão de NF-e, então o tema não precisa (nem deve) refazer essa conta.
Tema que ignora checkoutFields quebra de dois jeitos, e os dois já aconteceram: com birthDate: "required" o POST /storefront/checkout/complete responde 422 por um campo que a tela não pediu; e com cpfCnpj: "optional" a tela segue exigindo um documento que a loja não usa, desfazendo a minimização que o servidor aplicou.

GET/storefront/site/layout

Layout publicado do site: seções da home com dados embutidos, identidade e tema.

Query string

preview (opcional): Token de preview do rascunho (emitido no admin da loja).

Resposta

Objeto PublicSiteLayout: sections (união discriminada por type: hero_banner, product_grid, collection_grid, image_text, newsletter, custom_code etc., cada uma com os dados já resolvidos), footerGroups (grupos do rodapé com menus), identity (cores, logo, banner de anúncios) e theme (tema ativo + settings + código custom).

Um front headless pode ignorar esta rota e definir o próprio layout; ela existe para quem quer reaproveitar as seções montadas no admin.

GET/storefront/site/preview-session

Diz o que um token de pré-visualização do site autoriza (spec 14 §11, D5).

Query string

token (obrigatório): Token de preview emitido no admin da loja.

Resposta

{ scope, editor, theme, designId?, editorOrigin? }: diz se o token abre o rascunho ou o publicado (scope), qual rascunho (designId, ausente no escopo publicado), se liga o modo editor e para qual origin a ponte responde (editorOrigin, ausente fora do modo editor) e o tema efetivo. Token inválido ou expirado responde 404 PREVIEW_EXPIRED.

Existe para que a vitrine valide o token SEM conhecer o segredo de assinatura da API: quem verifica a assinatura é a API, o front só recebe o veredito.
Não é cacheável: o token é de uso único do preview e tem validade de 1 hora.

GET/storefront/site/gate

Estado do modo "em construção" da loja (resolvido por host).

Resposta

{ enabled: boolean, locked: boolean, message: string }, em que locked indica visitante sem o cookie de desbloqueio.

GET/storefront/site/order-tracking

Configuração do rastreio de pedido da loja (spec 01 RN-24), resolvida por host.

Resposta `(orderTrackingConfigSchema)`

Campo	Tipo	Obrigatório
mode	"native" \| "external" \| "both"	não
externalKind	"link" \| "embed"	não
externalUrl	string \| null	não
externalEmbedHtml	string \| null	não
helpText	string \| null	não

Exemplo (payload de "data")

{
  "mode": "both",
  "externalKind": "link",
  "externalUrl": "https://www.ordertracker.com/track/{codigo}",
  "externalEmbedHtml": null,
  "helpText": "O código de rastreio chega por e-mail em até 2 dias úteis."
}

Config EFETIVA: o fail-safe da RN-24 já vem aplicado, e modo externo sem externalUrl/externalEmbedHtml preenchido chega como native. Não reimplemente essa decisão no seu front.
externalUrl é um template: substitua {codigo} pelo código de rastreio do pedido (RN-09) para levar o cliente direto ao provedor.
externalEmbedHtml é HTML/JS do provedor, guardado sem sanitização (mesmo modelo de confiança do código customizado, spec 14 RN-16); renderize-o só na sua vitrine.
Cacheável: muda apenas quando o lojista salva a configuração no admin.

POST/storefront/site/unlock

Desbloqueia o modo em construção com a senha; emite o cookie sf_unlock.

Body `(siteUnlockSchema)`

Campo	Tipo	Obrigatório
password	string	sim

Exemplo de requisição

{
  "password": "espia-ai"
}

Resposta

{ ok: true }

GET/storefront/menus/:handle

Árvore de menu resolvida por handle (ex.: menu principal e links rápidos).

Parâmetros de rota

handle (obrigatório): Handle do menu (ex.: main-menu).

Resposta `(publicMenuSchema)`

Campo	Tipo	Obrigatório
handle	string	sim
title	string	sim
items	objeto[]	sim

Exemplo (payload de "data")

{
  "handle": "main-menu",
  "title": "Menu principal",
  "items": [
    {
      "label": "Início",
      "url": "/",
      "children": []
    },
    {
      "label": "Coleções",
      "url": null,
      "children": [
        {
          "label": "Camisetas",
          "url": "/colecoes/camisetas"
        }
      ]
    }
  ]
}

Catálogo

Produtos ativos, busca, coleções publicadas e disponibilidade de estoque. Preços sempre em centavos (integer). URLs de mídia vêm RELATIVAS ao host da loja (/api/v1/media/...); sirva-as pelo seu proxy same-origin ou prefixe com https://<host-da-loja>.

GET/storefront/home
GET/storefront/products/:slug
GET/storefront/search
GET/storefront/collections
GET/storefront/collections/:slug
GET/storefront/collections/:slug/products
GET/storefront/availability

GET/storefront/home

Dados da home default: coleções em destaque (até 6) com até 8 produtos cada.

Resposta `(homeDataSchema)`

Campo	Tipo	Obrigatório
collection	objeto	sim
products	objeto[]	sim

Exemplo (payload de "data")

[
  {
    "collection": {
      "id": "01J0EXEMPLOCOLECAO0000000",
      "slug": "camisetas",
      "title": "Camisetas",
      "descriptionHtml": "<p>Nossas camisetas.</p>",
      "imageUrl": null
    },
    "products": [
      {
        "id": "01J0EXEMPLOPRODUTO0000000",
        "slug": "camiseta-basica",
        "title": "Camiseta Básica",
        "thumbnailUrl": "/api/v1/media/renditions/01J0EXEMPLOMIDIA000000000-md.webp",
        "priceCents": 7990,
        "compareAtPriceCents": 9990,
        "hasPriceRange": false,
        "available": true
      }
    ]
  }
]

GET/storefront/products/:slug

Detalhe de um produto ativo (PDP): imagens, opções, variantes e FAQs.

Parâmetros de rota

slug (obrigatório): Slug público do produto.

Resposta `(publicProductSchema)`

Campo	Tipo	Obrigatório
id	string	sim
slug	string	sim
title	string	sim
descriptionHtml	string	sim
seoTitle	string \| null	sim
seoDescription	string \| null	sim
categoryName	string \| null	sim
images	objeto[]	sim
videos	objeto[]	não
options	objeto[]	sim
variants	objeto[]	sim
faqs	objeto[]	sim
aiGenerated	boolean	não

Exemplo (payload de "data")

{
  "id": "01J0EXEMPLOPRODUTO0000000",
  "slug": "camiseta-basica",
  "title": "Camiseta Básica",
  "descriptionHtml": "<p>Algodão penteado 30.1.</p>",
  "seoTitle": null,
  "seoDescription": null,
  "categoryName": "Vestuário",
  "images": [
    {
      "thumb": "https://minha-loja.meweb.com.br/media/camiseta-thumb.webp",
      "md": "https://minha-loja.meweb.com.br/media/camiseta-md.webp",
      "lg": "https://minha-loja.meweb.com.br/media/camiseta-lg.webp",
      "alt": "Camiseta básica preta",
      "optionValueId": null
    }
  ],
  "videos": [],
  "options": [
    {
      "id": "01J0EXEMPLOOPCAO000000000",
      "name": "Tamanho",
      "values": [
        {
          "id": "01J0EXEMPLOVALOR000000000",
          "value": "P"
        },
        {
          "id": "01J0EXEMPLOVALOR000000001",
          "value": "M"
        }
      ]
    }
  ],
  "variants": [
    {
      "id": "01J0EXEMPLOVARIANTE000000",
      "title": "P",
      "sku": "CAM-P",
      "priceCents": 7990,
      "compareAtPriceCents": null,
      "optionValueIds": [
        "01J0EXEMPLOVALOR000000000"
      ],
      "availableQuantity": 0
    }
  ],
  "faqs": [
    {
      "question": "Encolhe na lavagem?",
      "answer": "Não, é pré-encolhida."
    }
  ]
}

variants[].availableQuantity vem sempre **0** nesta rota, inclusive no exemplo acima: o catálogo não lê estoque (fronteira de módulo), e a disponibilidade real é composta pelo front via GET /storefront/availability (consulta em lote).

GET/storefront/searchpaginada

Busca de produtos por texto, paginada por cursor.

Query string

q (obrigatório): Termo de busca (1–120 caracteres).
limit (opcional): Itens por página (1–100, padrão 25).
cursor (opcional): endCursor da página anterior.

Resposta `(publicProductCardSchema, item de data[])`

Campo	Tipo	Obrigatório
id	string	sim
slug	string	sim
title	string	sim
thumbnailUrl	string \| null	sim
priceCents	inteiro	sim
compareAtPriceCents	inteiro \| null	sim
hasPriceRange	boolean	sim
available	boolean	sim

Exemplo (payload de "data")

{
  "id": "01J0EXEMPLOPRODUTO0000000",
  "slug": "camiseta-basica",
  "title": "Camiseta Básica",
  "thumbnailUrl": null,
  "priceCents": 7990,
  "compareAtPriceCents": null,
  "hasPriceRange": false,
  "available": true
}

Query validada por searchProductsQuerySchema.

GET/storefront/collections

Coleções publicadas.

Resposta `(publicCollectionSchema[])`

Campo	Tipo	Obrigatório
id	string	sim
slug	string	sim
title	string	sim
descriptionHtml	string	sim
imageUrl	string \| null	sim

Exemplo (payload de "data")

[
  {
    "id": "01J0EXEMPLOCOLECAO0000000",
    "slug": "camisetas",
    "title": "Camisetas",
    "descriptionHtml": "",
    "imageUrl": null
  }
]

GET/storefront/collections/:slug

Detalhe de uma coleção publicada.

Parâmetros de rota

slug (obrigatório): Slug público da coleção.

Resposta `(publicCollectionSchema)`

Campo	Tipo	Obrigatório
id	string	sim
slug	string	sim
title	string	sim
descriptionHtml	string	sim
imageUrl	string \| null	sim

GET/storefront/collections/:slug/productspaginada

Produtos de uma coleção, com ordenação e paginação por cursor.

Parâmetros de rota

slug (obrigatório): Slug público da coleção.

Query string

sort (opcional): default | price_asc | price_desc | newest | title | best_selling.
limit (opcional): Itens por página (1–100, padrão 25).
cursor (opcional): endCursor da página anterior.

Resposta `(publicProductCardSchema, item de data[])`

Campo	Tipo	Obrigatório
id	string	sim
slug	string	sim
title	string	sim
thumbnailUrl	string \| null	sim
priceCents	inteiro	sim
compareAtPriceCents	inteiro \| null	sim
hasPriceRange	boolean	sim
available	boolean	sim

Query validada por listCollectionProductsQuerySchema.

GET/storefront/availability

Disponibilidade de estoque por variante (consulta em lote).

Query string

variantIds (obrigatório): IDs de variante separados por vírgula (máx. 200).

Resposta `(Record<variantId, number>)`

Exemplo (payload de "data")

{
  "01J0EXEMPLOVARIANTE000000": 12
}

Páginas institucionais

Páginas publicadas no admin (sobre, trocas, contato…), com HTML sanitizado.

GET/storefront/pages
GET/storefront/pages/preview
GET/storefront/pages/:slug

GET/storefront/pages

Lista de páginas publicadas (para footer/sitemap).

Resposta `({ title, slug, updatedAt }[])`

Campo	Tipo	Obrigatório
title	string	sim
slug	string	sim
updatedAt	string	sim

Exemplo (payload de "data")

[
  {
    "title": "Trocas e devoluções",
    "slug": "trocas",
    "updatedAt": "2026-07-01T12:00:00.000Z"
  }
]

GET/storefront/pages/preview

Preview de rascunho por token (emitido no admin).

Query string

token (obrigatório): Token de preview.

Resposta `(publicPageResultSchema)`

GET/storefront/pages/:slug

Página publicada por slug (ou redirect quando o slug mudou).

Parâmetros de rota

slug (obrigatório): Slug público da página.

Resposta `(publicPageResultSchema)`

Exemplo (payload de "data")

{
  "title": "Trocas e devoluções",
  "slug": "trocas",
  "bodyHtml": "<p>Você tem 30 dias para trocar.</p>",
  "seoTitle": "",
  "seoDescription": "",
  "publishedAt": "2026-07-01T12:00:00.000Z"
}

Slug antigo de página publicada responde { redirectTo: "/paginas/<novo>" }.

Blog

Posts publicados no admin (spec 25), com HTML sanitizado. Alimentam a listagem /blog, a página do post, o sitemap e o feed RSS do tema.

GET/storefront/blog/posts
GET/storefront/blog/posts/:slug

GET/storefront/blog/postspaginada

Posts publicados, do mais recente ao mais antigo, com filtro por tag.

Query string

tag (opcional): Filtra por uma tag (minúsculas).
limit (opcional): Itens por página (1–50, padrão 12).
cursor (opcional): endCursor da página anterior.

Resposta `(publicBlogListItemDtoSchema, item de data[])`

Campo	Tipo	Obrigatório
title	string	sim
slug	string	sim
excerpt	string	sim
coverUrl	string \| null	sim
tags	string[]	sim
publishedAt	string	sim

Exemplo (payload de "data")

{
  "title": "Como escolher o tamanho certo",
  "slug": "como-escolher-o-tamanho-certo",
  "excerpt": "Um guia rápido para acertar de primeira.",
  "coverUrl": "/api/v1/media/renditions/01J0EXEMPLOMIDIA000000000-lg.webp",
  "tags": [
    "guias"
  ],
  "publishedAt": "2026-07-01T12:00:00.000Z"
}

Rascunhos nunca aparecem aqui (RN-04), nem na busca, no sitemap ou no RSS.
Query validada por listPublicBlogPostsQuerySchema. Para o RSS (RN-06), peça limit=20.
excerpt vazio no admin vem derivado do corpo do post.

GET/storefront/blog/posts/:slug

Post publicado por slug (ou redirect quando o slug mudou).

Parâmetros de rota

slug (obrigatório): Slug público do post.

Query string

preview (opcional): Token de preview do rascunho (emitido no admin da loja).

Resposta `(publicBlogPostResultSchema)`

Exemplo (payload de "data")

{
  "post": {
    "title": "Como escolher o tamanho certo",
    "slug": "como-escolher-o-tamanho-certo",
    "excerpt": "Um guia rápido para acertar de primeira.",
    "bodyHtml": "<p>Meça o busto e a cintura antes de comprar.</p>",
    "coverUrl": null,
    "authorName": "Equipe da Loja",
    "tags": [
      "guias"
    ],
    "seoTitle": "",
    "seoDescription": "",
    "publishedAt": "2026-07-01T12:00:00.000Z"
  }
}

Slug antigo de post publicado responde { redirectTo: "/blog/<novo>" }; sirva um 301/308.
Post draft ou inexistente responde 404 BLOG_POST_NOT_FOUND (RN-03/07).

Avaliações

Avaliações aprovadas de produto; envio exige cliente autenticado.

GET/storefront/products/:slug/reviews
POST/storefront/products/:slug/reviews

GET/storefront/products/:slug/reviewspaginada

Avaliações aprovadas do produto, paginadas, com resumo de notas.

Parâmetros de rota

slug (obrigatório): Slug público do produto.

Query string

limit (opcional): Itens por página (1–100, padrão 25).
cursor (opcional): endCursor da página anterior.

Resposta `(publicReviewSchema, item de data[])`

Campo	Tipo	Obrigatório
id	string	sim
rating	inteiro	sim
title	string	sim
body	string	sim
authorName	string	sim
verifiedPurchase	boolean	sim
reply	string \| null	sim
createdAt	string	sim

Exemplo (payload de "data")

{
  "id": "01J0EXEMPLOREVIEW00000000",
  "rating": 5,
  "title": "Excelente",
  "body": "Tecido ótimo, chegou rápido.",
  "authorName": "Ana P.",
  "verifiedPurchase": true,
  "reply": null,
  "createdAt": "2026-07-01T12:00:00.000Z"
}

Além de data/pageInfo, a resposta traz summary (reviewSummarySchema): média, total e contagem por estrela.

POST/storefront/products/:slug/reviewssessão de cliente

Envia avaliação do produto (entra em moderação).

Parâmetros de rota

slug (obrigatório): Slug público do produto.

Body `(submitReviewInputSchema)`

Campo	Tipo	Obrigatório
rating	inteiro	sim
title	string	não
body	string	sim

Exemplo de requisição

{
  "rating": 5,
  "title": "Excelente",
  "body": "Tecido ótimo, chegou rápido."
}

Resposta

{ ok: true, status: "pending" }: publicada após moderação.

Carrinho

O carrinho vive num cookie httpOnly (sameSite: lax) emitido pela API na primeira interação, e por isso o padrão recomendado é um proxy same-origin (BFF) no seu front. Todas as rotas devolvem o carrinho atualizado.

GET/storefront/cart
POST/storefront/cart/items
PATCH/storefront/cart/items/:itemId
DELETE/storefront/cart/items/:itemId
POST/storefront/cart/gift-card
POST/storefront/cart/discount-code
GET/storefront/cart/recover/:token

GET/storefront/cart

Carrinho atual (cria um novo se não houver; emite/renova o cookie).

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

Exemplo (payload de "data")

{
  "id": "01J0EXEMPLOCART0000000000",
  "status": "active",
  "items": [
    {
      "id": "01J0EXEMPLOITEM0000000000",
      "variantId": "01J0EXEMPLOVARIANTE000000",
      "productId": "01J0EXEMPLOPRODUTO0000000",
      "productTitle": "Camiseta Básica",
      "variantTitle": "P",
      "slug": "camiseta-basica",
      "thumbnailUrl": null,
      "unitPriceCents": 7990,
      "quantity": 2,
      "availableQuantity": 12,
      "totalCents": 15980,
      "isGiftCard": false,
      "giftMeta": null
    }
  ],
  "subtotalCents": 15980,
  "contact": null,
  "shippingAddress": null,
  "shippingMethod": null,
  "discount": null,
  "discountError": null,
  "giftCard": null,
  "giftCardError": null,
  "giftCardOnly": false,
  "totalCents": 15980,
  "giftCardAppliedCents": 0,
  "amountDueCents": 15980
}

totalCents é o total do PEDIDO (subtotal − cupom + frete) e **não desconta o cartão-presente**, porque cartão-presente é meio de pagamento, não desconto. O valor que vai ao PSP na conclusão é amountDueCents (= totalCents − giftCardAppliedCents); é ele que a tela deve mostrar como "a pagar".

POST/storefront/cart/items

Adiciona uma variante ao carrinho.

Body `(addCartItemInputSchema)`

Campo	Tipo	Obrigatório
variantId	string	sim
quantity	inteiro	não
gift	objeto \| null	não

Exemplo de requisição

{
  "variantId": "01J0EXEMPLOVARIANTE000000",
  "quantity": 1
}

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

gift (destinatário + mensagem) só se aplica ao produto especial cartão-presente.

PATCH/storefront/cart/items/:itemId

Altera a quantidade de um item.

Parâmetros de rota

itemId (obrigatório): ID do item no carrinho.

Body `(updateCartItemInputSchema)`

Campo	Tipo	Obrigatório
quantity	inteiro	sim

Exemplo de requisição

{
  "quantity": 3
}

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

DELETE/storefront/cart/items/:itemId

Remove um item do carrinho.

Parâmetros de rota

itemId (obrigatório): ID do item no carrinho.

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

POST/storefront/cart/gift-card10 req/min

Aplica (ou remove, com code: null) um cartão-presente como pagamento.

Body `(applyGiftCardInputSchema)`

Campo	Tipo	Obrigatório
code	string \| null	sim

Exemplo de requisição

{
  "code": "ABCD-1234-EFGH-5678"
}

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

Código inválido não é erro HTTP: volta em giftCardError no carrinho.

POST/storefront/cart/discount-code10 req/min

Aplica (ou remove, com code: null) um cupom de desconto.

Body `(applyDiscountCodeInputSchema)`

Campo	Tipo	Obrigatório
code	string \| null	sim

Exemplo de requisição

{
  "code": "BEMVINDO10"
}

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

Cupom inválido não é erro HTTP: volta em discountError no carrinho.

GET/storefront/cart/recover/:token

Recupera um carrinho abandonado pelo link de e-mail (regrava o cookie).

Parâmetros de rota

token (obrigatório): Token do link de recuperação.

Query string

cupom (opcional): Cupom a aplicar junto da recuperação.

Resposta

{ ok: true }

Checkout

Checkout em 3 etapas retomáveis sobre o carrinho: identificação → entrega → conclusão com pagamento. A conclusão revalida preço/estoque e exige o header Idempotency-Key.

POST/storefront/checkout/identification
GET/storefront/checkout/shipping-methods
POST/storefront/checkout/shipping
POST/storefront/checkout/complete
GET/storefront/checkout/payment-config

POST/storefront/checkout/identification

Etapa 1: dados de contato do comprador.

Body `(checkoutIdentificationInputSchema)`

Campo	Tipo	Obrigatório
email	string	sim
firstName	string	sim
lastName	string	não
phone	string	não
cpfCnpj	string	não
company	string	não
birthDate	string	não
acceptsMarketing	boolean	não

Exemplo de requisição

{
  "email": "cliente@example.com",
  "firstName": "Ana",
  "lastName": "Pereira",
  "phone": "(11) 99999-0000"
}

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

Os campos exigidos além de email/firstName são configuráveis pela loja (ex.: telefone e CPF/CNPJ); um 400 devolve details por campo, então trate-os dinamicamente.

GET/storefront/checkout/shipping-methods

Métodos de entrega disponíveis para um CEP (tabela de frete da loja).

Query string

cep (obrigatório): CEP de destino (00000-000).

Resposta `(shippingOptionSchema[])`

Campo	Tipo	Obrigatório
id	string	sim
label	string	sim
priceCents	inteiro	sim
deadlineDays	inteiro \| null	sim
pickup	boolean	sim
carrier	string \| null	não

Exemplo (payload de "data")

[
  {
    "id": "01J0EXEMPLOFRETE000000000",
    "label": "Entrega padrão",
    "priceCents": 1990,
    "deadlineDays": 7,
    "pickup": false
  },
  {
    "id": "pickup",
    "label": "Retirada na loja",
    "priceCents": 0,
    "deadlineDays": null,
    "pickup": true
  }
]

POST/storefront/checkout/shipping

Etapa 2: endereço de entrega e método escolhido.

Body `(checkoutShippingInputSchema)`

Campo	Tipo	Obrigatório
address	objeto	sim
shippingMethodId	string	sim

Exemplo de requisição

{
  "address": {
    "recipientName": "Ana Pereira",
    "cep": "01310-100",
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "ap 42",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  },
  "shippingMethodId": "01J0EXEMPLOFRETE000000000"
}

Resposta `(cartSchema)`

Campo	Tipo	Obrigatório
id	string	sim
status	"active" \| "checkout_started" \| "completed" \| "abandoned" \| "recovered" \| "expired"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
contact	objeto \| null	sim
shippingAddress	objeto \| null	sim
shippingMethod	objeto \| null	sim
discount	objeto \| null	sim
discountError	string \| null	sim
giftCard	objeto \| null	sim
giftCardError	string \| null	sim
giftCardOnly	boolean	sim
totalCents	inteiro	sim
giftCardAppliedCents	inteiro	sim
amountDueCents	inteiro	sim

POST/storefront/checkout/complete10 req/min

Etapa 3: conclui o pedido e inicia o pagamento (Pix, cartão ou boleto).

Headers

Idempotency-Key (obrigatório): Chave única da tentativa (ex.: UUID). Reenvio com a mesma chave devolve a resposta original; payload diferente → 409.

Body `(checkoutCompleteInputSchema)`

Campo	Tipo	Obrigatório
method	"pix" \| "credit_card" \| "boleto"	sim
cardToken	string	não
installments	inteiro	não
acknowledgeChanges	boolean	não

Exemplo de requisição

{
  "method": "pix",
  "installments": 1,
  "acknowledgeChanges": false
}

Resposta `(checkoutCompleteResultSchema)`

Campo	Tipo	Obrigatório
orderId	string	sim
orderNumber	inteiro	sim
status	string	sim
confirmationToken	string	sim
payment	objeto	sim

Exemplo (payload de "data")

{
  "orderId": "01J0EXEMPLOPEDIDO00000000",
  "orderNumber": 1042,
  "status": "pending_payment",
  "confirmationToken": "tKk3f8s2mN4pQ7rW9xZ1aB6c",
  "payment": {
    "method": "pix",
    "status": "pending",
    "pixQrCode": "00020126580014BR.GOV.BCB.PIX...",
    "boletoUrl": null,
    "boletoLine": null,
    "expiresAt": "2026-07-10T12:00:00.000Z"
  }
}

Cartão: envie cardToken gerado client-side pelo provedor (nunca dados crus do cartão).
Divergência de preço/estoque desde que o item entrou no carrinho → 422 com as mudanças; reenvie com acknowledgeChanges: true para aceitar.
Sucesso limpa o cookie do carrinho; use orderId + confirmationToken (?c=) para abrir a confirmação sem expor e-mail na URL (LGPD).

GET/storefront/checkout/payment-config

Config pública de pagamento: métodos ativos, chave pública e parcelamento.

Resposta `(publicPaymentConfigSchema)`

Campo	Tipo	Obrigatório
provider	string	sim
publicKey	string \| null	sim
providerConfig	mapa<string, string \| número \| boolean>	não
methods	"pix" \| "credit_card" \| "boleto"[]	sim
installments	objeto	sim

Exemplo (payload de "data")

{
  "provider": "pagarme",
  "publicKey": "pk_test_exemplo",
  "methods": [
    "pix",
    "credit_card",
    "boleto"
  ],
  "installments": {
    "max": 12,
    "minInstallmentCents": 500
  }
}

Autenticação do cliente

Sessão do cliente final em cookies httpOnly (customer_session ~15 min + customer_refresh rotativo ~30 dias, sameSite: lax). Em 401, chame refresh uma vez e repita a requisição.

POST/storefront/auth/register
POST/storefront/auth/login
POST/storefront/auth/refresh
POST/storefront/auth/logout
POST/storefront/auth/password-reset
POST/storefront/auth/password-reset/confirm
POST/storefront/auth/verify-email
POST/storefront/newsletter
POST/storefront/newsletter/confirm
GET/storefront/unsubscribe/:token
POST/storefront/unsubscribe/:token
GET/storefront/marketing/unsubscribe/:token
POST/storefront/marketing/unsubscribe/:token
GET/storefront/marketing/channels
GET/storefront/marketing/o/:token
GET/storefront/marketing/c/:token
GET/storefront/l/:token

POST/storefront/auth/register10 req/min

Cria a conta do cliente e já emite a sessão (cookies).

Body `(customerRegisterInputSchema)`

Campo	Tipo	Obrigatório
firstName	string	sim
lastName	string	não
email	string	sim
password	string	sim
acceptsMarketing	boolean	não

Exemplo de requisição

{
  "firstName": "Ana",
  "lastName": "Pereira",
  "email": "cliente@example.com",
  "password": "SenhaForte123",
  "acceptsMarketing": true
}

Resposta `(customerProfileSchema)`

Campo	Tipo	Obrigatório
id	string	sim
email	string	sim
firstName	string	sim
lastName	string	sim
phone	string \| null	sim
cpfCnpj	string \| null	sim
acceptsMarketing	boolean	sim
emailVerified	boolean	sim

POST/storefront/auth/login10 req/min

Autentica o cliente e emite a sessão (cookies).

Body `(customerLoginInputSchema)`

Campo	Tipo	Obrigatório
email	string	sim
password	string	sim
turnstileToken	string	não

Exemplo de requisição

{
  "email": "cliente@example.com",
  "password": "SenhaForte123"
}

Resposta `(customerProfileSchema)`

Campo	Tipo	Obrigatório
id	string	sim
email	string	sim
firstName	string	sim
lastName	string	sim
phone	string \| null	sim
cpfCnpj	string \| null	sim
acceptsMarketing	boolean	sim
emailVerified	boolean	sim

Exemplo (payload de "data")

{
  "id": "01J0EXEMPLOCLIENTE0000000",
  "email": "cliente@example.com",
  "firstName": "Ana",
  "lastName": "Pereira",
  "phone": null,
  "cpfCnpj": null,
  "acceptsMarketing": true,
  "emailVerified": false
}

Desafio progressivo (spec 08 RN-11): após 5 falhas do MESMO e-mail em 15 min a conta entra em modo desafio por 15 min. Login correto zera o contador. Os códigos abaixo saem iguais para e-mail inexistente (anti-enumeração).
Em host de subdomínio da plataforma (<slug>.meweb.com.br), o modo desafio exige turnstileToken: sem token → 422 CAPTCHA_REQUIRED (renderize o widget do Cloudflare Turnstile e reenvie); token recusado → 422 CAPTCHA_FAILED (o token é de USO ÚNICO, então peça um novo a cada falha).
Em domínio próprio do lojista, onde o widget do Turnstile não renderiza, o modo desafio limita a 1 tentativa a cada 30 s por e-mail: 429 RATE_LIMITED com Retry-After, antes de verificar a senha.

POST/storefront/auth/refresh

Rotaciona a sessão usando o cookie customer_refresh.

Resposta

{ ok: boolean }, com false quando o refresh expirou (faça login).

POST/storefront/auth/logout

Encerra a sessão e limpa os cookies.

Resposta

{ ok: true }

POST/storefront/auth/password-reset

Solicita redefinição de senha por e-mail (resposta sempre ok).

Body `(customerPasswordResetRequestSchema)`

Campo	Tipo	Obrigatório
email	string	sim

Exemplo de requisição

{
  "email": "cliente@example.com"
}

Resposta

{ ok: true }

POST/storefront/auth/password-reset/confirm

Define a nova senha com o token recebido por e-mail.

Body `(customerPasswordResetConfirmSchema)`

Campo	Tipo	Obrigatório
token	string	sim
password	string	sim

Exemplo de requisição

{
  "token": "token-do-email",
  "password": "NovaSenhaForte123"
}

Resposta

{ ok: true }

POST/storefront/auth/verify-email

Confirma o e-mail do cliente com o token recebido.

Body `({ token: string })`

Campo	Tipo	Obrigatório
token	string	sim

Exemplo de requisição

{
  "token": "token-do-email"
}

Resposta

{ ok: true }

POST/storefront/newsletter

Opt-in de marketing por e-mail (newsletter) com double opt-in: envia link de confirmação, não marca consentimento na hora.

Body `({ email: string })`

Campo	Tipo	Obrigatório
email	string	sim

Exemplo de requisição

{
  "email": "cliente@example.com"
}

Resposta

{ ok: true }

POST/storefront/newsletter/confirm

Confirma o opt-in de marketing com o token recebido por e-mail (double opt-in).

Body `({ token: string })`

Campo	Tipo	Obrigatório
token	string	sim

Exemplo de requisição

{
  "token": "token-do-email"
}

Resposta

{ ok: true }

GET/storefront/unsubscribe/:token

Descadastro de e-mails de marketing (LGPD art. 18 §2) via link do rodapé, com página de confirmação HTML.

Resposta

Página HTML de confirmação do descadastro (pt-BR).

POST/storefront/unsubscribe/:token

Descadastro em um clique (RFC 8058 List-Unsubscribe-Post): marca o cliente como acceptsMarketing=false.

Resposta

{ ok: true }

GET/storefront/marketing/unsubscribe/:token

Descadastro de marketing por token de MENSAGEM (spec 30 RN-03), com página HTML de confirmação, sem login.

Resposta

Página HTML (pt-BR). O token é opaco, emitido por mensagem promocional enviada; token desconhecido recebe resposta neutra.

É o alvo do header List-Unsubscribe dos e-mails promocionais do módulo de marketing (spec 30); o link visível no corpo aponta para a página /descadastrar/:token do storefront, que consome o POST abaixo.

POST/storefront/marketing/unsubscribe/:token

Descadastro em um clique (RFC 8058) do canal de e-mail promocional: revoga o consentimento e derruba as automações do cliente na hora (spec 30 RN-03).

Resposta

{ unsubscribed: boolean }: resposta neutra (HTTP 200) mesmo para token desconhecido ou já usado.

GET/storefront/marketing/channels

Canais promocionais que a loja sabe operar hoje (spec 30 §7): use para só mostrar o opt-in de WhatsApp quando o canal está conectado.

Resposta `(storefrontMarketingChannelsSchema)`

{ whatsappMarketing: boolean }, com true quando a loja tem o WhatsApp conectado. Não expõe número, provedor nem estado da conexão.

Campo	Tipo	Obrigatório
whatsappMarketing	boolean	sim

A caixa "Quero receber ofertas no WhatsApp" do checkout só deve aparecer quando isto for true **e** o cliente tiver telefone: não se pede consentimento para um canal que a loja não sabe usar.

GET/storefront/marketing/o/:token

Pixel de abertura de e-mail promocional (spec 30 RN-23): GIF 1×1 transparente, Cache-Control: no-store.

Resposta

Sempre o GIF (200), token válido ou não, porque pixel não erra. Token válido marca a abertura da mensagem (primeira vez em first_opened_at).

GET/storefront/marketing/c/:token

Clique envelopado de e-mail promocional (spec 30 RN-23): registra o clique e redireciona (302) ao destino.

Resposta

302 para o destino embutido no token assinado; token inválido ou expirado redireciona para a home da loja.

GET/storefront/l/:token

Link curto e opaco da fase 30.4 (spec 30 RN-27/RN-28): 302 para o checkout com o carrinho restaurado ou para a página de pagamento do pedido.

Resposta

302 para o destino resolvido pelo token. Token desconhecido, vencido ou de outra loja leva à página explicativa /l/expirado, nunca a um 4xx, porque quem clicou é um cliente.

A URL não carrega e-mail, id de cliente nem id de carrinho (M26/M28): o token é ULID + HMAC do tenant e todo o resto vive na linha de marketing_short_links.
Quando o carrinho já virou pedido, o link passa a apontar para o pedido (reação a CartRecovered) em vez de recriar um carrinho fantasma.

Conta do cliente

Área logada do cliente final: perfil, endereços, pedidos e cartões-presente. Exigem a sessão de cliente (401 CUSTOMER_UNAUTHENTICATED sem ela).

GET/storefront/account/profile
PATCH/storefront/account/profile
GET/storefront/account/marketing-preferences
PATCH/storefront/account/marketing-preferences
GET/storefront/account/addresses
POST/storefront/account/addresses
PUT/storefront/account/addresses/:id
DELETE/storefront/account/addresses/:id
GET/storefront/account/orders
GET/storefront/account/orders/:number
POST/storefront/account/orders/:number/cancel
GET/storefront/account/gift-cards
GET/storefront/account/export
POST/storefront/account/delete-request
POST/storefront/account/delete-confirm

GET/storefront/account/profilesessão de cliente

Perfil do cliente logado.

Resposta `(customerProfileSchema)`

Campo	Tipo	Obrigatório
id	string	sim
email	string	sim
firstName	string	sim
lastName	string	sim
phone	string \| null	sim
cpfCnpj	string \| null	sim
acceptsMarketing	boolean	sim
emailVerified	boolean	sim

PATCH/storefront/account/profilesessão de cliente

Atualiza dados do perfil.

Body `(updateProfileInputSchema)`

Campo	Tipo	Obrigatório
firstName	string	não
lastName	string	não
phone	string \| null	não
cpfCnpj	string \| null	não
acceptsMarketing	boolean	não

Exemplo de requisição

{
  "firstName": "Ana",
  "phone": "(11) 98888-0000"
}

Resposta `(customerProfileSchema)`

Campo	Tipo	Obrigatório
id	string	sim
email	string	sim
firstName	string	sim
lastName	string	sim
phone	string \| null	sim
cpfCnpj	string \| null	sim
acceptsMarketing	boolean	sim
emailVerified	boolean	sim

GET/storefront/account/marketing-preferencessessão de cliente

Preferências de comunicação do cliente por canal (e-mail / WhatsApp), com estado e pendência de confirmação (spec 30 RN-02).

Resposta `(marketingPreferencesDtoSchema)`

Campo	Tipo	Obrigatório
emailMarketing	objeto	sim
whatsappMarketing	objeto	sim
whatsappAvailable	boolean	não

PATCH/storefront/account/marketing-preferencessessão de cliente

Liga/desliga cada canal: ligar e-mail dispara o double opt-in (só vira granted após confirmação); desligar revoga na hora (spec 30 RN-02/RN-03).

Body `(updateMarketingPreferencesInputSchema)`

Campo	Tipo	Obrigatório
emailMarketing	boolean	não
whatsappMarketing	boolean	não
source	"checkout" \| "account"	não

Resposta `(marketingPreferencesDtoSchema)`

Campo	Tipo	Obrigatório
emailMarketing	objeto	sim
whatsappMarketing	objeto	sim
whatsappAvailable	boolean	não

GET/storefront/account/addressessessão de cliente

Endereços salvos do cliente.

Resposta `(customerAddressSchema[])`

Campo	Tipo	Obrigatório
id	string	sim
label	string \| null	sim
recipientName	string	sim
cep	string	sim
street	string	sim
number	string	sim
complement	string \| null	sim
district	string	sim
city	string	sim
state	string	sim
isDefault	boolean	sim

Exemplo (payload de "data")

[
  {
    "id": "01J0EXEMPLOENDERECO000000",
    "label": "Casa",
    "recipientName": "Ana Pereira",
    "cep": "01310-100",
    "street": "Av. Paulista",
    "number": "1000",
    "complement": null,
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "isDefault": true
  }
]

POST/storefront/account/addressessessão de cliente

Cadastra um endereço.

Body `(upsertAddressInputSchema)`

Campo	Tipo	Obrigatório
label	string \| null	não
recipientName	string	sim
cep	objeto	sim
street	string	sim
number	string	sim
complement	string \| null	não
district	string	sim
city	string	sim
state	"AC" \| "AL" \| "AP" \| "AM" \| "BA" \| "CE" \| "DF" \| "ES" \| "GO" \| "MA" \| "MT" \| "MS" \| "MG" \| "PA" \| "PB" \| "PR" \| "PE" \| "PI" \| "RJ" \| "RN" \| "RS" \| "RO" \| "RR" \| "SC" \| "SP" \| "SE" \| "TO"	sim
isDefault	boolean	não

Exemplo de requisição

{
  "label": "Casa",
  "recipientName": "Ana Pereira",
  "cep": "01310-100",
  "street": "Av. Paulista",
  "number": "1000",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "isDefault": true
}

Resposta `(customerAddressSchema)`

Campo	Tipo	Obrigatório
id	string	sim
label	string \| null	sim
recipientName	string	sim
cep	string	sim
street	string	sim
number	string	sim
complement	string \| null	sim
district	string	sim
city	string	sim
state	string	sim
isDefault	boolean	sim

PUT/storefront/account/addresses/:idsessão de cliente

Atualiza um endereço.

Parâmetros de rota

id (obrigatório): ID do endereço.

Body `(upsertAddressInputSchema)`

Campo	Tipo	Obrigatório
label	string \| null	não
recipientName	string	sim
cep	objeto	sim
street	string	sim
number	string	sim
complement	string \| null	não
district	string	sim
city	string	sim
state	"AC" \| "AL" \| "AP" \| "AM" \| "BA" \| "CE" \| "DF" \| "ES" \| "GO" \| "MA" \| "MT" \| "MS" \| "MG" \| "PA" \| "PB" \| "PR" \| "PE" \| "PI" \| "RJ" \| "RN" \| "RS" \| "RO" \| "RR" \| "SC" \| "SP" \| "SE" \| "TO"	sim
isDefault	boolean	não

Resposta `(customerAddressSchema)`

Campo	Tipo	Obrigatório
id	string	sim
label	string \| null	sim
recipientName	string	sim
cep	string	sim
street	string	sim
number	string	sim
complement	string \| null	sim
district	string	sim
city	string	sim
state	string	sim
isDefault	boolean	sim

DELETE/storefront/account/addresses/:idsessão de cliente

Remove um endereço.

Parâmetros de rota

id (obrigatório): ID do endereço.

Resposta

{ ok: true }

GET/storefront/account/orderssessão de cliente

Pedidos do cliente logado.

Resposta `(accountOrderSchema[])`

Campo	Tipo	Obrigatório
number	inteiro	sim
status	"draft" \| "pending_payment" \| "paid" \| "processing" \| "shipped" \| "delivered" \| "cancelled" \| "refunded"	sim
fulfillmentStatus	"unfulfilled" \| "processing" \| "shipped" \| "delivered"	sim
itemsCount	inteiro	sim
totalCents	inteiro	sim
createdAt	string	sim

Exemplo (payload de "data")

[
  {
    "number": 1042,
    "status": "paid",
    "fulfillmentStatus": "unfulfilled",
    "itemsCount": 2,
    "totalCents": 17970,
    "createdAt": "2026-07-09T12:00:00.000Z"
  }
]

GET/storefront/account/orders/:numbersessão de cliente

Detalhe de um pedido do cliente (itens, entrega, pagamento, rastreio).

Parâmetros de rota

number (obrigatório): Número do pedido.

Resposta `(accountOrderDetailSchema)`

Campo	Tipo	Obrigatório
number	inteiro	sim
status	"draft" \| "pending_payment" \| "paid" \| "processing" \| "shipped" \| "delivered" \| "cancelled" \| "refunded"	sim
fulfillmentStatus	"unfulfilled" \| "processing" \| "shipped" \| "delivered"	sim
items	objeto[]	sim
subtotalCents	inteiro	sim
discountCents	inteiro	sim
shippingCents	inteiro	sim
totalCents	inteiro	sim
shippingAddress	objeto \| null	sim
shippingMethod	string \| null	sim
trackingCode	string \| null	sim
trackingCarrier	string \| null	sim
payment	objeto \| null	sim
payments	objeto[]	sim
canCancel	boolean	sim
createdAt	string	sim

POST/storefront/account/orders/:number/cancelsessão de cliente

Cancela um pedido ainda cancelável pelo cliente.

Parâmetros de rota

number (obrigatório): Número do pedido.

Resposta

{ ok: true }

GET/storefront/account/gift-cardssessão de cliente

Cartões-presente do cliente (saldo e validade).

Resposta `(myGiftCardSchema[])`

Campo	Tipo	Obrigatório
last4	string	sim
status	"pending_activation" \| "active" \| "depleted" \| "expired" \| "disabled"	sim
balanceCents	inteiro	sim
expiresAt	string \| null	sim

Exemplo (payload de "data")

[
  {
    "last4": "5678",
    "status": "active",
    "balanceCents": 5000,
    "expiresAt": null
  }
]

GET/storefront/account/exportsessão de cliente

LGPD arts. 18 II/V e 19: relatório com TUDO o que a loja tem sobre o titular logado: cadastro, endereços, pedidos, consentimentos, mensagens e conversas de WhatsApp.

Query string

format (opcional): json (padrão) ou csv; o CSV vem como anexo meus-dados.csv.

Resposta `(customerDataExportSchema)`

Campo	Tipo	Obrigatório
generatedAt	string	sim
notice	string	sim
subject	objeto	sim
addresses	objeto[]	sim
orders	objeto[]	sim
marketing	objeto	sim
sectionsUnavailable	string[]	sim

Exemplo (payload de "data")

{
  "generatedAt": "2026-08-22T12:00:00.000Z",
  "notice": "Relatório dos dados pessoais que esta loja mantém sobre você…",
  "subject": {
    "id": "01J0EXEMPLOCLIENTE00000000",
    "email": "maria@example.com",
    "firstName": "Maria",
    "lastName": "Silva",
    "phone": "+5511999990000",
    "whatsapp": null,
    "cpfCnpj": "11144477735",
    "emailVerified": true,
    "acceptsMarketing": true,
    "tags": [
      "vip"
    ],
    "note": null,
    "createdAt": "2026-01-10T13:00:00.000Z",
    "ordersCount": 1,
    "totalSpentCents": 15900,
    "lastOrderAt": "2026-08-01T10:00:00.000Z"
  },
  "addresses": [
    {
      "id": "01J0EXEMPLOENDERECO0000000",
      "label": "Casa",
      "recipientName": "Maria Silva",
      "cep": "01310-100",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": null,
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "isDefault": true
    }
  ],
  "orders": [
    {
      "number": 1042,
      "status": "paid",
      "fulfillmentStatus": "shipped",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "paidAt": "2026-08-01T10:05:00.000Z",
      "cancelledAt": null,
      "subtotalCents": 14900,
      "discountCents": 0,
      "shippingCents": 1000,
      "totalCents": 15900,
      "shippingMethod": "PAC",
      "trackingCode": "AA123456789BR",
      "trackingCarrier": "Correios",
      "shippingAddress": {
        "recipientName": "Maria Silva",
        "cep": "01310-100",
        "street": "Av. Paulista",
        "number": "1000",
        "complement": null,
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP"
      },
      "items": [
        {
          "productTitle": "Camiseta",
          "variantTitle": "P / Preta",
          "quantity": 1,
          "unitPriceCents": 14900,
          "totalCents": 14900
        }
      ]
    }
  ],
  "marketing": {
    "consents": [
      {
        "channel": "email_marketing",
        "status": "granted",
        "source": "double_optin",
        "sourceDetail": "checkout",
        "consentText": "Quero receber ofertas, novidades e promoções desta loja por e-mail. Posso cancelar quando quiser.",
        "grantedAt": "2026-01-10T13:05:00.000Z",
        "revokedAt": null,
        "updatedAt": "2026-01-10T13:05:00.000Z"
      }
    ],
    "consentEvents": [
      {
        "channel": "email_marketing",
        "action": "grant",
        "source": "double_optin",
        "sourceDetail": "checkout",
        "consentText": "Quero receber ofertas, novidades e promoções desta loja por e-mail.",
        "occurredAt": "2026-01-10T13:05:00.000Z"
      }
    ],
    "messages": [
      {
        "channel": "email",
        "kind": "promotional",
        "subject": "Novidades da semana",
        "toIdentity": "maria@example.com",
        "status": "sent",
        "sentAt": "2026-02-01T12:00:00.000Z",
        "firstOpenedAt": "2026-02-01T12:30:00.000Z",
        "firstClickedAt": null
      }
    ],
    "whatsappConversations": []
  },
  "sectionsUnavailable": []
}

O escopo é SEMPRE o titular da sessão: a rota não aceita id de cliente, nem no path nem na query.
format=csv NÃO devolve o envelope { data } do doc 04: a resposta é o arquivo (text/csv; charset=utf-8, BOM + ; + CRLF, para abrir direto no Excel pt-BR).
Limite de 5 gerações por hora por titular (429 RATE_LIMITED): o relatório junta todas as seções numa resposta só.
sectionsUnavailable lista as seções que não puderam ser montadas nesta geração; vem vazio no caminho normal, e existe para o arquivo nunca omitir em silêncio.

POST/storefront/account/delete-requestsessão de cliente

LGPD art. 18 V: solicita a exclusão da própria conta; envia link de confirmação por e-mail (resposta sempre ok).

Resposta

{ ok: true }

POST/storefront/account/delete-confirm

Confirma a exclusão da conta com o token do e-mail: anonimiza a conta (RN-07) e derruba a sessão.

Body `({ token: string })`

Campo	Tipo	Obrigatório
token	string	sim

Exemplo de requisição

{
  "token": "token-do-email"
}

Resposta

{ ok: true }

Cartão-presente

Configuração pública do produto cartão-presente da loja.

GET/storefront/gift-card-config

GET/storefront/gift-card-config

Se a loja vende cartão-presente e em quais valores.

Resposta `(publicGiftCardConfigSchema)`

Campo	Tipo	Obrigatório
enabled	boolean	sim
valuesCents	inteiro[]	sim
variants	objeto[]	sim

Exemplo (payload de "data")

{
  "enabled": true,
  "valuesCents": [
    5000,
    10000
  ],
  "variants": [
    {
      "variantId": "01J0EXEMPLOVARIANTEGC0000",
      "valueCents": 5000
    }
  ]
}

Pedido de convidado

Acesso ao pedido sem sessão: confirmação pós-checkout (ID + e-mail) e rastreio público (número + e-mail).

GET/storefront/orders/:id/confirmation
POST/storefront/orders/track

GET/storefront/orders/:id/confirmation

Dados de confirmação do pedido para a tela de obrigado.

Parâmetros de rota

id (obrigatório): orderId devolvido pelo checkout.

Query string

email (obrigatório): E-mail usado na identificação do checkout.

Resposta

{ number, status, subtotalCents, discountCents, discountCode, shippingCents, shippingMethod, giftCardUsedCents, totalCents, payment (resumo com Pix/boleto quando pendente) | null, items: { productTitle, variantTitle, quantity, totalCents }[] }.

O resumo de valores entrou no QA de 2026-08-21 (M1): sem ele a tela de obrigado mostrava itens e Total e a soma não fechava para quem usou cupom ou pagou frete. discountCents soma cupom + desconto manual, como em /storefront/account/orders/:number.
totalCents é o total do PEDIDO, anterior ao cartão-presente (spec 07 RN-05); o que ainda falta pagar é totalCents − giftCardUsedCents.

POST/storefront/orders/track10 req/min

Rastreia um pedido por número + e-mail (spec 01 RN-23).

Body `(trackOrderInputSchema)`

Campo	Tipo	Obrigatório
number	inteiro	sim
email	string	sim

Exemplo de requisição

{
  "number": 1001,
  "email": "cliente@exemplo.com"
}

Resposta `(orderTrackingSchema)`

Campo	Tipo	Obrigatório
number	inteiro	sim
status	"draft" \| "pending_payment" \| "paid" \| "processing" \| "shipped" \| "delivered" \| "cancelled" \| "refunded"	sim
fulfillmentStatus	"unfulfilled" \| "processing" \| "shipped" \| "delivered"	sim
trackingCarrier	string \| null	sim
trackingCode	string \| null	sim
createdAt	string	sim
paidAt	string \| null	sim
shippedAt	string \| null	sim
deliveredAt	string \| null	sim

Exemplo (payload de "data")

{
  "number": 1001,
  "status": "shipped",
  "fulfillmentStatus": "shipped",
  "trackingCarrier": "Correios",
  "trackingCode": "AA123456789BR",
  "createdAt": "2026-02-01T12:00:00.000Z",
  "paidAt": "2026-02-01T12:05:00.000Z",
  "shippedAt": "2026-02-02T09:00:00.000Z",
  "deliveredAt": null
}

Só responde quando o par número + e-mail confere exatamente; qualquer outro caso devolve 404 ORDER_NOT_FOUND genérico (anti-enumeração).
Nunca expõe endereço, itens, valores ou dados do cliente. Consulta sem efeito colateral.

Loja e site

Resposta (publicStoreInfoSchema)

Query string

Resposta

Query string

Resposta

Resposta

Resposta (orderTrackingConfigSchema)

Body (siteUnlockSchema)

Resposta

Parâmetros de rota

Resposta (publicMenuSchema)

Catálogo

Resposta (homeDataSchema)

Parâmetros de rota

Resposta (publicProductSchema)

Query string

Resposta (publicProductCardSchema, item de data[])

Resposta (publicCollectionSchema[])

Parâmetros de rota

Resposta (publicCollectionSchema)

Parâmetros de rota

Query string

Resposta (publicProductCardSchema, item de data[])

Query string

Resposta (Record<variantId, number>)

Páginas institucionais

Resposta ({ title, slug, updatedAt }[])

Query string

Resposta (publicPageResultSchema)

Parâmetros de rota

Resposta (publicPageResultSchema)

Blog

Query string

Resposta (publicBlogListItemDtoSchema, item de data[])

Parâmetros de rota

Query string

Resposta (publicBlogPostResultSchema)

Avaliações

Parâmetros de rota

Query string

Resposta (publicReviewSchema, item de data[])

Parâmetros de rota

Body (submitReviewInputSchema)

Resposta

Carrinho

Resposta (cartSchema)

Body (addCartItemInputSchema)

Resposta (cartSchema)

Parâmetros de rota

Body (updateCartItemInputSchema)

Resposta (cartSchema)

Parâmetros de rota

Resposta (cartSchema)

Body (applyGiftCardInputSchema)

Resposta (cartSchema)

Body (applyDiscountCodeInputSchema)

Resposta (cartSchema)

Parâmetros de rota

Query string

Resposta

Checkout

Body (checkoutIdentificationInputSchema)

Resposta (cartSchema)

Query string

Resposta (shippingOptionSchema[])

Body (checkoutShippingInputSchema)

Resposta (cartSchema)

Headers

Body (checkoutCompleteInputSchema)

Resposta (checkoutCompleteResultSchema)

Resposta (publicPaymentConfigSchema)

Autenticação do cliente

Body (customerRegisterInputSchema)

Resposta (customerProfileSchema)

Body (customerLoginInputSchema)

Resposta (customerProfileSchema)

Resposta

Resposta

Body (customerPasswordResetRequestSchema)

Resposta `(publicStoreInfoSchema)`

Resposta `(orderTrackingConfigSchema)`

Body `(siteUnlockSchema)`

Resposta `(publicMenuSchema)`

Resposta `(homeDataSchema)`

Resposta `(publicProductSchema)`

Resposta `(publicProductCardSchema, item de data[])`

Resposta `(publicCollectionSchema[])`

Resposta `(publicCollectionSchema)`

Resposta `(publicProductCardSchema, item de data[])`

Resposta `(Record<variantId, number>)`

Resposta `({ title, slug, updatedAt }[])`

Resposta `(publicPageResultSchema)`

Resposta `(publicPageResultSchema)`

Resposta `(publicBlogListItemDtoSchema, item de data[])`

Resposta `(publicBlogPostResultSchema)`

Resposta `(publicReviewSchema, item de data[])`

Body `(submitReviewInputSchema)`

Resposta `(cartSchema)`

Body `(addCartItemInputSchema)`

Resposta `(cartSchema)`

Body `(updateCartItemInputSchema)`

Resposta `(cartSchema)`

Resposta `(cartSchema)`

Body `(applyGiftCardInputSchema)`

Resposta `(cartSchema)`

Body `(applyDiscountCodeInputSchema)`

Resposta `(cartSchema)`

Body `(checkoutIdentificationInputSchema)`

Resposta `(cartSchema)`

Resposta `(shippingOptionSchema[])`

Body `(checkoutShippingInputSchema)`

Resposta `(cartSchema)`

Body `(checkoutCompleteInputSchema)`

Resposta `(checkoutCompleteResultSchema)`

Resposta `(publicPaymentConfigSchema)`

Body `(customerRegisterInputSchema)`

Resposta `(customerProfileSchema)`

Body `(customerLoginInputSchema)`

Resposta `(customerProfileSchema)`

Body `(customerPasswordResetRequestSchema)`

Body `(customerPasswordResetConfirmSchema)`

Body `({ token: string })`

Body `({ email: string })`

Body `({ token: string })`

Resposta `(storefrontMarketingChannelsSchema)`

Resposta `(customerProfileSchema)`

Body `(updateProfileInputSchema)`

Resposta `(customerProfileSchema)`

Resposta `(marketingPreferencesDtoSchema)`

Body `(updateMarketingPreferencesInputSchema)`

Resposta `(marketingPreferencesDtoSchema)`

Resposta `(customerAddressSchema[])`

Body `(upsertAddressInputSchema)`

Resposta `(customerAddressSchema)`

Body `(upsertAddressInputSchema)`

Resposta `(customerAddressSchema)`

Resposta `(accountOrderSchema[])`

Resposta `(accountOrderDetailSchema)`

Resposta `(myGiftCardSchema[])`

Resposta `(customerDataExportSchema)`

Body `({ token: string })`

Resposta `(publicGiftCardConfigSchema)`

Body `(trackOrderInputSchema)`

Resposta `(orderTrackingSchema)`