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

Alterar itens da sacola

Muda a quantidade de uma linha, troca variação, opções e observação, ou remove a linha da sacola.

Depois de um item entrar na sacola, ele é identificado pelo item_id da linha. As três rotas abaixo recebem esse item_id no caminho e respondem com a sacola inteira, no formato de Ler a sacola.

Use o item_id, não o product_id: o mesmo produto pode ocupar linhas diferentes (variações, opções, observações). O product_id só é aceito no caminho quando o produto aparece em uma única linha.

Mudar a quantidade

PATCH/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}Pública

Define a nova quantidade de uma linha

A quantidade enviada substitui a anterior (não soma). qty: 0 remove a linha. Aumentar acima do estoque ou do limite por cliente é recusado com 409.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

itemIDstringobrigatório

item_id da linha (UUID).

Corpo da requisição

qtynumberobrigatório

Nova quantidade, de 0 a 1.000.000. Aceita fração para produto vendido por peso. Respeite quantity_step, min_quantity e max_quantity da linha.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items/31d7324a-e81b-4221-a955-66415cb9d83b" \
  -H "Content-Type: application/json" \
  -d '{"qty":3}'

Resposta

200Sacola com a linha alterada

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": 3, "line_total_cents": 27600, "stock_status": "ok" }
  ],
  "subtotal_cents": 27600,
  "total_cents": 27600,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 3
}

Erros

Status	Quando	Corpo
400	`qty` ausente, nula, negativa, maior que 1.000.000 ou que não é número.	`{"error":"invalid_qty"}`
403	A loja exige conta para alterar a sacola.	`{"error":"account_required","message":"Entre ou crie sua conta para alterar a sacola."}`
404	A linha já não está na sacola (toque duplo, outra aba, id velho).	`{"error":"item_not_in_cart","message":"Esse item já não está no carrinho."}`
409	Estoque ou limite por cliente estourado.	`{"error":"insufficient_stock","message":"..."}`
409	Uma linha da sacola ficou indisponível e a releitura falhou.	`{"error":"<texto>"}`
500	Falha inesperada.	`{"error":"<texto>"}`

Trocar variação, opções e observação

PUT/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}/configurationPública

Reconfigura uma linha: variação, opções, quantidade e observação

É a tela "editar item" da sacola. A linha é substituída pelo produto, configuração e opções enviados, sem duplicar nem perder o lugar. Envie sempre o conjunto completo de escolhas, não só o que mudou. A observação só muda se o campo note for enviado; "" apaga a observação.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

itemIDstringobrigatório

item_id da linha a reconfigurar.

Corpo da requisição

product_iduuidobrigatório

Produto da linha depois da troca (o mesmo de antes, quando só muda a opção).

qtynumberpadrão: 1

Quantidade da linha, maior que 0. Ausente vale 1. Aqui 0 não remove: use DELETE.

optionsarray

Opções escolhidas (option_id, value). Mesmas regras de Adicionar um produto.

configurationobject

Escolhas de variação e caixa (selections, box_type, box_id).

notestring

Observação da linha, até 280 caracteres. "" apaga; ausente mantém.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items/31d7324a-e81b-4221-a955-66415cb9d83b/configuration" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","qty":1,"note":"embrulhar"}'

Resposta

200Sacola com a linha reconfigurada

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": 1, "line_total_cents": 9200, "note": "embrulhar", "stock_status": "ok" }
  ],
  "subtotal_cents": 9200,
  "total_cents": 9200,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 1
}

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"}`
404	A linha não está na sacola.	`{"error":"item_not_in_cart","message":"Esse item já não está no carrinho."}`
404	O produto saiu de venda.	`{"error":"product_not_found","message":"Produto indisponível"}`
409	Estoque ou limite por cliente estourado.	`{"error":"insufficient_stock","message":"..."}`
422	Opção obrigatória faltando, inexistente ou fora do mínimo e máximo.	`{"error":"missing_required_options"}`, `{"error":"invalid_options"}` ou `{"error":"option_count_out_of_range"}`, todos com `message` em português
422	Combinação de variação inválida.	`{"error":"invalid_configuration","message":"Escolha uma combinação disponível para este produto."}`
502	Falha ao ler a sacola.	`{"error":"<texto>"}`

Remover uma linha

DELETE/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}Pública

Remove uma linha da sacola

Remove a linha e devolve a sacola que sobrou. Se a linha veio de um combo (bundle_id), releia o desconto na resposta: bundle_discount_cents é recalculado.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

itemIDstringobrigatório

item_id da linha a remover.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items/31d7324a-e81b-4221-a955-66415cb9d83b"

Resposta

200Sacola depois da remoção

json

{
  "cart_id": "c8a36455-37a0-4d82-bb9b-895931af38ce",
  "items": [],
  "subtotal_cents": 0,
  "total_cents": 0,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 0
}

