VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Venddor Ads

Carteira de mídia

Mostra o saldo e os últimos movimentos da carteira do Ads e permite recarregá-la.

A carteira é o saldo que paga os cliques. As duas rotas exigem um privilégio financeiro do seller (vendor_financial ou equivalente); o dono da loja sempre tem.

Consultar a carteira

GET/api/v1/vendor/ads/walletSeller

Saldo e movimentos da carteira

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Exemplo de requisição

200Carteira

Campos da resposta

vendor_iduuid
Seller dono da carteira.
balance_centsinteger
Saldo atual em centavos.
transactionsarray

Os 100 movimentos mais recentes, do mais novo para o mais antigo.

iduuid
Id do movimento.
vendor_iduuid
Seller.
campaign_iduuid
Campanha que gerou a cobrança. Ausente nas recargas.
typestring
topupclick_charge
topup (entrada, valor positivo) ou click_charge (cobrança de clique, valor negativo).
amount_centsinteger
Valor em centavos, com sinal.
created_atstring
Data do movimento (RFC 3339, UTC).

Recarregar a carteira

POST/api/v1/vendor/ads/wallet/topupSeller

Recarrega a carteira de mídia

O valor entra no saldo na hora e é registrado como uma dívida de mídia do seller, descontada integralmente dos próximos repasses. Nenhum cartão ou Pix é cobrado nesta chamada.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Corpo da requisição

amount_centsintegerobrigatório
Valor em centavos. Mínimo 5000 (R$ 50,00).

Exemplo de requisição

200Carteira após a recarga

Campos da resposta

...object
A carteira completa, como acima.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário do seller (equipe) não tem nenhum dos privilégios exigidos. O dono da loja nunca recebe este erro.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial","vendor_request_payouts","vendor_view_commissions","vendor_view_debts","vendor_view_referrals"]}
403O usuário autenticado não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}
400JSON inválido.{"error":"invalid request body","detail":"..."}
400amount_cents abaixo de 5000 ou ausente.{"error":"failed to top up wallet","detail":"minimum top-up is 5000 centavos"}
Recarga é dívida

Cada recarga cria uma dívida do mesmo valor, descontada a 100% dos repasses do seller até ser quitada. Avise quem opera o painel: recarregar R$ 1.000,00 reduz os próximos repasses em R$ 1.000,00, mesmo que a carteira ainda não tenha sido gasta. Não há rota de seller para estornar o saldo.

Veja também

  • Criar e alterar
  • Mudar status
  • Visão geral do Ads
Anterior
Mudar status da campanha
Próxima
Newsletter e formulários
Nesta página
  • Consultar a carteira
  • Exemplo de requisição
  • Recarregar a carteira
  • Exemplo de requisição
  • Erros
  • Veja também
bash
curl -X GET "$BASE_URL/api/v1/vendor/ads/wallet" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/ads/wallet/topup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 10000
}'
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "balance_cents": 10000,
  "transactions": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "campaign_id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "type": "click_charge",
      "amount_cents": -34,
      "created_at": "2026-10-11T15:20:00Z"
    },
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "type": "topup",
      "amount_cents": 10034,
      "created_at": "2026-10-11T12:05:00Z"
    }
  ]
}
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "balance_cents": 20000,
  "transactions": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "type": "topup",
      "amount_cents": 10034,
      "created_at": "2026-10-11T12:05:00Z"
    }
  ]
}