API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Ler e adicionar à sacola

Lê a sacola do cliente, adiciona um produto (com variação, opções e observação) e adiciona um combo "compre junto".

A sacola (carrinho) da mini-loja pertence ao token. Estas três rotas são o começo de toda compra: ler o que já está lá, pôr um produto e pôr um combo. Toda resposta é a sacola inteira já recalculada, então você não precisa reler depois de uma alteração.

Se a loja só mostra preço depois do login, os valores voltam zerados e a sacola traz price_redacted: true.

Ler a sacola

GET/api/v1/storefront/wa-coex/cart/{token}Pública

Lê a sacola atual do cliente

Cria a sacola vazia na primeira leitura. Linhas de produtos que saíram de venda continuam na resposta com unavailable: true, para o cliente poder removê-las.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN"

Resposta

200Sacola com uma linha

json

{
  "cart_id": "c8a36455-37a0-4d82-bb9b-895931af38ce",
  "items": [
    {
      "item_id": "31d7324a-e81b-4221-a955-66415cb9d83b",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa",
      "image_url": "/uploads/exemplo/notebook.png",
      "unit_price_cents": 9200,
      "list_price_cents": 12345,
      "quantity": 2,
      "sale_unit": "un",
      "line_total_cents": 18400,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "quantity_step": 1,
      "min_quantity": 1,
      "stock_status": "ok"
    }
  ],
  "subtotal_cents": 18400,
  "total_cents": 18400,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 2,
  "gross_subtotal_cents": 23000,
  "cart_promotion_discount_cents": 1150,
  "cart_promotions": [{ "name": "Progressiva 5% acima de R$ 100", "discount_cents": 1150 }]
}

Campos da resposta

cart_iduuid

Id da sacola.

itemsarray

Linhas da sacola. Veja os campos de cada linha abaixo. [] quando vazia.

subtotal_centsinteger

Soma das linhas, em centavos, já com o desconto de combo.

total_centsinteger

Total da sacola em centavos. Não desconta cupom nem promoção de carrinho: veja a conta em Sacola e checkout.

gross_subtotal_centsinteger

Subtotal antes de qualquer desconto. É a base do "frete grátis acima de". Omitido quando 0.

currencystring

Sempre BRL.

item_countnumber

Soma das quantidades de todas as linhas.

supports_line_selectionboolean

true quando shipping, totals, validate e checkout aceitam line_ids (pagar só parte da sacola).

price_redactedboolean

true quando a loja esconde preço até o cliente entrar. Omitido quando false.

coupon_codestring

Cupom aplicado na sacola. Omitido sem cupom.

discount_centsinteger

Desconto do cupom em centavos. Omitido quando 0.

coupon_noticestring

Texto em português dizendo por que um cupom que estava na sacola saiu (desativado, vencido, esgotado).

bundle_discount_centsinteger

Desconto de combo, já abatido das linhas e do total.

cart_promotion_discount_centsinteger

Desconto das promoções automáticas da loja. Não está dentro de total_cents.

cart_promotionsarray

Promoções automáticas aplicadas: name e discount_cents.

min_order_centsinteger

Pedido mínimo do destino da sacola, em centavos. Omitido quando não há mínimo conhecido.

Campos de cada linha de items

item_iduuid

Id da linha. Use-o para alterar e remover.

product_iduuid

Produto da linha.

variant_iduuid

Variação, quando a linha vem de um produto com variação por produto-filho.

namestring

Nome do produto.

variation_labelstring

Texto das escolhas do cliente, por exemplo Ponto: Ao ponto, Adicionais: Bacon.

image_urlstring

Foto do produto.

unit_price_centsinteger

Preço unitário do cliente, em centavos.

list_price_centsinteger

Preço "de" (tabela), riscado ao lado do preço. Omitido quando não há preço de referência.

quantitynumber

Quantidade. Pode ser fracionada (produto vendido por peso).

sale_unitstring

Unidade de venda (un, kg...). sale_unit_label traz o texto para exibir.

line_total_centsinteger

Total da linha em centavos.

notestring

Observação do cliente para a linha.

vendor_iduuid

Seller (lojista) dono do produto. vendor_name traz o nome.

