Skip to main content

Task #194881 — Cart API: Endpoint para Adicionar Item a Cart Existente

Task pai: #194881 — [Back] 03 - Cart API: Add Item a cart existente Contexto: US 194871 — MVP Upsell (Pedido)

Status do refinamento: concluido Requisitos EARS: task-194881-cart-api-add-item-requisitos.md Pesquisa tecnica: context/pesquisa-add-recommended-item.md ADRs: ADR-004 · ADR-005 · ADR-006 · ADR-007 · ADR-009

Contexto​

O endpoint POST api/payment/v2/{id}/add-recommended-item do checkout service precisa chamar a Cart API para persistir o novo item no cart. A Cart API nao possui hoje um endpoint de add item a cart existente — itens so sao adicionados na criacao do cart via POST api/cart com JWT Bearer.

Esta task cria o endpoint interno que sera chamado exclusivamente pelo checkout service via ApiKey "internal".

Endpoint​

POST api/cart/{cartId}/items
x-api-key: {internal api key}
Content-Type: application/json

Request body​

{
  "recommendedItemId": 0
}

Body simplificado para apenas recommendedItemId. Todos os dados do item (productId, size, fullPrice, unitPrice, discountType, discountValue, hasEmployeeDiscount) sao resolvidos internamente do CartItemRecommendationModel (ver REQ-03). quantity sempre 1. Sem validacao de estoque neste endpoint.

Autenticacao​

[AllowAnonymous] + [UseApiKey("internal")] — mesmo padrao do POST api/payment/check-payment-flow.
Sem JWT. A chamada vem exclusivamente do checkout service.

Responsabilidades da Cart API​

  1. Buscar o cart pelo cartId (com CartItemRecommendations e CartItems incluidos)
    • Retornar 400 se nao encontrado
    • Retornar 400 se SaleEcommerce == true
  2. Buscar CartRecommendedItem pelo recommendedItemId na colecao do cart
    • Validar que o registro existe → 400 se nao
    • Validar que pertence ao cartId da rota → 400 se nao
    • Validar que CartItemId == null (nao efetivada) → 400 se ja adicionada
    • Validar que FullPrice > 0 e UnitPrice > 0 → 400 se preco invalido
    • Extrair productId, size, fullPrice, unitPrice, discountType, discountValue, hasEmployeeDiscount
  3. Construir CartItemsModel com dados do CartRecommendedItem, FromRecommendation = true, Quantity = 1
  4. Adicionar o item ao cart (CartModel.AddItems)
  5. Recalcular totais do cart (CartModel.CalculateTotal)
  6. Atualizar CartRecommendedItem.CartItemId com o Id do novo CartItemsModel
  7. Persistir cart e recomendacao atualizados, retornar 200

Saida​

  • 200 — item adicionado, cart recalculado e recomendacao marcada como efetivada (sem corpo)
  • 400:
    • Cart nao encontrado
    • Cart com SaleEcommerce == true
    • recommendedItemId ausente, invalido ou <= 0
    • Recomendacao nao encontrada
    • Recomendacao nao pertence ao cartId informado
    • Recomendacao ja efetivada (CartItemId != null)
    • Item com preco invalido (FullPrice <= 0 ou UnitPrice <= 0)
  • 401: ApiKey ausente ou invalida
  • 500: Erro interno

Arquivos desta pasta​

ArquivoDescricao
task-194881-cart-api-add-item.mdEste arquivo — sumario, indice da task e fluxo do endpoint
task-194881-cart-api-add-item-requisitos.mdDocumento de requisitos EARS (pt-BR): REQs, respostas HTTP, questoes fechadas

Questoes abertas​

Nenhuma. Todas as questoes foram fechadas nas sessoes de grilling de 2026-05-14 e 2026-06-17. Ver detalhes em task-194881-cart-api-add-item-requisitos.md.