API atual/Referência completa/Créditos e descontos

Carteira digital

Consulta saldo e extrato da carteira do cliente e paga pedidos com ela.

A carteira guarda crédito do cliente na loja. Estas rotas exigem o token do cliente e o módulo digital-wallet; sem o módulo, respondem 403 module_disabled.

Ver minha carteira

A carteira digital é o saldo em reais que o cliente tem na loja (reembolsos, créditos, bônus) e pode usar para pagar pedidos. Esta rota devolve o saldo e os totais. Se o cliente ainda não tem carteira, ela é criada vazia na primeira consulta.

GET/api/v1/storefront/walletCliente

Saldo e totais da carteira do cliente

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wallet" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Carteira

json

{
  "balance": 7500,
  "status": "active",
  "total_credits": 15000,
  "total_debits": 7500
}

Campos da resposta

balanceinteger

Saldo atual, em centavos.

statusstring

activefrozen

frozen: a loja congelou a carteira; não aceita crédito nem débito.

total_creditsinteger

Soma de todos os créditos já recebidos, em centavos.

total_debitsinteger

Soma de todos os débitos já feitos, em centavos (valor positivo).

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `digital-wallet` está desligado nesta loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Extrato da carteira

Lista os créditos e débitos da carteira, do mais recente para o mais antigo.

GET/api/v1/storefront/wallet/transactionsCliente

Lançamentos da carteira, com paginação

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wallet/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Página do extrato

json