Erros

Status	Quando	Corpo
404	A linha já não está na sacola. Repetir o `DELETE` cai aqui.	`{"error":"item_not_in_cart","message":"Esse item já não está no carrinho."}`
500	Falha inesperada.	`{"error":"<texto>"}`

Veja também

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

Alterar itens da sacola

Muda a quantidade de uma linha, troca variação, opções e observação, ou remove a linha da sacola.

Mudar a quantidade

PATCH/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}Pública

Define a nova quantidade de uma linha

A quantidade enviada substitui a anterior (não soma). qty: 0 remove a linha. Aumentar acima do estoque ou do limite por cliente é recusado com 409.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

itemIDstringobrigatório

item_id da linha (UUID).

Corpo da requisição

qtynumberobrigatório

Nova quantidade, de 0 a 1.000.000. Aceita fração para produto vendido por peso. Respeite quantity_step, min_quantity e max_quantity da linha.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items/31d7324a-e81b-4221-a955-66415cb9d83b" \
  -H "Content-Type: application/json" \
  -d '{"qty":3}'

Resposta

200Sacola com a linha alterada

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": 3, "line_total_cents": 27600, "stock_status": "ok" }
  ],
  "subtotal_cents": 27600,
  "total_cents": 27600,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 3
}

Erros

Status	Quando	Corpo
400	`qty` ausente, nula, negativa, maior que 1.000.000 ou que não é número.	`{"error":"invalid_qty"}`
403	A loja exige conta para alterar a sacola.	`{"error":"account_required","message":"Entre ou crie sua conta para alterar a sacola."}`
404	A linha já não está na sacola (toque duplo, outra aba, id velho).	`{"error":"item_not_in_cart","message":"Esse item já não está no carrinho."}`
409	Estoque ou limite por cliente estourado.	`{"error":"insufficient_stock","message":"..."}`
409	Uma linha da sacola ficou indisponível e a releitura falhou.	`{"error":"<texto>"}`
500	Falha inesperada.	`{"error":"<texto>"}`

Trocar variação, opções e observação

PUT/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}/configurationPública

Reconfigura uma linha: variação, opções, quantidade e observação

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

itemIDstringobrigatório

item_id da linha a reconfigurar.

Corpo da requisição

product_iduuidobrigatório

Produto da linha depois da troca (o mesmo de antes, quando só muda a opção).

qtynumberpadrão: 1

Quantidade da linha, maior que 0. Ausente vale 1. Aqui 0 não remove: use DELETE.

optionsarray

Opções escolhidas (option_id, value). Mesmas regras de Adicionar um produto.

configurationobject

Escolhas de variação e caixa (selections, box_type, box_id).

notestring

Observação da linha, até 280 caracteres. "" apaga; ausente mantém.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items/31d7324a-e81b-4221-a955-66415cb9d83b/configuration" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","qty":1,"note":"embrulhar"}'

Resposta

200Sacola com a linha reconfigurada

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": 1, "line_total_cents": 9200, "note": "embrulhar", "stock_status": "ok" }
  ],
  "subtotal_cents": 9200,
  "total_cents": 9200,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 1
}

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"}`
404	A linha não está na sacola.	`{"error":"item_not_in_cart","message":"Esse item já não está no carrinho."}`
404	O produto saiu de venda.	`{"error":"product_not_found","message":"Produto indisponível"}`
409	Estoque ou limite por cliente estourado.	`{"error":"insufficient_stock","message":"..."}`
422	Opção obrigatória faltando, inexistente ou fora do mínimo e máximo.	`{"error":"missing_required_options"}`, `{"error":"invalid_options"}` ou `{"error":"option_count_out_of_range"}`, todos com `message` em português
422	Combinação de variação inválida.	`{"error":"invalid_configuration","message":"Escolha uma combinação disponível para este produto."}`
502	Falha ao ler a sacola.	`{"error":"<texto>"}`

Remover uma linha

DELETE/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}Pública

Remove uma linha da sacola

Remove a linha e devolve a sacola que sobrou. Se a linha veio de um combo (bundle_id), releia o desconto na resposta: bundle_discount_cents é recalculado.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

itemIDstringobrigatório

item_id da linha a remover.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/items/31d7324a-e81b-4221-a955-66415cb9d83b"

Resposta

200Sacola depois da remoção

json

{
  "cart_id": "c8a36455-37a0-4d82-bb9b-895931af38ce",
  "items": [],
  "subtotal_cents": 0,
  "total_cents": 0,
  "supports_line_selection": true,
  "currency": "BRL",
  "item_count": 0
}

Erros

Status	Quando	Corpo
404	A linha já não está na sacola. Repetir o `DELETE` cai aqui.	`{"error":"item_not_in_cart","message":"Esse item já não está no carrinho."}`
500	Falha inesperada.	`{"error":"<texto>"}`