API atual/Referência completa/Carteiras de crédito

Consultar carteiras

Lista carteiras, busca clientes, mostra os totais da loja e o saldo e o extrato de um cliente.

Quatro consultas de leitura. Use a busca (q) quando você parte do nome ou e-mail do cliente e precisa achar o user_id.

Listar carteiras

Sem q, lista as carteiras existentes. Com q, muda de formato: busca, pelo nome ou e-mail, clientes que já têm carteira e devolve a chave users, com o saldo de cada um.

GET/api/v1/admin/walletsAdmin

Lista carteiras ou busca clientes

Parâmetros de consulta

qstring

Busca por cliente. Muda a resposta para users.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets?q=marina&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Busca de clientes (com q)

json

{
  "users": [
    {
      "id": "64a72542-ac9e-49aa-87bd-bad84fad96a5",
      "email": "marina.duarte@example.com",
      "first_name": "Marina",
      "last_name": "Duarte",
      "balance": 698
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

200Carteiras (sem q)

json

{
  "wallets": [
    {
      "id": "19aae607-b66a-4637-b18e-6a14554e0443",
      "user_id": "64a72542-ac9e-49aa-87bd-bad84fad96a5",
      "balance": 698,
      "status": "active",
      "created_at": "2026-09-17T05:28:00Z",
      "updated_at": "2026-09-17T05:28:00Z"
    }
  ],
  "total": 31,
  "page": 1,
  "per_page": 20
}

Campos da resposta

usersarray

Só com q: clientes (id é o user_id), email, first_name, last_name, balance.

walletsarray

Sem q: carteiras (id, user_id, balance, status active ou frozen, datas).

totalinteger

Total.

pageinteger

Página.

per_pageinteger

Tamanho.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Ver os totais

GET/api/v1/admin/wallets/summaryAdmin

Totais das carteiras

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Totais

json

{
  "total_credits": 150825,
  "total_debits": 2400,
  "active_wallets": 8
}

Campos da resposta

total_creditsinteger

Soma de todos os créditos já lançados, em centavos.

total_debitsinteger

Soma de todos os débitos, em centavos.

active_walletsinteger

Carteiras com saldo positivo.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Consultar o saldo de um cliente

GET/api/v1/admin/wallets/{user_id}Admin

Saldo de um cliente

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Saldo

json

{
  "balance": 698,
  "status": "active",
  "total_credits": 698,
  "total_debits": 0
}

Campos da resposta

balanceinteger

Saldo em centavos.

statusstring

activefrozen

active ou frozen.

total_creditsinteger

Soma dos créditos da carteira.

total_debitsinteger

Soma dos débitos (valor absoluto).

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`
500	`user_id` que não é UUID válido (a mensagem vem em português).	`{"error":"failed to get wallet","detail":"o valor \"abc\" não é um uuid válido..."}`

Consultar o extrato

GET/api/v1/admin/wallets/{user_id}/transactionsAdmin

Extrato de um cliente

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transações

json

{
  "transactions": [
    {
      "id": "b761af68-16bd-4141-8183-9a56948050e5",
      "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
      "amount": 698,
      "type": "credit",
      "reference_type": "cashback",
      "reference_id": "9bf6822d-fc13-4948-86ae-99e3042f5e9a",
      "description": "Cashback do pedido 9bf6822d-fc13-4948-86ae-99e3042f5e9a",
      "balance_after": 698,
      "created_at": "2026-09-17T05:28:00Z",
      "created_by": "system"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

transactionsarray

Mais recentes primeiro.

totalinteger

Total.

pageinteger

Página.

per_pageinteger

Tamanho.

total_pagesinteger

Páginas.

iduuid

Id da transação.

wallet_iduuid

Carteira.

amountinteger

Centavos: positivo no crédito, negativo no débito.

typestring

creditdebit

credit ou debit.

reference_typestring

Origem do movimento.

reference_idstring

Id da entidade de origem (por exemplo o pedido).

descriptionstring

Texto do movimento.

balance_afterinteger

Saldo depois deste movimento, em centavos.

created_atstring

Quando (RFC 3339).

created_bystring

Quem iniciou (usuário ou system).

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`
500	`user_id` malformado.	`{"error":"failed to list transactions","detail":"..."}`

Veja também

Carteiras

API atual/Referência completa/Carteiras de crédito

Consultar carteiras

Lista carteiras, busca clientes, mostra os totais da loja e o saldo e o extrato de um cliente.

Quatro consultas de leitura. Use a busca (q) quando você parte do nome ou e-mail do cliente e precisa achar o user_id.

Listar carteiras

Sem q, lista as carteiras existentes. Com q, muda de formato: busca, pelo nome ou e-mail, clientes que já têm carteira e devolve a chave users, com o saldo de cada um.

GET/api/v1/admin/walletsAdmin

Lista carteiras ou busca clientes

Parâmetros de consulta

qstring

Busca por cliente. Muda a resposta para users.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets?q=marina&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Busca de clientes (com q)

json

{
  "users": [
    {
      "id": "64a72542-ac9e-49aa-87bd-bad84fad96a5",
      "email": "marina.duarte@example.com",
      "first_name": "Marina",
      "last_name": "Duarte",
      "balance": 698
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

200Carteiras (sem q)

json

{
  "wallets": [
    {
      "id": "19aae607-b66a-4637-b18e-6a14554e0443",
      "user_id": "64a72542-ac9e-49aa-87bd-bad84fad96a5",
      "balance": 698,
      "status": "active",
      "created_at": "2026-09-17T05:28:00Z",
      "updated_at": "2026-09-17T05:28:00Z"
    }
  ],
  "total": 31,
  "page": 1,
  "per_page": 20
}

Campos da resposta

usersarray

Só com q: clientes (id é o user_id), email, first_name, last_name, balance.

walletsarray

Sem q: carteiras (id, user_id, balance, status active ou frozen, datas).

totalinteger

Total.

pageinteger

Página.

per_pageinteger

Tamanho.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Ver os totais

GET/api/v1/admin/wallets/summaryAdmin

Totais das carteiras

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Totais

json

{
  "total_credits": 150825,
  "total_debits": 2400,
  "active_wallets": 8
}

Campos da resposta

total_creditsinteger

Soma de todos os créditos já lançados, em centavos.

total_debitsinteger

Soma de todos os débitos, em centavos.

active_walletsinteger

Carteiras com saldo positivo.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Consultar o saldo de um cliente

GET/api/v1/admin/wallets/{user_id}Admin

Saldo de um cliente

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Saldo

json

{
  "balance": 698,
  "status": "active",
  "total_credits": 698,
  "total_debits": 0
}

Campos da resposta

balanceinteger

Saldo em centavos.

statusstring

activefrozen

active ou frozen.

total_creditsinteger

Soma dos créditos da carteira.

total_debitsinteger

Soma dos débitos (valor absoluto).

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`
500	`user_id` que não é UUID válido (a mensagem vem em português).	`{"error":"failed to get wallet","detail":"o valor \"abc\" não é um uuid válido..."}`

Consultar o extrato

GET/api/v1/admin/wallets/{user_id}/transactionsAdmin

Extrato de um cliente

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transações

json

{
  "transactions": [
    {
      "id": "b761af68-16bd-4141-8183-9a56948050e5",
      "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
      "amount": 698,
      "type": "credit",
      "reference_type": "cashback",
      "reference_id": "9bf6822d-fc13-4948-86ae-99e3042f5e9a",
      "description": "Cashback do pedido 9bf6822d-fc13-4948-86ae-99e3042f5e9a",
      "balance_after": 698,
      "created_at": "2026-09-17T05:28:00Z",
      "created_by": "system"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

transactionsarray

Mais recentes primeiro.

totalinteger

Total.

pageinteger

Página.

per_pageinteger

Tamanho.

total_pagesinteger

Páginas.

iduuid

Id da transação.

wallet_iduuid

Carteira.

amountinteger

Centavos: positivo no crédito, negativo no débito.

typestring

creditdebit

credit ou debit.

reference_typestring

Origem do movimento.

reference_idstring

Id da entidade de origem (por exemplo o pedido).

descriptionstring

Texto do movimento.

balance_afterinteger

Saldo depois deste movimento, em centavos.

created_atstring

Quando (RFC 3339).

created_bystring

Quem iniciou (usuário ou system).

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_wallet` nem `manage_payments`.	`{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}`
403	O módulo `digital-wallet` está desligado na loja.	`{"error":"module_disabled","module":"digital-wallet"}`
500	`user_id` malformado.	`{"error":"failed to list transactions","detail":"..."}`

Veja também

Carteiras