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

Ajustar, reembolsar e congelar

Lança crédito ou débito manual, reembolsa um pedido para a carteira e congela ou descongela.

Toda movimentação fica registrada no extrato e no log de ações do painel, com o administrador que a fez.

Ajustar o saldo

Credita ou debita o saldo com uma justificativa obrigatória. Use type para dar o sentido e envie amount sempre positivo.

POST/api/v1/admin/wallets/{user_id}/adjustAdmin

Ajuste manual

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Corpo da requisição

typestring

creditdebit

credit ou debit. Se omitido, vale o sinal de amount (positivo = crédito, negativo = débito).

amountintegerobrigatório

Valor em centavos, diferente de zero.

descriptionstringobrigatório

Motivo do ajuste. Obrigatório; fica no extrato.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/adjust" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credit",
    "amount": 2500,
    "description": "Compensação por atraso na entrega do pedido 1234"
  }'

Resposta

200Ajuste feito

json

{
  "message": "wallet adjusted",
  "transaction": {
    "id": "b761af68-16bd-4141-8183-9a56948050e5",
    "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
    "amount": 2500,
    "type": "credit",
    "reference_type": "admin",
    "reference_id": "",
    "description": "Compensação por atraso na entrega do pedido 1234",
    "balance_after": 3198,
    "created_at": "2026-09-17T05:28:00Z",
    "created_by": "2d3e4f5a-6b7c-4d8e-9f01-a2b3c4d5e6f7"
  }
}

Campos da resposta

messagestring

Texto fixo wallet adjusted.

transactionobject

A transação criada (campos do extrato).

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido, `type` desconhecido, `amount` zero, `description` vazia, débito acima do saldo ou carteira congelada.	`{"error":"description is required for admin adjustments"}`
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 ou falha interna.	`{"error":"failed to adjust wallet","detail":"..."}`

Reembolsar para a carteira

Credita na carteira o valor de um pedido, como reembolso em crédito da loja. A transação fica com reference_type: refund e reference_id igual ao pedido.

POST/api/v1/admin/wallets/{user_id}/refundAdmin

Reembolsa para a carteira

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Corpo da requisição

order_idstringobrigatório

Pedido de origem. Fica só como referência.

amountintegerobrigatório

Valor em centavos, maior que zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 4990
  }'

Resposta

200Crédito lançado

json

{
  "message": "refund credited to wallet",
  "transaction": {
    "id": "b761af68-16bd-4141-8183-9a56948050e5",
    "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
    "amount": 4990,
    "type": "credit",
    "reference_type": "refund",
    "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "description": "",
    "balance_after": 5688,
    "created_at": "2026-09-17T05:28:00Z",
    "created_by": "system"
  }
}

Campos da resposta

messagestring

refund credited to wallet.

transactionobject

A transação criada.

Erros

Status	Quando	Corpo de exemplo
400	`order_id` ausente, `amount` não positivo ou carteira congelada.	`{"error":"order_id is required"}`
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"}`

Congelar

POST/api/v1/admin/wallets/{user_id}/freezeAdmin

Congela a carteira

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Exemplo de requisição

bash

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

Resposta

200Congelada

json

{
  "message": "wallet frozen"
}

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	Cliente sem carteira (`wallet not found for user ...`) ou `user_id` malformado.	`{"error":"failed to freeze wallet","detail":"wallet not found for user ..."}`

Descongelar

POST/api/v1/admin/wallets/{user_id}/unfreezeAdmin

Descongela a carteira

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Exemplo de requisição

bash

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

Resposta

200Descongelada

json

{
  "message": "wallet unfrozen"
}

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	Cliente sem carteira ou `user_id` malformado.	`{"error":"failed to unfreeze wallet","detail":"wallet not found for user ..."}`

Veja também

Carteiras

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

Ajustar, reembolsar e congelar

Lança crédito ou débito manual, reembolsa um pedido para a carteira e congela ou descongela.

Toda movimentação fica registrada no extrato e no log de ações do painel, com o administrador que a fez.

Ajustar o saldo

Credita ou debita o saldo com uma justificativa obrigatória. Use type para dar o sentido e envie amount sempre positivo.

POST/api/v1/admin/wallets/{user_id}/adjustAdmin

Ajuste manual

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Corpo da requisição

typestring

creditdebit

credit ou debit. Se omitido, vale o sinal de amount (positivo = crédito, negativo = débito).

amountintegerobrigatório

Valor em centavos, diferente de zero.

descriptionstringobrigatório

Motivo do ajuste. Obrigatório; fica no extrato.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/adjust" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credit",
    "amount": 2500,
    "description": "Compensação por atraso na entrega do pedido 1234"
  }'

Resposta

200Ajuste feito

json

{
  "message": "wallet adjusted",
  "transaction": {
    "id": "b761af68-16bd-4141-8183-9a56948050e5",
    "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
    "amount": 2500,
    "type": "credit",
    "reference_type": "admin",
    "reference_id": "",
    "description": "Compensação por atraso na entrega do pedido 1234",
    "balance_after": 3198,
    "created_at": "2026-09-17T05:28:00Z",
    "created_by": "2d3e4f5a-6b7c-4d8e-9f01-a2b3c4d5e6f7"
  }
}

Campos da resposta

messagestring

Texto fixo wallet adjusted.

transactionobject

A transação criada (campos do extrato).

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido, `type` desconhecido, `amount` zero, `description` vazia, débito acima do saldo ou carteira congelada.	`{"error":"description is required for admin adjustments"}`
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 ou falha interna.	`{"error":"failed to adjust wallet","detail":"..."}`

Reembolsar para a carteira

Credita na carteira o valor de um pedido, como reembolso em crédito da loja. A transação fica com reference_type: refund e reference_id igual ao pedido.

POST/api/v1/admin/wallets/{user_id}/refundAdmin

Reembolsa para a carteira

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Corpo da requisição

order_idstringobrigatório

Pedido de origem. Fica só como referência.

amountintegerobrigatório

Valor em centavos, maior que zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 4990
  }'

Resposta

200Crédito lançado

json

{
  "message": "refund credited to wallet",
  "transaction": {
    "id": "b761af68-16bd-4141-8183-9a56948050e5",
    "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
    "amount": 4990,
    "type": "credit",
    "reference_type": "refund",
    "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "description": "",
    "balance_after": 5688,
    "created_at": "2026-09-17T05:28:00Z",
    "created_by": "system"
  }
}

Campos da resposta

messagestring

refund credited to wallet.

transactionobject

A transação criada.

Erros

Status	Quando	Corpo de exemplo
400	`order_id` ausente, `amount` não positivo ou carteira congelada.	`{"error":"order_id is required"}`
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"}`

Congelar

POST/api/v1/admin/wallets/{user_id}/freezeAdmin

Congela a carteira

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Exemplo de requisição

bash

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

Resposta

200Congelada

json

{
  "message": "wallet frozen"
}

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	Cliente sem carteira (`wallet not found for user ...`) ou `user_id` malformado.	`{"error":"failed to freeze wallet","detail":"wallet not found for user ..."}`

Descongelar

POST/api/v1/admin/wallets/{user_id}/unfreezeAdmin

Descongela a carteira

Parâmetros de caminho

user_iduuidobrigatório

Id do cliente dono da carteira.

Exemplo de requisição

bash

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

Resposta

200Descongelada

json

{
  "message": "wallet unfrozen"
}

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	Cliente sem carteira ou `user_id` malformado.	`{"error":"failed to unfreeze wallet","detail":"wallet not found for user ..."}`

Veja também

Carteiras