Adicionar itens ao carrinho

Adiciona um produto, vários produtos de uma vez, um kit ou um mix ao carrinho do cliente ou do visitante.

Estas quatro rotas põem produtos no carrinho. Use POST /cart/items para o botão "Comprar" de uma página de produto, POST /cart/bulk para um formulário de pedido rápido (várias linhas), POST /cart/add-bundle para um kit montado pelo lojista e POST /cart/items/batch para um mix que o comprador montou.

Todas devolvem o carrinho inteiro já atualizado (ou, no caso do bulk, um resultado por linha com o carrinho dentro). Se o mesmo produto, com a mesma variação, as mesmas opções, a mesma observação e a mesma origem de estoque, já estiver no carrinho, a quantidade é somada à linha existente. Se qualquer um desses elementos mudar, nasce uma linha nova.

Cada adição valida as regras do produto: ele precisa estar ativo e à venda, ter seller, ter estoque para a quantidade (somada ao que já está no carrinho), respeitar quantidade mínima, máxima e múltiplo, e a visibilidade por grupo de clientes. O preço da linha é resolvido no servidor (faixas de quantidade, preço B2B); você nunca envia preço, exceto no mix.

Adicionar um item

POST/api/v1/storefront/cart/itemsAutenticada

Adiciona um item ao carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

product_iduuidobrigatório

Produto a adicionar.

quantitynumberobrigatório

Quantidade, maior que zero. Aceita decimais só em produto vendido por peso ou medida; produto vendido por caixa exige número inteiro de caixas. O nome amount também é aceito (compatibilidade com a plataforma anterior); se os dois vierem, vale quantity.

variation_iduuid

Variação do produto, quando ele tem variações.

unified_variation_idinteger

Variação unificada (combinação de atributos, como tamanho e cor), quando o produto usa esse modelo.

optionsarray

Opções escolhidas: [{"option_id":"...","value":"..."}] ou uma lista simples de ids de valor. Cada valor pode somar preço e peso à linha. Combinações diferentes de opções viram linhas diferentes.

notestring

Observação do comprador sobre a linha ("sem cebola"). Faz parte da identidade da linha.

box_idstring

Caixa escolhida, para produto vendido por caixa. Obrigatório nesse caso; sem ele a resposta é 400 com box_required.

warehouse_idstring

Origem do estoque escolhida na página do produto, quando a loja deixa o comprador escolher. Vazio: a loja decide.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/items" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "quantity": 2
}'

Resposta

200Carrinho atualizado

json

{
  "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "session_id": "6f1c3c0e-8f5b-4c3e-9d6a-2b7d0e0f1a11",
  "items": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Notebook Slim Rosa 02373",
      "sku": "SD-002373",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "subtotal": 23000,
  "total": 23000,
  "currency": "BRL"
}

Os campos são os mesmos de Ler o carrinho; aqui a resposta está reduzida.

Adicionar vários itens

POST /cart/bulk adiciona até 50 linhas por chamada. Cada linha é validada sozinha: uma que falha não impede as outras. O resultado separa o que entrou do que não entrou e traz o carrinho final.

POST/api/v1/storefront/cart/bulkAutenticada

Adiciona vários itens de uma vez

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

itemsarrayobrigatório

De 1 a 50 linhas.

items[].product_iduuidobrigatório

Produto.

items[].quantitynumber

Quantidade.

items[].variation_iduuid

Variação, se houver.

items[].unified_variation_idinteger

Variação unificada, se houver.

items[].optionsarray

Opções escolhidas, como em POST /cart/items.

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/bulk" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "quantity": 1
    },
    {
      "product_id": "00000000-0000-0000-0000-000000000000",
      "quantity": 1
    }
  ]
}'

200Resultado por linha

json

{
  "added": [
    {
      "line_id": "e0a45a70-6e1c-4a2b-8f55-1f6a7d3c9b22",
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "name": "Cafeteira Moderno Branco 01426",
      "unit_price": 80990,
      "quantity": 1,
      "total": 80990
    }
  ],
  "failed": [
    {
      "product_id": "00000000-0000-0000-0000-000000000000",
      "reason": "product not found or inactive: 00000000-0000-0000-0000-000000000000"
    }
  ],
  "cart": { "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23", "subtotal": 115490, "total": 115490 }
}

Campos da resposta

addedarray

Linhas que entraram, no formato de linha do carrinho.

failedarray

Linhas recusadas. Cada uma traz product_id e reason (texto do motivo, em inglês).

cartobject

O carrinho depois da operação, como em Ler o carrinho.

Adicionar um kit

Um kit (bundle) é um conjunto de produtos que o lojista vende junto, com desconto. Esta rota adiciona todos os produtos do kit de uma vez e marca cada linha com o bundle_id, para que o desconto do kit seja aplicado em Calcular o carrinho. Exige o módulo de kits ligado na loja; sem ele a resposta é 403 module_disabled.

POST/api/v1/storefront/cart/add-bundleAutenticada

Adiciona um kit ao carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

bundle_iduuidobrigatório

Kit a adicionar.

