> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Carteiras (Wallet)

> Consulte saldo, adicione créditos e acompanhe as transações da carteira do WhatsApp Oficial

# Carteiras (Wallet)

O canal do WhatsApp Oficial é **pré-pago**: cada conta conectada tem uma carteira, criada automaticamente, de onde sai o custo das conversas. Sem saldo, os envios falham.

Todas as operações usam `POST /api/v1/message/SendCommand` com `content.type: "WALLET"`, variando o `commandType`. A resposta síncrona é sempre `{ "packageId": "..." }`; o resultado chega no webhook do canal de feedback. Use `correlationId` para correlacionar.

| `commandType`  | Operação                                       | Webhook de resposta            |
| -------------- | ---------------------------------------------- | ------------------------------ |
| `LIST`         | Lista as carteiras da conta                    | `WALLET_LIST_RESPONSE`         |
| `BALANCE`      | Consulta o saldo                               | `WALLET_BALANCE_RESPONSE`      |
| `ADD_FUND`     | Gera link de pagamento para adicionar créditos | `WALLET_ADD_FUND_RESPONSE`     |
| `TRANSACTIONS` | Extrato de transações                          | `WALLET_TRANSACTIONS_RESPONSE` |
| `CREDIT`       | Crédito administrativo (sem pagamento)         | `WALLET_CREDIT_RESPONSE`       |

### Objeto `wallet`

Presente nas respostas:

| Campo                     | Tipo     | Descrição                    |
| ------------------------- | -------- | ---------------------------- |
| `id`                      | uuid     | Identificador da carteira    |
| `balance`                 | number   | Saldo atual                  |
| `currency`                | string   | Moeda (ex.: `BRL`)           |
| `name`                    | string   | Nome (ex.: `Principal`)      |
| `isDefault`               | boolean  | Carteira padrão da conta     |
| `createdAt` / `updatedAt` | datetime | Datas de criação/atualização |

## Listar carteiras

```json theme={null}
{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "listar-carteiras-01",
  "content": { "type": "WALLET", "commandType": "LIST" }
}
```

Webhook:

```json theme={null}
{
  "correlationId": "listar-carteiras-01",
  "content": {
    "type": "WALLET_LIST_RESPONSE",
    "commandType": "WALLET_LIST_RESPONSE",
    "success": true,
    "count": 1,
    "wallets": [
      {
        "id": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
        "balance": 0,
        "currency": "BRL",
        "name": "Principal",
        "isDefault": true,
        "createdAt": "2026-07-06T22:52:29.423565+00:00"
      }
    ]
  }
}
```

## Consultar saldo

```json theme={null}
{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "saldo-01",
  "content": { "type": "WALLET", "commandType": "BALANCE" }
}
```

Webhook: `WALLET_BALANCE_RESPONSE` com o objeto `wallet` (mesmos campos acima).

## Adicionar fundos

Gera um **link de checkout** para pagamento; após pagar, o crédito entra na carteira.

```json theme={null}
{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "fundos-01",
  "content": {
    "type": "WALLET",
    "commandType": "ADD_FUND",
    "walletId": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
    "amount": 50,
    "callbackUrl": "https://suaempresa.com.br/funds-added"
  }
}
```

<ParamField body="content.walletId" type="uuid" required>
  Id da carteira (obtenha com `LIST`).
</ParamField>

<ParamField body="content.amount" type="number" required>
  Valor a adicionar, na moeda da carteira.
</ParamField>

<ParamField body="content.callbackUrl" type="string" required>
  URL para onde o pagador é redirecionado após concluir o pagamento.
</ParamField>

Webhook:

```json theme={null}
{
  "correlationId": "fundos-01",
  "content": {
    "type": "WALLET_ADD_FUND_RESPONSE",
    "commandType": "WALLET_ADD_FUND_RESPONSE",
    "success": true,
    "link": "https://metaguru.../checkout?state=...",
    "fundRequestId": "0023817d-6f5d-4c0d-86ab-e7f0c7e2de49"
  }
}
```

Entregue o `link` a quem vai pagar.

## Extrato (transações)

```json theme={null}
{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "extrato-01",
  "content": { "type": "WALLET", "commandType": "TRANSACTIONS" }
}
```

Webhook:

```json theme={null}
{
  "correlationId": "extrato-01",
  "content": {
    "type": "WALLET_TRANSACTIONS_RESPONSE",
    "commandType": "WALLET_TRANSACTIONS_RESPONSE",
    "success": true,
    "count": 1,
    "transactions": [
      {
        "id": "428d7e3b-7a19-4e4e-916d-9959aea8f976",
        "walletId": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
        "type": "Credit",
        "amount": 5,
        "description": "Adição de Crédito",
        "referenceId": "25adeb56-5384-4f7c-b987-55385dead5ac",
        "createdAt": "2026-07-08T19:29:45.758302+00:00",
        "wallet": { "id": "1eed9c1d-9977-4d91-810e-1819087ca8b6", "balance": 10, "currency": "BRL", "name": "Principal", "isDefault": true }
      }
    ]
  }
}
```

## Crédito administrativo

`CREDIT` credita a carteira **sem passar por pagamento**. É uma operação administrativa, restrita a fluxos internos/autorizados:

```json theme={null}
{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "credito-admin-01",
  "content": {
    "type": "WALLET",
    "commandType": "CREDIT",
    "walletId": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
    "amount": 5
  }
}
```

Webhook: `WALLET_CREDIT_RESPONSE` com `success` e `message`.

<Note>
  Em caso de erro em qualquer operação, o webhook chega com `success: false` e o campo `error`
  preenchido (o `type` pode vir como `WALLET_RESPONSE` quando a operação não é reconhecida).
</Note>