💼 Carteira do Cliente

📋 Visão Geral

A Carteira do Cliente é um recurso de créditos digitais vinculado diretamente à conta do cliente.

Os créditos acumulados podem ser utilizados como forma de pagamento em compras na loja, atuando como saldo disponível no momento do checkout. Movimentações como adição de créditos via gift card, adição via voucher promocional e uso do saldo em pedidos geram transações registradas na carteira.

O acesso às informações da carteira é totalmente baseado no token do cliente autenticado — não é necessário informar o ID do cliente na URL. Os endpoints desta seção são utilizados principalmente na tela de Minha Conta, permitindo que o cliente acompanhe suas movimentações financeiras de forma autônoma.

🔄 Entidades Envolvidas

As seguintes entidades participam do fluxo da carteira:

Cliente

O titular da carteira, identificado pelo token de autenticação. Toda consulta é automaticamente filtrada pelo cliente do token.

Transação de Carteira

Registro de cada movimentação financeira. Cada transação possui uma ação (action) que indica se foi um crédito (add) ou débito (remove), além de um valor e a data de criação.

Voucher Promocional (quando aplicável)

Vouchers emitidos por promoções que, ao serem resgatados, geram um crédito na carteira.

Gift Card (quando aplicável)

Cartões presentes adquiridos ou recebidos. Ao serem ativados, geram uma transação de crédito na carteira do cliente.

Pedido (quando aplicável)

Quando o saldo da carteira é utilizado em uma compra, a transação de débito é vinculada ao pedido correspondente.

🗂️ Estrutura da Transação de Carteira

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

• id — identificador único da transação
• voucher — objeto do voucher promocional vinculado, ou null quando não aplicável
• giftCard — objeto do gift card vinculado, ou null quando não aplicável
• order — objeto do pedido vinculado, ou null quando não aplicável
• action — ação executada na transação: "add" para crédito ou "remove" para débito
• value — valor monetário da transação
• createdAt — data e hora de criação da transação

🎟️ Estrutura do Voucher

Quando a transação possui um voucher promocional vinculado, o objeto contém:

• id — identificador único do voucher
• customerId — ID do cliente titular do voucher
• userId — ID do usuário administrativo que criou a promoção (null quando não aplicável)
• userName — nome do usuário que criou a promoção
• userEmail — e-mail do usuário que criou a promoção
• hash — código identificador único do voucher
• value — valor do voucher
• observation — observação textual associada ao voucher (null quando ausente)
• customer — dados resumidos do cliente associado (null quando não carregado)
• createdAt — data e hora de criação do voucher

🎁 Estrutura do Gift Card

Quando a transação possui um gift card vinculado, o objeto contém:

• id — identificador único do gift card gerado
• productId — ID do produto de gift card
• orderItemId — ID do item do pedido que gerou o gift card (null para gift cards criados manualmente)
• code — código de resgate do gift card
• value — valor nominal do gift card
• userId — ID do usuário administrativo que registrou o gift card (null quando não aplicável)
• userName — nome do usuário que registrou o gift card
• userEmail — e-mail do usuário que registrou o gift card
• createdAt — data e hora de criação do gift card
• activatedAt — data e hora de ativação (resgate) do gift card

🛒 Estrutura do Pedido

Quando a transação possui um pedido vinculado, o objeto contém:

• id — identificador único do pedido
• orderGroupId — ID do grupo de pedido ao qual este pedido pertence
• productStorageId — ID do armazém associado ao pedido (null quando não aplicável)
• orderStatusId — ID do status atual do pedido (null quando não aplicável)
• marketplaceOrderId — identificador do pedido no marketplace externo (null quando não aplicável)

📌 Notas e Considerações

• O cliente é identificado exclusivamente pelo token de autenticação — customerId não deve ser informado na requisição.
• Uma transação pode ter no máximo um dos campos voucher, giftCard ou order preenchido; os demais serão null.
• A listagem suporta paginação e filtros por ação, voucher, gift card, pedido e data de criação.

💼 Listagem de Transações da Carteira

📄 Descrição

Endpoint responsável por retornar uma lista paginada das transações da carteira do cliente autenticado. Cada transação representa uma movimentação financeira — crédito (add) ou débito (remove) — e pode estar vinculada a um pedido, a um voucher promocional ou a um gift card.

A listagem suporta filtros por campo (action, promotionalVoucherId, productGiftCardGeneratedId, orderId, createdAt) e ordenação por id ou createdAt, além de paginação via limit e offset.

A utilização requer autenticação via CustomerAuth — o ID do cliente é identificado automaticamente pelo token de autenticação, 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/wallet/transaction?limit=10&offset=0' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

💡 Exemplo com Filtros

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/wallet/transaction?limit=10&offset=0&condition[conditions][0][field]=action&condition[conditions][0][value]=add&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": 5,
7        "voucher": null,
8        "giftCard": {
9          "id": 12,
10          "productId": 7,
11          "orderItemId": null,
12          "code": "GFT9X2MPLQ",
13          "value": 150.00,
14          "userId": 3,
15          "userName": "Suporte Loja",
16          "userEmail": "suporte@minhaloja.com.br",
17          "createdAt": "2026-03-10 09:00:00",
18          "activatedAt": "2026-03-10 09:15:00"
19        },
20        "order": null,
21        "action": "add",
22        "value": 150.00,
23        "createdAt": "2026-03-10 09:15:00"
24      },
25      {
26        "id": 8,
27        "voucher": {
28          "id": 14,
29          "customerId": 42,
30          "userId": 3,
31          "userName": "Suporte Loja",
32          "userEmail": "suporte@minhaloja.com.br",
33          "hash": "VOC88PROMO",
34          "value": 75.00,
35          "observation": "Cupom de fidelidade",
36          "customer": null,
37          "createdAt": "2026-03-12 14:30:00"
38        },
39        "giftCard": null,
40        "order": null,
41        "action": "add",
42        "value": 75.00,
43        "createdAt": "2026-03-12 14:30:00"
44      },
45      {
46        "id": 9,
47        "voucher": null,
48        "giftCard": null,
49        "order": {
50          "id": 2048,
51          "orderGroupId": 820,
52          "productStorageId": 3,
53          "orderStatusId": 7,
54          "marketplaceOrderId": null
55        },
56        "action": "remove",
57        "value": 60.00,
58        "createdAt": "2026-03-15 11:00:00"
59      }
60    ],
61    "pagination": {
62      "limit": 10,
63      "offset": 0,
64      "pages": 1,
65      "registers": 3
66    }
67  }
68}

⚠️ 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.