Skip to main content

Requisitos — Add Recommended Item

Task #194880 · Endpoint POST api/payment/v2/{id}/add-recommended-item​

Task pai: #194880 — [Back] 02 - Adicionar item recomendado Contexto: US 194871 — MVP Upsell (Pedido) Spec tecnica: a ser criada ADRs relacionados: ADR-004 · ADR-005 · ADR-006 · ADR-007 · ADR-009

Visão geral​

O cliente que recebeu um link de pagamento (zzlink) pode visualizar itens recomendados pelo vendedor e, com um clique, adicionar um desses itens ao seu pedido. O endpoint recebe essa intenção, valida as condições, incorpora o item ao cart 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 validar estoque e persistir o novo item no cart

Requisitos​

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

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

Acceptance Criteria:

  1. WHEN o cliente chama POST api/payment/v2/{id}/add-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 a recomendação​

Acceptance Criteria:

  1. WHEN o RecommendedItemId informado não existe na tabela de CartRecommendedItems THEN o sistema SHALL retornar 400 com mensagem "Recomendação não encontrada".
  2. WHEN o RecommendedItemId existe, mas o registro não pertence ao CartId vinculado ao payment THEN o sistema SHALL retornar 400 com mensagem "Recomendação não encontrada".
  3. WHEN o item recomendado existe, mas Cart.DateCreated + 1 hora < DateTime.Now (janela de validade expirada) THEN o sistema SHALL retornar 400 com mensagem "Recomendação não está mais disponível".
  4. WHEN todas as validações de contexto e recomendação passam THEN o sistema SHALL prosseguir para a chamada à Cart API.

RF-03 — Adicionar o item via Cart API​

Acceptance Criteria:

  1. WHEN o sistema chama a Cart API para adicionar o item THEN o sistema SHALL enviar: cartId e recommendedItemId. A Cart API é responsável por resolver os dados do item (productId, size, fullPrice, discount, discountType) a partir do registro em CartRecommendedItems.
  2. WHEN a Cart API retorna sucesso THEN o sistema SHALL prosseguir para o ajuste do Payment.Total.
  3. WHEN a Cart API retorna erro de produto sem estoque THEN o sistema SHALL retornar 400 com mensagem "Produto sem estoque na loja" 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 adicionar 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 AddRecommendedItemResponseDTO contendo:
    • values — Values recalculado com o novo total
    • products — List<Product> completa e atualizada dos CartItems (incluindo o item recém-adicionado), cada item contendo cartItemId para referência no fluxo de remoção
    • paymentMethods — PaymentMethods com parcelas recalculadas para o novo total
    • recommendations — RecommendationsInfoDTO com hoursToExpire e lista de RecommendedItemsInfoDTO filtrada (apenas recomendações onde CartItemId == null, ou seja, não efetivadas)

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 adicionar o item (payment GUID, recommendedItemId).
  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​

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

{
  "recommendedItemId": 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": [
    {
      "cartItemId": 0,
      "name": "string",
      "size": "string",
      "amount": 0,
      "fullPrice": 0.0,
      "price": 0.0,
      "total": 0.0,
      "url": "string",
      "fromRecommendation": false
    }
  ],
  "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
  },
  "recommendations": {
    "hoursToExpire": "0:00",
    "items": [
      {
        "recommendedItemId": 0,
        "productId": 0,
        "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 (CartInfoDTO.SaleEcommerce == true)"Operação não disponível para este tipo de pedido"
RecommendedItemId não encontrado ou não pertence ao CartId"Recomendação não encontrada"
Recomendação já efetivada (CartItemId != null)"Recomendação já adicionada ao carrinho"
Janela de validade expirada (CartInfoDTO.DateCreated + RECOMMENDATION_EXPIRATION_MINUTES)"Recomendação não está mais disponível"
Lock não adquirido (race condition)429 — "Pagamento em processamento"
Cart não encontrado"Carrinho não encontrado"
Sem estoque na loja (retorno Cart API)"Produto sem estoque na loja"
Outro erro da Cart API"Não foi possível adicionar o item"
Erro interno persistência500 — "Erro interno ao atualizar o pagamento"
recommendedItemId <= 0"O campo recommendedItemId deve ser um número inteiro positivo"

Dependências​

DependênciaTaskStatus
Cart API — endpoint POST api/cart/{cartId}/itemsTask 03 — Cart API: Add ItemPendente de refinamento

Nota: O contrato da Cart API será alterado para aceitar recommendedItemId em vez de productId + size. Esta alteração será feita no refinamento da task-03.

Fora de escopo​

  • Lógica interna da Cart API (validação de estoque, cálculo de totais do cart) — responsabilidade da task separada da Cart API
  • Remoção de item recomendado — task #193232 item 03

Questões abertas​

Nenhuma.