quantityintegerobrigatório

Quantos kits. Mínimo 1. A quantidade de cada produto é multiplicada por este valor.

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/add-bundle" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "bundle_id": "3b0a4f0e-6a39-4c1f-9d57-0d9e5b1c2a44",
  "quantity": 1
}'

A resposta 200 é o carrinho completo, com uma linha por produto do kit, cada uma com bundle_id.

Adicionar um mix

Um mix é uma combinação de produtos que o próprio comprador monta, por um preço fechado. A vitrine primeiro pede ao módulo de mixes a lista de componentes com o preço de cada um já distribuído, e depois envia essa lista aqui. Exige o módulo de mixes; sem ele a resposta é 403 module_disabled.

POST/api/v1/storefront/cart/items/batchAutenticada

Adiciona ao carrinho um mix de produtos já resolvido

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

mix_iduuidobrigatório

Mix de origem. Todas as linhas criadas recebem esse mix_id.

linesarrayobrigatório

Componentes do mix, no mínimo um.

lines[].product_iduuidobrigatório

Produto do componente.

lines[].quantityintegerobrigatório

Quantidade, mínimo 1 (valores menores são tratados como 1).

lines[].unit_price_centavosintegerobrigatório

Preço unitário do componente em centavos, exatamente como veio na resolução do mix. A API grava este valor na linha sem recalcular.

lines[].component_idstring

Id do componente no mix, para análise.

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/items/batch" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "mix_id": "7d1f3a52-0b8c-4e6d-a2b1-5c4e9f8a1d33",
  "lines": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 1,
      "unit_price_centavos": 9000
    },
    {
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "quantity": 1,
      "unit_price_centavos": 71000
    }
  ]
}'

A resposta 200 é o carrinho completo, com uma linha por componente, cada uma com mix_id. O estoque de cada componente é conferido, mas as linhas de mix não são comparadas com o preço de catálogo no checkout: o valor enviado em unit_price_centavos é o que o comprador paga. Por isso, repasse sempre os valores devolvidos pela resolução do mix, sem alterá-los.

Erros

As quatro rotas usam as mesmas respostas de erro. O corpo é {"error":"<mensagem>"}.

Status	Quando	Mensagem ou código
400	Sem token e sem `X-Session-ID`	`session_id or authentication required`
400	Corpo que não é JSON	`invalid request body`
400	`product_id`, `bundle_id`, `mix_id` ou `lines` ausentes	`product_id is required`, `bundle_id is required`, `mix_id is required`, `lines is required`
400	`quantity` menor ou igual a zero (`/cart/items`)	`quantity must be positive`
400	`items` vazio ou com mais de 50 linhas (`/cart/bulk`)	`items list is required and must not be empty`, `maximum 50 items per bulk add request`
400	Estoque insuficiente	`insufficient stock for 'Notebook Slim Rosa 02373': requested 100002, available 51`, `out of stock`
400	Regra de quantidade do produto	`qty_below_minimum`, `qty_above_maximum`, `qty_not_multiple_of_step`
400	Produto vendido por caixa sem caixa	`box_required`
400	Produto fora do ar ou sem seller	`product_not_yet_available`, `product_not_sellable`, `product_not_available_for_user`, `zero_price_purchase_disabled`, `zero_price_quote_required`
401	A loja não aceita carrinho de visitante	`guest cart is not allowed` (o texto segue com o pedido para entrar na conta)
403	O produto não é entregue na região do comprador	`product_outside_delivery_region`
403	Módulo desligado (`add-bundle`, `items/batch`)	`{"error":"module_disabled","module":"product-bundles"}` ou `"mix-products"`
500	`product_id` inexistente ou inativo em `/cart/items`; kit inexistente ou indisponível; produto inexistente em um mix	`{"error":"failed to add item","detail":"product not found or inactive: ..."}`

Veja também

API atual/Referência completa/Carrinho

Adicionar itens ao carrinho

Adiciona um produto, vários produtos de uma vez, um kit ou um mix ao carrinho do cliente ou do visitante.

Adicionar um item

POST/api/v1/storefront/cart/itemsAutenticada

Adiciona um item ao carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

product_iduuidobrigatório

Produto a adicionar.

quantitynumberobrigatório

variation_iduuid

Variação do produto, quando ele tem variações.

unified_variation_idinteger

Variação unificada (combinação de atributos, como tamanho e cor), quando o produto usa esse modelo.

optionsarray

notestring

Observação do comprador sobre a linha ("sem cebola"). Faz parte da identidade da linha.

box_idstring

Caixa escolhida, para produto vendido por caixa. Obrigatório nesse caso; sem ele a resposta é 400 com box_required.

warehouse_idstring

Origem do estoque escolhida na página do produto, quando a loja deixa o comprador escolher. Vazio: a loja decide.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/items" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "quantity": 2
}'

Resposta

200Carrinho atualizado

json

{
  "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "session_id": "6f1c3c0e-8f5b-4c3e-9d6a-2b7d0e0f1a11",
  "items": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Notebook Slim Rosa 02373",
      "sku": "SD-002373",
      "unit_price": 11500,
      "quantity": 2,
      "total": 23000
    }
  ],
  "subtotal": 23000,
  "total": 23000,
  "currency": "BRL"
}

