🎁 Cartões de Presente do Cliente

📋 Visão Geral

O cartão de presente é um código resgatável de crédito vinculado à conta do cliente.

Cada cartão de presente é adquirido como um produto na loja e carrega um valor predefinido. Ao ser vinculado à conta do cliente, o código credita automaticamente o saldo correspondente na carteira digital do cliente, que pode ser utilizado como forma de pagamento em compras futuras.

Os endpoints desta seção são utilizados principalmente na tela de Minha Conta, permitindo que o cliente consulte seus cartões de presente e vincule novos códigos de forma autônoma.

O acesso às informações de cartões de presente é totalmente baseado no token do cliente autenticado — não é necessário informar o ID do cliente na URL ou no corpo da requisição.

🔄 Entidades Envolvidas

As seguintes entidades participam do fluxo:

• Cliente
• Cartão de Presente
• Produto (o produto de cartão de presente adquirido na loja)
• Item de Pedido (quando o cartão de presente foi gerado a partir de uma compra)

🗂️ Estrutura do Cartão de Presente

O objeto de cartão de presente retornado contém as seguintes informações:

• id — identificador único do cartão de presente
• productId — ID do produto de cartão de presente associado
• product — objeto completo do produto de cartão de presente (veja estrutura abaixo)
• orderItemId — ID do item de pedido que originou o cartão de presente, ou null quando não aplicável
• code — código do cartão de presente para resgate
• value — valor monetário do cartão de presente
• userId — ID do usuário administrador que registrou o cartão de presente
• userName — nome do usuário que registrou o cartão de presente
• userEmail — e-mail do usuário que registrou o cartão de presente
• createdAt — data de criação do cartão de presente
• activatedAt — data em que o cartão de presente foi resgatado e vinculado a um cliente

🛍️ Estrutura do Produto

O campo product contém o objeto completo do produto de cartão de presente:

• productId — ID do produto
• brandId — ID da marca do produto
• brandName — nome da marca
• mainCategoryId — ID da categoria principal
• mainCategoryName — nome da categoria principal
• type — tipo do produto
• sku — SKU do produto
• name — nome do produto
• active — indica se o produto está ativo
• url — URL amigável do produto na loja
• comparisonPrice — preço de comparação do produto
• stock — estoque disponível
• medias — lista de mídias do produto
• combination — lista de combinações do produto
• currentAttributes — lista de atributos atuais
• restriction — restrição de acesso ao produto, ou null quando não aplicável

🔗 Estrutura do Resultado de Vínculo

Ao vincular códigos, cada entrada do array de retorno contém:

• giftCardId — ID do cartão de presente quando o vínculo foi iniciado por ID, ou null quando o vínculo foi iniciado pelo código (fluxo padrão do cliente)
• code — código submetido na requisição, ou null quando o vínculo foi iniciado por ID
• customerId — ID do cliente ao qual o código foi (ou tentou ser) vinculado
• error — código de erro interno caso o vínculo falhe, ou null em caso de sucesso

🎁 Listagem de Cartões de Presente do Cliente

📄 Descrição

Endpoint responsável por retornar uma lista paginada dos cartões de presente vinculados ao cliente autenticado.

Permite consultar todos os códigos já resgatados, com seus respectivos valores, datas e dados do produto associado. A listagem suporta filtros por campo (código, valor, datas) e paginação via limit e offset.

A utilização requer autenticação via CustomerAuth — o ID do cliente é identificado automaticamente pelo token, não sendo necessário informá-lo na requisição.

📋 Parâmetros de Query

🏷️ Headers Obrigatórios

🔍 Campos de Condição Disponíveis

📊 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/gift-cards?limit=10&offset=0' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

💡 Exemplo com Filtros

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/gift-cards?limit=10&offset=0&condition[conditions][0][field]=value&condition[conditions][0][value]=200&condition[conditions][0][operator]==&order[0][field]=createdAt&order[0][order]=desc' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 15,
7        "productId": 9,
8        "product": {
9          "productId": 9,
10          "brandId": 4,
11          "brandName": "Minha Loja",
12          "mainCategoryId": 0,
13          "mainCategoryName": "",
14          "type": "product",
15          "sku": "gift-card-200",
16          "name": "Gift Card R$ 200",
17          "active": true,
18          "url": "/gift-card-r$-200",
19          "comparisonPrice": 200,
20          "stock": 0,
21          "medias": [],
22          "combination": [],
23          "currentAttributes": [],
24          "restriction": null
25        },
26        "orderItemId": null,
27        "code": "ZPQ7RKWMTX",
28        "value": 200,
29        "userId": 5,
30        "userName": "Gerente Financeiro",
31        "userEmail": "financeiro@minhaloja.com.br",
32        "createdAt": "2026-01-15 10:30:00",
33        "activatedAt": "2026-01-15 11:05:22"
34      }
35    ],
36    "pagination": {
37      "limit": 10,
38      "offset": 0,
39      "pages": 1,
40      "registers": 1
41    }
42  }
43}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🎁 Vincular Cartões de Presente ao Cliente

📄 Descrição

Endpoint responsável por vincular um ou mais códigos de cartão de presente à conta do cliente autenticado.

Múltiplos códigos podem ser enviados em uma única requisição. Cada código é processado individualmente e retorna seu próprio resultado no array de resposta — permitindo que parte dos códigos seja vinculada com sucesso enquanto outros apresentam erro, sem que a requisição inteira seja rejeitada.

IMPORTANTE: os erros por código são embutidos no array de dados da resposta, e não lançados como erros HTTP. A resposta sempre retorna HTTP 200 independente do resultado individual de cada código.

A utilização requer autenticação via CustomerAuth — o ID do cliente é identificado automaticamente pelo token, não sendo necessário informá-lo no corpo da requisição.

📋 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/customer/gift-cards/link \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "codes": ["NOVOCOD123", "PRESENTE99"]
7  }'

✅ Resposta de Sucesso

Quando todos os códigos são vinculados com sucesso, giftCardId contém o ID do cartão de presente vinculado e error é null.

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "giftCardId": 22,
6      "code": "NOVOCOD123",
7      "customerId": 88,
8      "error": null
9    },
10    {
11      "giftCardId": 23,
12      "code": "PRESENTE99",
13      "customerId": 88,
14      "error": null
15    }
16  ]
17}

⚠️ Resposta com Erro por Código

Quando um ou mais códigos não podem ser vinculados, o resultado é embutido no array de dados com giftCardId: null e o código de erro no campo error. A requisição retorna HTTP 200 normalmente.

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "giftCardId": null,
6      "code": "NOVOCOD123",
7      "customerId": 88,
8      "error": "UAPPI_STORE_GIFT_CARD_ALREADY_LINKED"
9    },
10    {
11      "giftCardId": null,
12      "code": "NOVOCOD1234",
13      "customerId": 88,
14      "error": "UAPPI_STORE_GIFT_CARD_NOT_FOUND"
15    }
16  ]
17}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.