Skip to main content

Task #194880 — Criar endpoint para Adicionar um novo item recomendado no pedido

Task pai: #194880 — [Back] 02 - Adicionar item recomendado Contexto: US 194871 — MVP Upsell (Pedido)

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

Resumo​

Criar endpoint POST api/payment/v2/{id}/add-recommended-item para permitir que a cliente, via zzlink, adicione um item recomendado pelo vendedor ao pedido em andamento.

O handler orquestra: validacao do payment (store only), validacao da recomendacao (existe, pertence ao cart, dentro da janela de 1h), chamada a Cart API para adicionar o item, atualizacao sincrona do Payment.Total, e auditoria via alllogs.

Criar endpoint para Adicionar um novo item recomendado no pedido​

Endpoint​

POST api/payment/v2/{id}/add-recommended-item
Authorization: Bearer {token PaymentsScheme}

O endpoint deve receber (path + body):​

  • {id} — GUID do link de pagamento (path)
  • recommendedItemId — ID do registro em CartRecommendedItems (body)

Saida:​

  • 200 — AddRecommendedItemResponseDTO:
    • values — totais recalculados (Values de GetInfoBase)
    • products — lista atualizada de CartItems (List<Product>)
    • paymentMethods — formas de pagamento com parcelas recalculadas para o novo total
    • recommendedItems — lista atualizada de recomendacoes (item aceito removido por deduplicacao)
  • 400:
    • Payment nao encontrado
    • Operacao nao disponivel para este tipo de pedido (ecommerce)
    • Recomendacao nao encontrada (RecommendedItemId invalido ou nao pertence ao cart)
    • Recomendacao nao esta mais disponivel (janela de Cart.DateCreated + 1h expirada)
    • Produto sem estoque na loja (retorno da Cart API)
    • Nao foi possivel adicionar o item (outros erros da Cart API)

Fluxo do handler AddRecommendedItem​

  1. Busca payment pelo GUID
    • Valida existencia → 400 se nao encontrado
    • Valida tipo Store (nao ecommerce) → 400 se ecommerce
  2. Busca cart pelo CartId do payment
  3. Busca CartRecommendedItem na tabela de recomendacoes pelo RecommendedItemId
    • Valida existencia → 400 se nao encontrado
    • Valida que o registro pertence ao CartId do payment → 400 se nao
    • Valida janela de validade (Cart.DateCreated + 1h) → 400 se expirada
  4. Registra tentativa na alllogs
  5. Chama Cart API — POST api/cart/{cartId}/items com [UseApiKey("internal")]
    • Envia: cartId, recommendedItemId
    • Cart API eh responsavel por: resolver dados do item (productId, size, fullPrice, discount, discountType) a partir de CartRecommendedItems, validar estoque, persistir o item, recalcular totais do cart
    • Em caso de erro da Cart API → registra falha na alllogs → retorna 400
  6. Atualiza sincronamente Payment.Total com o novo total do cart
  7. Registra sucesso na alllogs
  8. Retorna AddRecommendedItemResponseDTO

Dependencia — Cart API​

O endpoint POST api/cart/{cartId}/items nao existe na Cart API atualmente. Deve ser criado como task separada:

  • Task: 03 — Cart API: Add Item a cart existente
  • Auth: [UseApiKey("internal")]
  • Responsabilidades: validar estoque pelo StoreId do cart, adicionar item, recalcular totais
  • Payload: cartId, recommendedItemId — Cart API resolve os dados do CartRecommendedItems

Arquivos desta pasta​

ArquivoDescricao
task-194880-add-item-recomendado.mdEste arquivo — sumario, indice da task e fluxo do handler
task-194880-add-item-recomendado-requisitos.mdDocumento de requisitos EARS (pt-BR): RFs, contrato do endpoint, dependencias