Os campos são os mesmos de Ler o carrinho; aqui a resposta está reduzida.

Adicionar vários itens

POST/api/v1/storefront/cart/bulkAutenticada

Adiciona vários itens de uma vez

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

itemsarrayobrigatório

De 1 a 50 linhas.

items[].product_iduuidobrigatório

Produto.

items[].quantitynumber

Quantidade.

items[].variation_iduuid

Variação, se houver.

items[].unified_variation_idinteger

Variação unificada, se houver.

items[].optionsarray

Opções escolhidas, como em POST /cart/items.

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/bulk" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "quantity": 1
    },
    {
      "product_id": "00000000-0000-0000-0000-000000000000",
      "quantity": 1
    }
  ]
}'

200Resultado por linha

json

{
  "added": [
    {
      "line_id": "e0a45a70-6e1c-4a2b-8f55-1f6a7d3c9b22",
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "name": "Cafeteira Moderno Branco 01426",
      "unit_price": 80990,
      "quantity": 1,
      "total": 80990
    }
  ],
  "failed": [
    {
      "product_id": "00000000-0000-0000-0000-000000000000",
      "reason": "product not found or inactive: 00000000-0000-0000-0000-000000000000"
    }
  ],
  "cart": { "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23", "subtotal": 115490, "total": 115490 }
}

Campos da resposta

addedarray

Linhas que entraram, no formato de linha do carrinho.

failedarray

Linhas recusadas. Cada uma traz product_id e reason (texto do motivo, em inglês).

cartobject

O carrinho depois da operação, como em Ler o carrinho.

Adicionar um kit

POST/api/v1/storefront/cart/add-bundleAutenticada

Adiciona um kit ao carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

bundle_iduuidobrigatório

Kit a adicionar.

quantityintegerobrigatório

Quantos kits. Mínimo 1. A quantidade de cada produto é multiplicada por este valor.

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/add-bundle" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "bundle_id": "3b0a4f0e-6a39-4c1f-9d57-0d9e5b1c2a44",
  "quantity": 1
}'

A resposta 200 é o carrinho completo, com uma linha por produto do kit, cada uma com bundle_id.

Adicionar um mix

POST/api/v1/storefront/cart/items/batchAutenticada

Adiciona ao carrinho um mix de produtos já resolvido

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

mix_iduuidobrigatório

Mix de origem. Todas as linhas criadas recebem esse mix_id.

linesarrayobrigatório

Componentes do mix, no mínimo um.

lines[].product_iduuidobrigatório

Produto do componente.

lines[].quantityintegerobrigatório

Quantidade, mínimo 1 (valores menores são tratados como 1).

lines[].unit_price_centavosintegerobrigatório

Preço unitário do componente em centavos, exatamente como veio na resolução do mix. A API grava este valor na linha sem recalcular.

lines[].component_idstring

Id do componente no mix, para análise.

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/items/batch" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "mix_id": "7d1f3a52-0b8c-4e6d-a2b1-5c4e9f8a1d33",
  "lines": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 1,
      "unit_price_centavos": 9000
    },
    {
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "quantity": 1,
      "unit_price_centavos": 71000
    }
  ]
}'

Erros

As quatro rotas usam as mesmas respostas de erro. O corpo é {"error":"<mensagem>"}.

Status	Quando	Mensagem ou código
400	Sem token e sem `X-Session-ID`	`session_id or authentication required`
400	Corpo que não é JSON	`invalid request body`
400	`product_id`, `bundle_id`, `mix_id` ou `lines` ausentes	`product_id is required`, `bundle_id is required`, `mix_id is required`, `lines is required`
400	`quantity` menor ou igual a zero (`/cart/items`)	`quantity must be positive`
400	`items` vazio ou com mais de 50 linhas (`/cart/bulk`)	`items list is required and must not be empty`, `maximum 50 items per bulk add request`
400	Estoque insuficiente	`insufficient stock for 'Notebook Slim Rosa 02373': requested 100002, available 51`, `out of stock`
400	Regra de quantidade do produto	`qty_below_minimum`, `qty_above_maximum`, `qty_not_multiple_of_step`
400	Produto vendido por caixa sem caixa	`box_required`
400	Produto fora do ar ou sem seller	`product_not_yet_available`, `product_not_sellable`, `product_not_available_for_user`, `zero_price_purchase_disabled`, `zero_price_quote_required`
401	A loja não aceita carrinho de visitante	`guest cart is not allowed` (o texto segue com o pedido para entrar na conta)
403	O produto não é entregue na região do comprador	`product_outside_delivery_region`
403	Módulo desligado (`add-bundle`, `items/batch`)	`{"error":"module_disabled","module":"product-bundles"}` ou `"mix-products"`
500	`product_id` inexistente ou inativo em `/cart/items`; kit inexistente ou indisponível; produto inexistente em um mix	`{"error":"failed to add item","detail":"product not found or inactive: ..."}`