boxobject

Embalagem escolhida (box_type, box_id), quando o produto vende por caixa.

unavailableboolean

true quando o produto deixou de ser vendido no canal.

origin_warehouse_iduuid

Depósito de origem. origin_label traz o nome. Só em lojas que mostram a origem do estoque.

bundle_idstring

A linha veio de um combo e divide o desconto dele.

mix_idstring

A linha pertence a um mix cujo preço depende das outras linhas.

is_giftboolean

Brinde concedido pela sacola.

optionsarray

Opções escolhidas (option_id, value).

pending_choicesarray

Nomes das opções obrigatórias que ainda faltam. O checkout recusa enquanto houver.

max_quantitynumber

Máximo permitido na linha (o menor entre o produto, o limite da loja e a regra do canal). Omitido quando não há limite.

quantity_stepnumber

Passo de quantidade. min_quantity é o mínimo.

stock_statusstring

oklimitedout

ok, limited (estoque menor que a quantidade) ou out. Com limited e out, available_qty diz quanto dá para comprar.

Erros

Status	Quando	Corpo
403	Loja só mostra o catálogo depois do login.	`{"error":"account_required","message":"Entre ou crie sua conta para ver os produtos e fazer seu pedido."}`
403	A porta de entrada por CNPJ está fechada para o token.	`{"error":"entry_required"}`
409	Uma linha ficou indisponível e a leitura estrita falhou.	`{"error":"<texto>"}`
502	Falha ao montar a sacola.	`{"error":"<texto>"}`

Erros comuns de token (401, 403 web preview disabled, 409 tenant_mismatch) estão em Mini-loja do WhatsApp.

Adicionar um produto

POST/api/v1/storefront/wa-coex/cart/{token}/itemsPública

Adiciona um produto à sacola

Se o mesmo produto, com as mesmas escolhas, já está na sacola, a quantidade é somada na linha existente. A rota confere, no servidor, produto, estoque, área de entrega, opções obrigatórias e regras de pedido, mesmo que o seu front-end já tenha conferido.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_iduuidobrigatório

Produto a adicionar.

qtynumberpadrão: 1

Quantidade, maior que 0. Aceita fração para produto vendido por peso. Ausente vale 1.

variant_iduuid

Produto-filho (variação) quando a loja modela variação como produto separado. Com variant_id, as opções não são validadas.

optionsarray

Opções escolhidas, lista de objetos {"option_id": "...", "value": "..."}. Obrigatórias quando o produto tem opção obrigatória.

configurationobject

Escolhas de variação e caixa (selections, box_type, box_id). Formato em Variação e frete.

warehouse_iduuid

Depósito de origem escolhido na ficha. Só vale em lojas que mostram a origem do estoque.

notestring

Observação do cliente para a linha, até 280 caracteres. Texto vazio não apaga uma observação existente.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","qty":2,"note":"embrulhar para presente"}'

Resposta

200Sacola atualizada

json