{
  "transactions": [
    {
      "id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f",
      "wallet_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "amount": -5000,
      "type": "debit",
      "reference_type": "order",
      "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "description": "Payment for order 3f73310d-bfdd-4713-a664-305c08eda58b",
      "balance_after": 7500,
      "created_at": "2026-10-11T15:15:00Z",
      "created_by": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

transactionsarray

Lançamentos da página.

iduuid

Id do lançamento.

wallet_iduuid

A carteira.

amountinteger

Valor em centavos: positivo para crédito, negativo para débito.

typestring

creditdebit

Tipo do lançamento.

reference_typestring

orderrefundadmingift_cert

O que originou o lançamento.

reference_idstring

Id da origem (por exemplo, o pedido).

descriptionstring

Texto do lançamento.

balance_afterinteger

Saldo depois deste lançamento, em centavos.

created_atstring

Quando ocorreu (RFC 3339).

created_bystring

Quem iniciou: o cliente, um administrador ou o sistema.

totalinteger

Total de lançamentos.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página aplicado.

total_pagesinteger

Número de páginas.

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `digital-wallet` está desligado nesta loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Pagar com a carteira

Debita o valor informado do saldo da carteira, vinculado ao pedido. O débito é imediato e atômico. No checkout normal a plataforma usa a carteira sozinha; use esta rota apenas num checkout próprio.

POST/api/v1/storefront/wallet/applyCliente

Debita a carteira para pagar (parte de) um pedido

Corpo da requisição

order_iduuidobrigatório

Pedido que está sendo pago.

amountintegerobrigatório

Valor a debitar, em centavos, maior que zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wallet/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 5000
  }'

Resposta

200Débito feito

json

{
  "message": "wallet payment applied",
  "transaction": {
    "id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f",
    "wallet_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "amount": -5000,
    "type": "debit",
    "reference_type": "order",
    "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "description": "Payment for order 3f73310d-bfdd-4713-a664-305c08eda58b",
    "balance_after": 7500,
    "created_at": "2026-10-11T15:15:00Z",
    "created_by": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a"
  }
}

Campos da resposta

messagestring

Texto fixo em inglês.

transactionobject

O lançamento criado.

iduuid

Id do lançamento.

wallet_iduuid

A carteira.

amountinteger

Valor em centavos: positivo para crédito, negativo para débito.

typestring

creditdebit

Tipo do lançamento.

reference_typestring

orderrefundadmingift_cert

O que originou o lançamento.

reference_idstring

Id da origem (por exemplo, o pedido).

descriptionstring

Texto do lançamento.

balance_afterinteger

Saldo depois deste lançamento, em centavos.

created_atstring

Quando ocorreu (RFC 3339).

created_bystring

Quem iniciou: o cliente, um administrador ou o sistema.

Erros

Status	Quando	Corpo de exemplo
400	`order_id` ausente, `amount` não positivo, ou saldo insuficiente (a mensagem mostra o saldo e o pedido, em centavos).	`{"error":"insufficient wallet balance: have 3000 centavos, need 5000"}`
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	Carteira congelada, ou módulo desligado.	`{"error":"wallet is frozen, cannot debit"}`
403	O módulo `digital-wallet` está desligado nesta loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Veja também

API atual/Referência completa/Créditos e descontos

Carteira digital

Consulta saldo e extrato da carteira do cliente e paga pedidos com ela.

A carteira guarda crédito do cliente na loja. Estas rotas exigem o token do cliente e o módulo digital-wallet; sem o módulo, respondem 403 module_disabled.

Ver minha carteira

GET/api/v1/storefront/walletCliente

Saldo e totais da carteira do cliente

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wallet" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Carteira

json

{
  "balance": 7500,
  "status": "active",
  "total_credits": 15000,
  "total_debits": 7500
}

Campos da resposta

balanceinteger

Saldo atual, em centavos.

statusstring

activefrozen

frozen: a loja congelou a carteira; não aceita crédito nem débito.

total_creditsinteger

Soma de todos os créditos já recebidos, em centavos.

total_debitsinteger

Soma de todos os débitos já feitos, em centavos (valor positivo).

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `digital-wallet` está desligado nesta loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Extrato da carteira

Lista os créditos e débitos da carteira, do mais recente para o mais antigo.

GET/api/v1/storefront/wallet/transactionsCliente

Lançamentos da carteira, com paginação

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wallet/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Página do extrato

json

{
  "transactions": [
    {
      "id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f",
      "wallet_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "amount": -5000,
      "type": "debit",
      "reference_type": "order",
      "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "description": "Payment for order 3f73310d-bfdd-4713-a664-305c08eda58b",
      "balance_after": 7500,
      "created_at": "2026-10-11T15:15:00Z",
      "created_by": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

transactionsarray

Lançamentos da página.

iduuid

Id do lançamento.

wallet_iduuid

A carteira.

amountinteger

Valor em centavos: positivo para crédito, negativo para débito.

typestring

creditdebit

Tipo do lançamento.

reference_typestring

orderrefundadmingift_cert

O que originou o lançamento.

reference_idstring

Id da origem (por exemplo, o pedido).

descriptionstring

Texto do lançamento.

balance_afterinteger

Saldo depois deste lançamento, em centavos.

created_atstring

Quando ocorreu (RFC 3339).

created_bystring

Quem iniciou: o cliente, um administrador ou o sistema.

totalinteger

Total de lançamentos.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página aplicado.

total_pagesinteger

Número de páginas.

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `digital-wallet` está desligado nesta loja.	`{"error":"module_disabled","module":"digital-wallet"}`

Pagar com a carteira

POST/api/v1/storefront/wallet/applyCliente

Debita a carteira para pagar (parte de) um pedido

Corpo da requisição

order_iduuidobrigatório

Pedido que está sendo pago.

amountintegerobrigatório

Valor a debitar, em centavos, maior que zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wallet/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 5000
  }'

Resposta

200Débito feito

json

{
  "message": "wallet payment applied",
  "transaction": {
    "id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f",
    "wallet_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "amount": -5000,
    "type": "debit",
    "reference_type": "order",
    "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "description": "Payment for order 3f73310d-bfdd-4713-a664-305c08eda58b",
    "balance_after": 7500,
    "created_at": "2026-10-11T15:15:00Z",
    "created_by": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a"
  }
}

Campos da resposta

messagestring

Texto fixo em inglês.

transactionobject

O lançamento criado.

iduuid

Id do lançamento.

wallet_iduuid

A carteira.

amountinteger

Valor em centavos: positivo para crédito, negativo para débito.

typestring

creditdebit

Tipo do lançamento.

reference_typestring

orderrefundadmingift_cert

O que originou o lançamento.

reference_idstring

Id da origem (por exemplo, o pedido).

descriptionstring

Texto do lançamento.

balance_afterinteger

Saldo depois deste lançamento, em centavos.

created_atstring

Quando ocorreu (RFC 3339).

created_bystring

Quem iniciou: o cliente, um administrador ou o sistema.

Erros

Status	Quando	Corpo de exemplo
400	`order_id` ausente, `amount` não positivo, ou saldo insuficiente (a mensagem mostra o saldo e o pedido, em centavos).	`{"error":"insufficient wallet balance: have 3000 centavos, need 5000"}`
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	Carteira congelada, ou módulo desligado.	`{"error":"wallet is frozen, cannot debit"}`
403	O módulo `digital-wallet` está desligado nesta loja.	`{"error":"module_disabled","module":"digital-wallet"}`