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

bash

curl -X GET "$BASE_URL/api/v1/vendor/ads/wallet" \
  -H "Authorization: Bearer $TOKEN"

200Carteira

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"
    }
  ]
}

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

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
}'

200Carteira após a recarga

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"
    }
  ]
}

Campos da resposta

...object

A carteira completa, como acima.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"]}`
403	O usuário autenticado não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`amount_cents` abaixo de 5000 ou ausente.	`{"error":"failed to top up wallet","detail":"minimum top-up is 5000 centavos"}`

Veja também

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

bash

curl -X GET "$BASE_URL/api/v1/vendor/ads/wallet" \
  -H "Authorization: Bearer $TOKEN"

200Carteira

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"
    }
  ]
}

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

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
}'

200Carteira após a recarga

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"
    }
  ]
}

Campos da resposta

...object

A carteira completa, como acima.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"]}`
403	O usuário autenticado não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`amount_cents` abaixo de 5000 ou ausente.	`{"error":"failed to top up wallet","detail":"minimum top-up is 5000 centavos"}`