Documentação

CheckoutGiftVariantSelection

A mutation CheckoutGiftVariantSelection permite realizar a escolha da variação de um produto brinde vinculado a um carrinho.

Parâmetros

ParâmetroTipoObrigatórioDescrição
checkoutIdUUID!SimID do carrinho.
productVariantIdLong!SimID da variante (SKU) escolhida para o brinde.
cartGiftIdLongNãoID da linha de brinde do carrinho que receberá a escolha, obtido em products.cartGiftId na query Checkout. Obrigatório na prática quando o carrinho tem mais de uma linha de brinde. Ver Escolha entre produtos diferentes.
customerAccessTokenStringNãoToken do cliente.
recaptchaTokenStringNãoToken do Google reCAPTCHA. Obrigatório quando a loja exige reCAPTCHA para esta mutation.

A mutation retorna o objeto Checkout já reprocessado, com a linha de brinde apontando para o produto/variante escolhido. Qualquer campo da query Checkout pode ser consultado no retorno.

📘

Quando informar o cartGiftId

Quando o cartGiftId não é informado, a plataforma localiza a linha de brinde a partir do próprio productVariantId, procurando um brinde do mesmo produto no carrinho ou de um produto irmão (mesmo produto pai). Esse é o comportamento histórico e continua válido para o cenário de um único brinde no carrinho, em que a escolha é apenas de variação.

Sempre que o carrinho puder ter mais de uma linha de brinde — ou quando a promoção oferece produtos diferentes como opção —, informe o cartGiftId. Sem ele, não há como endereçar qual das linhas de brinde deve receber a escolha.

Primeiramente será necessário executar a query de Checkout para obter o ID da variante selecionada.

Exemplo

