Carteira do Cliente (Admin)

Visão Geral

Este módulo permite que usuários administrativos consultem a carteira digital dos clientes e suas respectivas transações 💼.

A carteira é utilizada para armazenar créditos, que podem ser utilizados como forma de pagamento em compras na loja.

Permissão

Todas as rotas exigem autenticação via middleware UserAuth, com validação do escopo apropriado.

• CUSTOMER_READ: necessário para listagem de transações da carteira

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 ou null quando não houver voucher vinculado
• giftCard: objeto ou null quando não houver gift card vinculado
• order: objeto ou null quando não houver pedido vinculado
• action: ação executada na transação
• value: valor da transação
• createdAt: data de criação da transação

Estrutura do Voucher

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

• id: ID do voucher
• customerId: ID do cliente que possui o voucher
• userId: ID do usuário 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: hash identificador do voucher
• value: valor do voucher
• observation: observação associada ao voucher
• customer: dados do cliente associado
• createdAt: data de criação

Estrutura do GiftCard

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

• id: ID do gift card gerado
• productId: ID do produto de gift card
• product: dados do produto
• orderItemId: ID do item do pedido (null quando não aplicável)
• code: código do gift card
• value: valor do gift card
• userId: ID do usuário
• userName: nome do usuário
• userEmail: e-mail do usuário
• createdAt: data de criação do gift card
• activatedAt: data de resgate do gift card

Estrutura do Pedido

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

• id: ID do pedido
• orderGroupId: ID do grupo de pedido
• productStorageId: ID do armazém (null quando não aplicável)
• orderStatusId: ID do status do pedido (null quando não aplicável)

Listagem de Transações da Carteira

Descrição

Endpoint responsável por retornar uma lista paginada das transações da carteira de um cliente específico 💼.

Destinado ao painel administrativo, permite acompanhar movimentações como créditos, débitos e vínculos com pedidos, vouchers ou gift cards.

A utilização requer autenticação via UserAuth e permissão CUSTOMER_READ, garantindo controle e segurança no acesso às informações financeiras.

Parâmetros de Query

Headers Obrigatórios

Parâmetros de URL

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/123/wallet/transaction?limit=10&offset=0' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

Exemplo com Filtros

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/123/wallet/transaction?limit=10&offset=0&condition[action]=CREDIT&order[0][field]=createdAt&order[0][direction]=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": 1,
7        "voucher": {
8          "id": 10,
9          "customerId": 123,
10          "userId": 1,
11          "userName": "Admin",
12          "userEmail": "admin@exemplo.com",
13          "hash": "ABC123XYZ",
14          "value": 50.00,
15          "observation": "Crédito de boas-vindas",
16          "customer": null,
17          "createdAt": "2026-01-01 10:30:00"
18        },
19        "giftCard": null,
20        "order": null,
21        "action": "credit",
22        "value": 50.00,
23        "createdAt": "2026-01-01 10:30:00"
24      },
25      {
26        "id": 2,
27        "voucher": null,
28        "giftCard": null,
29        "order": {
30          "id": 1001,
31          "orderGroupId": 500,
32          "productStorageId": 1,
33          "orderStatusId": 5
34        },
35        "action": "remove",
36        "value": 30.00,
37        "createdAt": "2026-01-01 10:30:00"
38      }
39    ],
40    "pagination": {
41      "limit": 10,
42      "offset": 0,
43      "pages": 1,
44      "registers": 2
45    }
46  }
47}

Possíveis Erros

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.