> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/pt-br/billing-api/wallet.md).
# Carteira
## Visão geral
A API de carteira permite que os anunciantes gerenciem carteiras digitais usadas para orçamentação de campanhas e controle de gastos. Cada carteira está vinculada a uma única moeda e equipe, e suporta recursos como orçamentos diários e gerenciamento de fundos.
Os anunciantes podem manter várias carteiras, cada uma com seu próprio saldo de crédito e controles de gastos. Com essas APIs, você pode:
* Gerenciar nomes de carteira
* Visualizar IDs de carteira
* Acessar códigos de moeda
* Definir orçamentos diários
* Verificar saldos atuais
* Visualizar saldos disponíveis
* Controlar estados de arquivamento
* Gerenciar fundos (Apenas varejistas) e mais
### Fundamentos da carteira
#### Propósito
As carteiras são ferramentas essenciais para os anunciantes gerenciarem, controlarem e relatarem orçamentos de campanhas. Elas permitem o rastreamento granular por região, produto ou equipe, e suportam orçamentação e controle de gastos específicos por moeda.
Suponha que sua equipe de marketing precise executar campanhas para três regiões (EUA, UE, APAC), cada uma com seu próprio orçamento e moeda. Você cria três carteiras:
* **US Wallet (USD)**: $20.000, limite diário $2.000.
* **EU Wallet (EUR)**: €15.000, limite diário €1.500.
* **APAC Wallet (AUD)**: A$10.000, limite diário A$1.000.
Cada campanha está vinculada à carteira de sua região. Se a carteira dos EUA ficar baixa, apenas as campanhas dos EUA serão pausadas. UE e APAC continuam inalteradas. Você pode relatar gastos, ROI e ritmo por carteira, e sua equipe financeira pode reconciliar cada carteira separadamente.
{% hint style="info" %}
Os anunciantes só podem usar carteiras em catálogos de varejistas que suportem a mesma moeda.
{% endhint %}
#### Múltiplas carteiras
Os anunciantes podem criar várias carteiras com base em seu modelo operacional. Cada campanha pode ser vinculada a apenas uma carteira por vez, garantindo uma separação clara do orçamento e o rastreamento de gastos. Você é livre para usar a carteira padrão se não desejar criar várias carteiras.
#### Organização do orçamento entre carteiras
As carteiras ajudam as empresas a gerenciar seus orçamentos de publicidade organizando fundos com base na moeda e no propósito. Por exemplo, grandes organizações podem criar carteiras separadas para diferentes departamentos ou campanhas. Essa configuração permite que cada grupo controle seus próprios gastos diários sem impactar os outros.
Cada carteira mantém um saldo de crédito em sua moeda designada, facilitando o gerenciamento de orçamentos em várias moedas. Os anunciantes podem criar várias carteiras, cada uma com seu próprio saldo de crédito e ID de carteira exclusivo. Esse ID é usado para identificar e gerenciar carteiras individualmente.
{% hint style="info" %}
Você precisa de fundos suficientes em sua carteira para executar uma campanha. Assim que a carteira atinge o orçamento definido, o anúncio para de ser veiculado.
{% endhint %}
Como cada campanha pode ser vinculada a apenas uma carteira por vez, gerenciar os saldos da carteira de forma eficaz é crucial para a veiculação ininterrupta da campanha.
#### Compatibilidade de moeda com catálogos
Alguns recursos de carteira, como criar ou editar carteiras, podem não estar disponíveis para todos os anunciantes, dependendo da configuração do varejista. Se um varejista tiver restrições, você verá mensagens de erro relevantes e certas funções relacionadas à carteira podem ficar oculta na UI.
Ao criar uma campanha e selecionar um catálogo, cada catálogo é associado a uma moeda específica. Você deve escolher uma carteira que corresponda à moeda do catálogo. Por exemplo, se seu catálogo usa AUD (Dólar Australiano), você não pode selecionar uma carteira em GBP (Libra Esterlina). O sistema impedirá que você selecione uma moeda incompatível durante a criação da campanha.
### Recursos da carteira
As carteiras ajudam você a gerenciar orçamentos e gastos em campanhas, incluindo:
* **Suporte a várias carteiras**: Permite a separação de orçamento por equipe, campanha ou departamento.
* **Carteiras específicas por moeda**: Opera em uma única moeda.
* **Carteiras arquivadas**: Mantém o histórico sem afetar as campanhas ativas.
### Elementos da carteira
Cada carteira inclui os seguintes elementos principais:
| Nome | Descrição |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome da carteira | O nome atribuído à carteira. |
| ID da carteira | Um identificador exclusivo usado para cobrar a carteira correta para uma campanha. |
| Moeda | A moeda na qual a carteira opera. |
| Saldo atual | O saldo da carteira excluindo qualquer limite de crédito. |
| Saldo disponível | O valor total gasto, incluindo o limite de crédito. |
| Limite de crédito | Uma tolerância para excesso de gastos que é redefinida mensalmente.
Nota: Este é um recurso legado e não é suportado pela maioria dos varejistas.
|
| Estado arquivado | Indica que a carteira não está mais ativa, mas foi mantida para registros. |
Você pode visualizar as carteiras da sua equipe na seção **Carteiras**. Dependendo da configuração do seu varejista, você pode ter acesso para visualizar ou modificar configurações específicas de carteira.
#### Exemplo
A Empresa A planeja alocar seu orçamento de publicidade em três tipos de produtos: $10.000 para o Produto A, $5.000 para o Produto B e $1.200 para o Produto C. Para gerenciar isso, a empresa cria três carteiras separadas, uma para cada tipo de produto com os valores correspondentes.
Ao configurar campanhas, cada campanha é vinculada à carteira atribuída ao seu respetivo produto. Essa configuração permite que a equipe controle e monitore os gastos com publicidade para cada tipo de produto de forma independente, garantindo que os orçamentos sejam usados conforme pretendido.
#### O que é um ID externo?
Um **ID externo** é um campo opcional onde você pode armazenar números de referência personalizados, como um pedido de compra, ID do Salesforce ou número do Placement IO. Ele ajuda os parceiros a rastrear e vincular a carteira aos seus próprios sistemas.
> **Nota:** Este campo fica visível apenas se o seu varejista tiver ativado a flag do recurso.
### Limite de orçamento e ritmo
Para ajudar os anunciantes a gerenciar seus gastos diários com anúncios de forma eficaz, as carteiras suportam os seguintes controles:
#### Limite diário / Gasto diário
O valor máximo que uma carteira pode gastar em um único dia. Esse limite garante que as campanhas não excedam um orçamento diário predefinido.
#### Ritmo do orçamento
Se todo o limite diário não for gasto em um determinado dia, o valor não gasto acumula para o dia seguinte. Isso permite um ritmo flexível do orçamento ao longo de vários dias.
#### Limite diário restante
A parcela do limite diário que permanece não gasta do dia anterior. Esse valor é adicionado ao limite diário do dia seguinte, permitindo flexibilidade de gastos cumulativos.
> **Nota:** A disponibilidade de limites de orçamento diário está sujeita à ativação da flag do recurso pelo varejista.
### Endpoints disponíveis
| Endpoint | Descrição |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Create wallet](/retail-media-interface/partner/pt-br/billing-api/wallet/createwallet.md) | Configure uma nova carteira com um namespace, equipe, nome, moeda, orçamento diário e ID externo opcional. |
| [Update wallet](/retail-media-interface/partner/pt-br/billing-api/wallet/updatewallet-1.md) | Modifique o nome da carteira, moeda, orçamento diário, limite de crédito ou ID externo. |
| [Retrieve wallet by ID](/retail-media-interface/partner/pt-br/billing-api/wallet/getwallet-1.md) | Busque os detalhes da carteira usando seu identificador exclusivo. |
| [List all wallets](/retail-media-interface/partner/pt-br/billing-api/wallet/listwallets.md) | Obtenha uma lista de todas as carteiras associadas à sua equipe. |
| [Get balance of specific wallet](/retail-media-interface/partner/pt-br/billing-api/wallet/getwalletbalance.md) | Verifique os saldos atual e disponível, usando seu identificador exclusivo. |
| [Manage funds to specific wallet](/retail-media-interface/partner/pt-br/billing-api/wallet/managefunds.md) | Adicione fundos a uma carteira para aumentar seu saldo disponível para gastos com campanhas. |
### Definições de campos da API de Carteira
A seguir estão os principais campos de carteira comumente usados em solicitações e respostas da API:
| Campo | Descrição |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| walletId | Identificador exclusivo da carteira. |
| currency | Código da moeda (ex.: USD, EUR). |
| creditLimit | Limite de gastos extras mensal.
Nota: Este é um recurso legado e não é suportado pela maioria dos varejistas.
|
| dailyBudget | Limite de gasto diário. |
| availableBalance | Valor disponível para gasto, incluindo crédito. |
| currentBalance | Saldo real da carteira, excluindo crédito. |
| externalId | Campo opcional para números de PO, IDs do Salesforce, etc. |
| archived | Sinalizador booleano indicando se a carteira está arquivada. |
Para perguntas frequentes e solução de problemas, consulte [Perguntas frequentes](/retail-media-interface/partner/pt-br/partner-api-overview/frequently-asked-questions.md#wallet).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.citrusad.com/retail-media-interface/partner/pt-br/billing-api/wallet.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.