VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
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

Resposta

200Busca de clientes (com q)
200Carteiras (sem q)

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

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

A chave de topo muda conforme a presença de q (users ou wallets). Escreva o parser tratando os dois.

Ver os totais

GET/api/v1/admin/wallets/summaryAdmin

Totais das carteiras

Exemplo de requisição

Resposta

200Totais

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

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_wallet nem manage_payments.{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}
403O 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

Resposta

200Saldo

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

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_wallet nem manage_payments.{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}
403O módulo digital-wallet está desligado na loja.{"error":"module_disabled","module":"digital-wallet"}
500user_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 cria a carteira

Para um cliente sem carteira, esta rota cria uma carteira vazia e devolve saldo 0. Não use para checar existência.

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

Resposta

200Transações

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

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

Veja também

  • Carteiras
Anterior
Carteiras de crédito
Próxima
Ajustar, reembolsar e congelar
Nesta página
  • Listar carteiras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver os totais
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar o saldo de um cliente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar o extrato
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/wallets?q=marina&per_page=20" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/wallets/summary" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"
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
}
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
}
json
{
  "total_credits": 150825,
  "total_debits": 2400,
  "active_wallets": 8
}
json
{
  "balance": 698,
  "status": "active",
  "total_credits": 698,
  "total_debits": 0
}
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
}