query {
  checkout(checkoutId: "7f8aa2c9-047f-4da8-ac54-929ca785e0000000000000") {
    products {
      productId
      productVariantId
      gift
      attributeSelections(
        selected: [
          { attributeId: 123, value: "36" }
          { attributeId: 321, value: "Preto" }
        ]
      ) {
        selectedVariant {
          productVariantId
          attributes {
            id
            attributeId
            displayType
            name
            type
            value
          }
        }
        selections {
          attributeId
          name
          values {
            value
          }
        }
      }
    }
  }
}
Mostrar resposta 
{
  "data": {
    "checkout": {
      "products": [
        {
          "productId": 90129,
          "productVariantId": 276639,
          "gift": false,
          "attributeSelections": null
        },
        {
          "productId": 130129,
          "productVariantId": 316640,
          "gift": false,
          "attributeSelections": null
        },
        {
          "productId": 130130,
          "productVariantId": 316644,
          "gift": true,
          "attributeSelections": {
            "selectedVariant": {
              "productVariantId": 316641,
              "attributes": [
                {
                  "id": "eyJFbnRpdHkiOiJQcm9kdWN0QXR0cmlidXRlIiwiSWQiOjI1N30=",
                  "attributeId": 123,
                  "displayType": "DIV com foto do produto variante",
                  "name": "Cor",
                  "type": "Seleção",
                  "value": "Preto"
                },
                {
                  "id": "eyJFbnRpdHkiOiJQcm9kdWN0QXR0cmlidXRlIiwiSWQiOjI1OH0=",
                  "attributeId": 321,
                  "displayType": "DIV",
                  "name": "Tamanho",
                  "type": "Seleção",
                  "value": "36"
                }
              ]
            },
            "selections": [
              {
                "attributeId": 123,
                "name": "Tamanho",
                "values": [
                  {
                    "value": "34"
                  },
                  {
                    "value": "35"
                  },
                  {
                    "value": "36"
                  },
                  {
                    "value": "37"
                  }
                ]
              },
              {
                "attributeId": 321,
                "name": "Cor",
                "values": [
                  {
                    "value": "Preto"
                  },
                  {
                    "value": "Vermelho"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Após obter o ID da variante selecionada, será possivel executar a mutation checkoutGiftVariantSelection.

Exemplo

mutation {
  checkoutGiftVariantSelection(
    checkoutId: "7f8aa2c9-047f-4da8-ac54-929ca7858000000000"
    productVariantId: 316641
  ) {
    products {
      productId
      productVariantId
      name
      gift
    }
  }
}
Mostrar resposta 
{
  "data": {
    "checkoutGiftVariantSelection": {
      "products": [
        {
          "productId": 90129,
          "productVariantId": 276639,
          "name": "Caderno Espiral Capa Dura Preto",
          "gift": false
        },
        {
          "productId": 130129,
          "productVariantId": 316640,
          "name": "Tênis All Star Preto",
          "gift": false
        },
        {
          "productId": 130129,
          "productVariantId": 316641,
          "name": "Tênis All Star Preto",
          "gift": true
        }
      ]
    }
  }
}

Escolha de brinde entre produtos diferentes (cartGiftId)

Além da escolha da variação de um brinde, a mutation também efetiva a escolha de qual produto o consumidor quer receber, quando a promoção declara mais de um produto contemplado como brinde.

As opções disponíveis para cada linha de brinde são consultadas no campo giftOptions da query Checkout. O fluxo é:

  1. Consulte as linhas de brinde do carrinho com gift, cartGiftId e giftOptions.
  2. Renderize a vitrine de opções, destacando a que retorna selected: true.
  3. Ao consumidor escolher outra opção, chame a checkoutGiftVariantSelection informando o cartGiftId da linha e o productVariantId da opção escolhida.
  4. A plataforma reprocessa o carrinho e o retorno já traz a linha de brinde com o produto escolhido.

Exemplo

Consulta das opções de brinde disponíveis na linha de brinde do carrinho:

query {
  checkout(checkoutId: "7f8aa2c9-047f-4da8-ac54-929ca785e0000000000000") {
    products {
      productId
      productVariantId
      name
      gift
      cartGiftId
      giftOptions {
        productId
        productVariantId
        selected
        name
      }
    }
  }
}
Mostrar resposta 
{
  "data": {
    "checkout": {
      "products": [
        {
          "productId": 90129,
          "productVariantId": 276639,
          "name": "Caderno Espiral Capa Dura Preto",
          "gift": false,
          "cartGiftId": 0,
          "giftOptions": []
        },
        {
          "productId": 130130,
          "productVariantId": 316644,
          "name": "Caneca Cerâmica 300ml",
          "gift": true,
          "cartGiftId": 987,
          "giftOptions": [
            {
              "productId": 130130,
              "productVariantId": 316644,
              "selected": true,
              "name": "Caneca Cerâmica 300ml"
            },
            {
              "productId": 130131,
              "productVariantId": 316650,
              "selected": false,
              "name": "Mousepad Gamer"
            },
            {
              "productId": 130132,
              "productVariantId": null,
              "selected": false,
              "name": "Camiseta Básica"
            }
          ]
        }
      ]
    }
  }
}

Efetivando a troca do brinde da linha 987 (caneca) pelo mousepad:

mutation {
  checkoutGiftVariantSelection(
    checkoutId: "7f8aa2c9-047f-4da8-ac54-929ca785e0000000000000"
    cartGiftId: 987
    productVariantId: 316650
  ) {
    products {
      productId
      productVariantId
      name
      gift
      cartGiftId
    }
  }
}
Mostrar resposta 
{
  "data": {
    "checkoutGiftVariantSelection": {
      "products": [
        {
          "productId": 90129,
          "productVariantId": 276639,
          "name": "Caderno Espiral Capa Dura Preto",
          "gift": false,
          "cartGiftId": 0
        },
        {
          "productId": 130131,
          "productVariantId": 316650,
          "name": "Mousepad Gamer",
          "gift": true,
          "cartGiftId": 987
        }
      ]
    }
  }
}
⚠️

Opção sem variante resolvida

Quando a opção escolhida retorna productVariantId: null em giftOptions, significa que o produto possui mais de uma variante disponível e a variante ainda não está definida. Nesse caso, antes de chamar a mutation, consulte as variantes daquele produto na query products, em attributeSelections, usando includeParentIdVariants: false, e chame a mutation com a variante que o consumidor selecionar.

A mutation sempre recebe uma variante concreta: não existe chamada apenas com o productId da opção.

Erros

CódigoMensagemQuando ocorre
PRM109Produto brinde não encontrado no carrinhoO cartGiftId informado não existe no carrinho, ou — quando o cartGiftId é omitido — não há linha de brinde correspondente ao productVariantId informado nem a um produto irmão dele.
PRM117O produto escolhido não está entre as opções deste brindeA variante informada não pertence às opções que a promoção declarou para aquela linha de brinde. Envie apenas valores obtidos em giftOptions.
PRM104Erro ao selecionar a variante do brindeFalha na requisição ao módulo de Promoções ao gravar a escolha. Inclui as validações do próprio módulo, que é a autoridade final sobre a regra da promoção.

Updated 13 days ago