Skip to main content

Requisitos — Remove Recommended Item

Task #194882 · Endpoint DELETE api/payment/v2/{id}/remove-recommended-item​

Task pai: #194882 — [Back] 04 - Remover item recomendado Contexto: US 194871 — MVP Upsell (Pedido) Spec tecnica: a ser criada ADRs relacionados: ADR-005 · ADR-007 · ADR-008 · ADR-009

Visão geral​

O cliente que adicionou um item recomendado ao pedido via zzlink pode desistir e removê-lo antes de finalizar o pagamento. O endpoint recebe o identificador do item já presente no cart, valida que é um item originado de uma recomendação, remove-o via Cart API e retorna os valores atualizados do pedido para que o front possa atualizar a tela sem recarregar.

Papéis​

  • Cliente: pessoa que acessa o zzlink para efetuar o pagamento
  • Checkout service: orquestrador da operação — valida, chama Cart API, atualiza Payment
  • Cart API: responsável por localizar e remover o item do cart e recalcular totais

Requisitos​

RF-01 — Receber e validar o contexto do pedido​

User Story: Como cliente no zzlink, quero remover um item recomendado que adicionei ao meu pedido, para que ele não seja incluído no pagamento que vou realizar.

Acceptance Criteria:

  1. WHEN o cliente chama DELETE api/payment/v2/{id}/remove-recommended-item THEN o sistema SHALL exigir autenticação via PaymentsScheme (token JWT já presente no zzlink para operações de finalização).
  2. WHEN o {id} (GUID do payment) não corresponde a nenhum payment THEN o sistema SHALL retornar 400 com mensagem "Payment não encontrado".
  3. WHEN o payment encontrado é do tipo Ecommerce (não Store) THEN o sistema SHALL retornar 400 com mensagem "Operação não disponível para este tipo de pedido".

RF-02 — Validar o item a remover​

Acceptance Criteria:

  1. WHEN o cartItemId informado não corresponde a nenhum CartItem no cart vinculado ao payment THEN o sistema SHALL retornar 400 com mensagem "Item não encontrado no pedido".
  2. WHEN o CartItem encontrado tem IsFromRecommendation = false THEN o sistema SHALL retornar 400 com mensagem "Item não pode ser removido".
  3. WHEN todas as validações passam THEN o sistema SHALL prosseguir para a chamada à Cart API.

Dependência: A validação do critério 2 depende da flag IsFromRecommendation em CartItemsModel, que será adicionada em US separada.

RF-03 — Remover o item via Cart API​

Acceptance Criteria:

  1. WHEN o sistema chama a Cart API para remover o item THEN o sistema SHALL chamar DELETE api/cart/{cartId}/items/{cartItemId} com ApiKey "internal".
  2. WHEN a Cart API retorna sucesso THEN o sistema SHALL prosseguir para o ajuste do Payment.Total.
  3. WHEN a Cart API retorna 404 (item não encontrado) THEN o sistema SHALL retornar 400 com mensagem "Item não encontrado no pedido" e registrar a falha na alllogs.
  4. WHEN a Cart API retorna qualquer outro erro THEN o sistema SHALL retornar 400 com mensagem "Não foi possível remover o item" e registrar a falha na alllogs.

RF-04 — Atualizar o Payment e retornar o DTO consolidado​

Acceptance Criteria:

  1. WHEN a Cart API confirma sucesso THEN o sistema SHALL atualizar sincronamente o campo Total do PaymentModel com o novo total do cart.
  2. WHEN o Payment.Total é atualizado com sucesso THEN o sistema SHALL retornar 200 com o RemoveRecommendedItemResponseDTO contendo:
    • values — Values recalculado com o novo total
    • products — List<Product> completa e atualizada dos CartItems (sem o item removido, cada item com cartItemId)
    • paymentMethods — PaymentMethods com parcelas recalculadas para o novo total
    • recommendedItems — List<RecommendedItemsInfoDTO> atualizada

RF-05 — Auditoria (alllogs)​

Acceptance Criteria:

  1. WHEN o endpoint é chamado com dados válidos de autenticação THEN o sistema SHALL registrar na alllogs a tentativa de remover o item (payment GUID, cartItemId).
  2. WHEN a operação conclui com sucesso THEN o sistema SHALL registrar na alllogs o resultado positivo.
  3. WHEN a operação falha em qualquer etapa (Cart API, atualização do payment, etc.) THEN o sistema SHALL registrar na alllogs a falha com o motivo.

Contrato do endpoint​

Request​

DELETE api/payment/v2/{id}/remove-recommended-item
Authorization: Bearer {token PaymentsScheme}
Content-Type: application/json

{
  "cartItemId": 0
}

Response 200​

{
  "values": {
    "products": { "value": 0.0, "description": "R$ 0,00", "amount": 0 },
    "discount": { "value": 0.0, "description": "R$ 0,00" },
    "discountPix": { "value": 0.0, "description": "R$ 0,00" },
    "bonus": { "value": 0.0, "description": "R$ 0,00" },
    "subtotal": { "value": 0.0, "description": "R$ 0,00" },
    "subtotalWhenPix": { "value": 0.0, "description": "R$ 0,00" },
    "shipment": { "value": 0.0, "description": "R$ 0,00" },
    "total": { "value": 0.0, "description": "R$ 0,00" },
    "totalWhenPix": { "value": 0.0, "description": "R$ 0,00" }
  },
  "products": [
    {
      "itemId": 0,
      "name": "string",
      "size": "string",
      "amount": 0,
      "fullPrice": 0.0,
      "price": 0.0,
      "total": 0.0,
      "url": "string"
    }
  ],
  "paymentMethods": {
    "creditCard": true,
    "pix": { "operator": 0, "key": "string", "discountPercentage": null, "discountValue": null },
    "boleto": false,
    "installments": [
      { "installment": "1", "value": 0.0, "description": "1x de R$ 0,00" }
    ],
    "isTwoCreditCardsAllowed": false
  },
  "recommendedItems": [
    {
      "recommendedItemId": 0,
      "productId": "string",
      "sku": "string",
      "productName": "string",
      "description": "string",
      "thumbnail": "string",
      "images": [],
      "fullPrice": 0.0,
      "discountValue": 0.0,
      "discountType": 0,
      "size": "string"
    }
  ]
}

Responses 400​

CenárioMensagem
Payment não encontrado"Payment não encontrado"
Payment não é do tipo Store"Operação não disponível para este tipo de pedido"
cartItemId não encontrado no cart"Item não encontrado no pedido"
Item não originado de recomendação (IsFromRecommendation = false)"Item não pode ser removido"
Cart API retornou 404"Item não encontrado no pedido"
Outro erro da Cart API"Não foi possível remover o item"

Dependências​

DependênciaTaskStatus
Cart API — endpoint DELETE api/cart/{cartId}/items/{cartItemId}Task 05 — Cart API: Remove ItemPendente de refinamento
Flag IsFromRecommendation em CartItemsModelUS separada (a ser criada)Pendente
cartItemId exposto no Product DTOADR-008Decisao tomada

Fora de escopo​

  • Lógica interna da Cart API (remoção do item, recálculo de totais do cart) — responsabilidade da task separada da Cart API
  • Adição de item recomendado — task #194882 item 02
  • Validação de janela de validade (1h) — não se aplica ao remove; o item já foi aceito e está no cart

Questões abertas​

Nenhuma.