{
  "cart_id": "c8a36455-37a0-4d82-bb9b-895931af38ce",
  "items": [
    { "item_id": "31d7324a-e81b-4221-a955-66415cb9d83b", "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "name": "Notebook Slim Rosa", "unit_price_cents": 9200, "quantity": 2, "line_total_cents": 18400, "note": "embrulhar para presente", "stock_status": "ok" }
  ],
  "subtotal_cents": 18400,
  "total_cents": 18400,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 2
}

A resposta tem o mesmo formato de Ler a sacola.

Erros

Status	Quando	Corpo
400	Corpo ilegível ou sem `product_id`.	`{"error":"product_id required"}`
400	`qty` zero, negativa ou que não é número.	`{"error":"invalid_qty"}`
403	A loja exige conta para mexer na sacola.	`{"error":"account_required","message":"Entre ou crie sua conta para adicionar produtos."}`
404	Produto inexistente, escondido ou fora do canal.	`{"error":"product_not_found","message":"Produto indisponível"}`
409	O seller não entrega na área do cliente.	`{"error":"outside_delivery_area","message":"..."}`
409	Estoque ou limite por cliente estourado.	`{"error":"insufficient_stock","message":"..."}`
409	Produto com data de lançamento no futuro.	`{"error":"product_not_yet_available","message":"Este produto ainda não está disponível. Volte a partir da data de lançamento."}`
409	Regra de pedido da loja recusou (código próprio da regra).	`{"error":"<codigo>","message":"..."}`
409	Depósito sem estoque (`warehouse_id`).	`{"error":"insufficient_stock","message":"..."}`
422	Opção obrigatória faltando.	`{"error":"missing_required_options","message":"Escolha: Ponto da carne"}`
422	Opção que não existe mais no produto.	`{"error":"invalid_options","message":"Escolha uma opção disponível para este produto."}`
422	Quantidade de escolhas fora do mínimo ou máximo do grupo.	`{"error":"option_count_out_of_range","message":"Ajuste suas escolhas: ..."}`
422	Combinação de variação inválida ou incompleta.	`{"error":"invalid_configuration","message":"Escolha uma combinação disponível para este produto."}`
422	`warehouse_id` desconhecido.	`{"error":"invalid_origin","message":"Escolha um depósito disponível para este produto."}`

Adicionar um combo

POST/api/v1/storefront/wa-coex/cart/{token}/comboPública

Adiciona o combo compre junto de um produto

O "compre junto" é um conjunto de produtos que o seller vende com desconto. Esta rota coloca todos os itens do combo de uma vez; o desconto aparece em bundle_discount_cents. As linhas do combo carregam o mesmo bundle_id, e ao pagar só parte da sacola (line_ids) o combo vai inteiro ou nenhum (veja Frete e totais). Para descobrir o combo de um produto, use GET /product/{token}/{productID}/combo.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_iduuidobrigatório

Produto da ficha onde o combo foi oferecido.

bundle_idstring

Id do combo, quando o produto participa de mais de um. Ausente usa o combo vigente do produto.

Responde 200 com a sacola completa, no mesmo formato de Ler a sacola. A funcionalidade "compre junto" precisa estar ligada na loja (wa.pdp.buy_together em store_caps).

Erros

Status	Quando	Corpo
400	Corpo ilegível ou sem `product_id`.	`{"error":"product_id required"}`
403	Catálogo fechado para o token.	`{"error":"account_required","message":"..."}` ou `{"error":"entry_required"}`
409	O produto não tem combo vigente.	`{"error":"combo_unavailable","message":"Esse combo não está disponível agora."}`
502	Falha ao adicionar.	`{"error":"<texto>"}`

Veja também

Alterar itens da sacola
Cupom e cashback
Favoritos: "Adicionar todos à sacola"

API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Ler e adicionar à sacola

Lê a sacola do cliente, adiciona um produto (com variação, opções e observação) e adiciona um combo "compre junto".

Se a loja só mostra preço depois do login, os valores voltam zerados e a sacola traz price_redacted: true.

Ler a sacola

GET/api/v1/storefront/wa-coex/cart/{token}Pública

Lê a sacola atual do cliente

Cria a sacola vazia na primeira leitura. Linhas de produtos que saíram de venda continuam na resposta com unavailable: true, para o cliente poder removê-las.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN"

Resposta

200Sacola com uma linha

json

{
  "cart_id": "c8a36455-37a0-4d82-bb9b-895931af38ce",
  "items": [
    {
      "item_id": "31d7324a-e81b-4221-a955-66415cb9d83b",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa",
      "image_url": "/uploads/exemplo/notebook.png",
      "unit_price_cents": 9200,
      "list_price_cents": 12345,
      "quantity": 2,
      "sale_unit": "un",
      "line_total_cents": 18400,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "quantity_step": 1,
      "min_quantity": 1,
      "stock_status": "ok"
    }
  ],
  "subtotal_cents": 18400,
  "total_cents": 18400,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 2,
  "gross_subtotal_cents": 23000,
  "cart_promotion_discount_cents": 1150,
  "cart_promotions": [{ "name": "Progressiva 5% acima de R$ 100", "discount_cents": 1150 }]
}

Campos da resposta

cart_iduuid

Id da sacola.

itemsarray

Linhas da sacola. Veja os campos de cada linha abaixo. [] quando vazia.

subtotal_centsinteger

Soma das linhas, em centavos, já com o desconto de combo.

total_centsinteger

Total da sacola em centavos. Não desconta cupom nem promoção de carrinho: veja a conta em Sacola e checkout.

gross_subtotal_centsinteger

Subtotal antes de qualquer desconto. É a base do "frete grátis acima de". Omitido quando 0.

currencystring

Sempre BRL.

item_countnumber

Soma das quantidades de todas as linhas.

supports_line_selectionboolean

true quando shipping, totals, validate e checkout aceitam line_ids (pagar só parte da sacola).

price_redactedboolean

true quando a loja esconde preço até o cliente entrar. Omitido quando false.

coupon_codestring

Cupom aplicado na sacola. Omitido sem cupom.

discount_centsinteger

Desconto do cupom em centavos. Omitido quando 0.

coupon_noticestring

Texto em português dizendo por que um cupom que estava na sacola saiu (desativado, vencido, esgotado).

bundle_discount_centsinteger

Desconto de combo, já abatido das linhas e do total.

cart_promotion_discount_centsinteger

Desconto das promoções automáticas da loja. Não está dentro de total_cents.

cart_promotionsarray

Promoções automáticas aplicadas: name e discount_cents.

min_order_centsinteger

Pedido mínimo do destino da sacola, em centavos. Omitido quando não há mínimo conhecido.

Campos de cada linha de items

item_iduuid

Id da linha. Use-o para alterar e remover.

product_iduuid

Produto da linha.

variant_iduuid

Variação, quando a linha vem de um produto com variação por produto-filho.

namestring

Nome do produto.

variation_labelstring

Texto das escolhas do cliente, por exemplo Ponto: Ao ponto, Adicionais: Bacon.

image_urlstring

Foto do produto.

unit_price_centsinteger

Preço unitário do cliente, em centavos.

list_price_centsinteger

Preço "de" (tabela), riscado ao lado do preço. Omitido quando não há preço de referência.

quantitynumber

Quantidade. Pode ser fracionada (produto vendido por peso).

sale_unitstring

Unidade de venda (un, kg...). sale_unit_label traz o texto para exibir.

line_total_centsinteger

Total da linha em centavos.

notestring

Observação do cliente para a linha.

vendor_iduuid

Seller (lojista) dono do produto. vendor_name traz o nome.

boxobject

Embalagem escolhida (box_type, box_id), quando o produto vende por caixa.

unavailableboolean

true quando o produto deixou de ser vendido no canal.

origin_warehouse_iduuid

Depósito de origem. origin_label traz o nome. Só em lojas que mostram a origem do estoque.

bundle_idstring

A linha veio de um combo e divide o desconto dele.

mix_idstring

A linha pertence a um mix cujo preço depende das outras linhas.

is_giftboolean

Brinde concedido pela sacola.

optionsarray

Opções escolhidas (option_id, value).

pending_choicesarray

Nomes das opções obrigatórias que ainda faltam. O checkout recusa enquanto houver.

max_quantitynumber

Máximo permitido na linha (o menor entre o produto, o limite da loja e a regra do canal). Omitido quando não há limite.

quantity_stepnumber

Passo de quantidade. min_quantity é o mínimo.

stock_statusstring

oklimitedout

ok, limited (estoque menor que a quantidade) ou out. Com limited e out, available_qty diz quanto dá para comprar.

Erros

Status	Quando	Corpo
403	Loja só mostra o catálogo depois do login.	`{"error":"account_required","message":"Entre ou crie sua conta para ver os produtos e fazer seu pedido."}`
403	A porta de entrada por CNPJ está fechada para o token.	`{"error":"entry_required"}`
409	Uma linha ficou indisponível e a leitura estrita falhou.	`{"error":"<texto>"}`
502	Falha ao montar a sacola.	`{"error":"<texto>"}`

Erros comuns de token (401, 403 web preview disabled, 409 tenant_mismatch) estão em Mini-loja do WhatsApp.

Adicionar um produto

POST/api/v1/storefront/wa-coex/cart/{token}/itemsPública

Adiciona um produto à sacola

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_iduuidobrigatório

Produto a adicionar.

qtynumberpadrão: 1

Quantidade, maior que 0. Aceita fração para produto vendido por peso. Ausente vale 1.

variant_iduuid

Produto-filho (variação) quando a loja modela variação como produto separado. Com variant_id, as opções não são validadas.

optionsarray

Opções escolhidas, lista de objetos {"option_id": "...", "value": "..."}. Obrigatórias quando o produto tem opção obrigatória.

configurationobject

Escolhas de variação e caixa (selections, box_type, box_id). Formato em Variação e frete.

warehouse_iduuid

Depósito de origem escolhido na ficha. Só vale em lojas que mostram a origem do estoque.

notestring

Observação do cliente para a linha, até 280 caracteres. Texto vazio não apaga uma observação existente.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","qty":2,"note":"embrulhar para presente"}'

Resposta

200Sacola atualizada

json

{
  "cart_id": "c8a36455-37a0-4d82-bb9b-895931af38ce",
  "items": [
    { "item_id": "31d7324a-e81b-4221-a955-66415cb9d83b", "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "name": "Notebook Slim Rosa", "unit_price_cents": 9200, "quantity": 2, "line_total_cents": 18400, "note": "embrulhar para presente", "stock_status": "ok" }
  ],
  "subtotal_cents": 18400,
  "total_cents": 18400,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 2
}

A resposta tem o mesmo formato de Ler a sacola.

Erros

Status	Quando	Corpo
400	Corpo ilegível ou sem `product_id`.	`{"error":"product_id required"}`
400	`qty` zero, negativa ou que não é número.	`{"error":"invalid_qty"}`
403	A loja exige conta para mexer na sacola.	`{"error":"account_required","message":"Entre ou crie sua conta para adicionar produtos."}`
404	Produto inexistente, escondido ou fora do canal.	`{"error":"product_not_found","message":"Produto indisponível"}`
409	O seller não entrega na área do cliente.	`{"error":"outside_delivery_area","message":"..."}`
409	Estoque ou limite por cliente estourado.	`{"error":"insufficient_stock","message":"..."}`
409	Produto com data de lançamento no futuro.	`{"error":"product_not_yet_available","message":"Este produto ainda não está disponível. Volte a partir da data de lançamento."}`
409	Regra de pedido da loja recusou (código próprio da regra).	`{"error":"<codigo>","message":"..."}`
409	Depósito sem estoque (`warehouse_id`).	`{"error":"insufficient_stock","message":"..."}`
422	Opção obrigatória faltando.	`{"error":"missing_required_options","message":"Escolha: Ponto da carne"}`
422	Opção que não existe mais no produto.	`{"error":"invalid_options","message":"Escolha uma opção disponível para este produto."}`
422	Quantidade de escolhas fora do mínimo ou máximo do grupo.	`{"error":"option_count_out_of_range","message":"Ajuste suas escolhas: ..."}`
422	Combinação de variação inválida ou incompleta.	`{"error":"invalid_configuration","message":"Escolha uma combinação disponível para este produto."}`
422	`warehouse_id` desconhecido.	`{"error":"invalid_origin","message":"Escolha um depósito disponível para este produto."}`

Adicionar um combo

POST/api/v1/storefront/wa-coex/cart/{token}/comboPública

Adiciona o combo compre junto de um produto

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_iduuidobrigatório

Produto da ficha onde o combo foi oferecido.

bundle_idstring

Id do combo, quando o produto participa de mais de um. Ausente usa o combo vigente do produto.

Responde 200 com a sacola completa, no mesmo formato de Ler a sacola. A funcionalidade "compre junto" precisa estar ligada na loja (wa.pdp.buy_together em store_caps).

Erros

Status	Quando	Corpo
400	Corpo ilegível ou sem `product_id`.	`{"error":"product_id required"}`
403	Catálogo fechado para o token.	`{"error":"account_required","message":"..."}` ou `{"error":"entry_required"}`
409	O produto não tem combo vigente.	`{"error":"combo_unavailable","message":"Esse combo não está disponível agora."}`
502	Falha ao adicionar.	`{"error":"<texto>"}`

Veja também

Alterar itens da sacola
Cupom e cashback
Favoritos: "Adicionar todos à sacola"