> For the complete documentation index, see [llms.txt](https://docs.smsfunnel.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfunnel.com.br/api/parceiros/saldo-e-carteira.md).

# Saldo e Carteira

Como a API de Parceiros informa o seu saldo, como ele é consumido e o que acontece quando ele acaba.

{% hint style="success" %}
**A URL de base de todos os endpoints é**: <https://web.smsfunnel.com.br/api/parceiros/v1>
{% endhint %}

#### Duas formas de cobrança

A SMS Funnel está migrando a cobrança dos **pacotes de créditos** (unidades de SMS e de ligação) para a **Carteira**, um saldo único em reais (R$) usado por todos os canais.

| Forma de cobrança      | Como funciona                                                       | Canais                                                                    |
| ---------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Carteira (R$)**      | Um único saldo em reais. Cada envio debita o valor do seu contrato. | WhatsApp e IA (todas as contas); SMS e Ligação para as contas já migradas |
| **Pacote de créditos** | Saldo em unidades, separado por canal.                              | SMS e Ligação das contas que ainda não migraram                           |

A migração é feita **por canal**: sua conta pode ter, por exemplo, o SMS na Carteira e as ligações ainda no pacote. Ao migrar um canal, o saldo de unidades dele é convertido para a Carteira e o pacote daquele canal fica zerado.

{% hint style="info" %}
**Como saber qual é a sua forma de cobrança?** Consulte `GET /credits`. Os canais listados em `wallet.billed` são cobrados pela Carteira. Os demais seguem no pacote de créditos.
{% endhint %}

***

#### Consultando o saldo

<mark style="color:green;">**GET**</mark>**&#x20;/credits**

**Função:** Devolve a posição atual do saldo. O mesmo conteúdo também vem no campo `credits` do `GET /me`.

Os parâmetros (`email` / `user_id` para consultar uma conta filha) estão descritos em Requisições.

**Corpo de resposta — conta com SMS e Ligação na Carteira:**

```json5
{
    "wallet": {
        "billed": ["sms", "call", "whatsapp", "ai"], // Canais cobrados pela Carteira
        "currency": "BRL",                           // Moeda do saldo
        "available": "4000.00"                       // Saldo disponível em reais (string, 2 casas). null = não foi possível consultar agora
    },
    "sms": {
        "contracted": 10500, // Histórico do pacote de créditos (anterior à migração)
        "sent": 3200,        // Histórico do pacote de créditos (anterior à migração)
        "available": 50000,  // Estimativa: quantos SMS cabem no saldo da Carteira
        "deprecated": true   // Bloco mantido por compatibilidade — use "wallet"
    },
    "call": {
        "contracted": 0,
        "sent": 0,
        "available": 1428,   // Estimativa: quantas ligações de até 30s cabem no saldo
        "deprecated": true
    }
}
```

**Corpo de resposta — conta com SMS e Ligação ainda no pacote de créditos:**

```json5
{
    "wallet": {
        "billed": ["whatsapp", "ai"], // Só WhatsApp e IA são cobrados pela Carteira
        "currency": "BRL",
        "available": "150.00"
    },
    "sms": {
        "contracted": 2000, // SMS contratados
        "sent": 766,        // SMS enviados
        "available": 1234   // SMS disponíveis no pacote
    },
    "call": {
        "contracted": 0,
        "sent": 0,
        "available": 0
    }
}
```

**Como ler a resposta**

* **`wallet.available`** é o saldo oficial da Carteira, em reais. Ele vem como **string** com duas casas decimais (`"4000.00"`) para não perder precisão.
* **`wallet.available: null`** quer dizer que não conseguimos consultar o saldo naquele momento. Isso **não** é saldo zero: tente novamente em alguns segundos e não interrompa seus envios por causa de um `null`.
* **Canal com `deprecated: true`** é cobrado pela Carteira. O bloco continua na resposta só para não quebrar integrações antigas, e o `available` dele é uma **estimativa** de quantas unidades cabem no saldo pelo preço do seu contrato. A estimativa não é uma reserva e muda se o saldo ou o preço mudarem.
* **Canal sem `deprecated`** segue no pacote de créditos e funciona exatamente como antes.
* **O bloco `whatsapp` não é mais devolvido** quando o WhatsApp é cobrado pela Carteira (o saldo dele é o `wallet.available`). Trate a ausência desse bloco como normal.
* **Conta sem nenhum canal na Carteira** recebe a resposta no formato antigo, sem o bloco `wallet`.

{% hint style="warning" %}
**Integrações que conferem o saldo antes de enviar:** use `wallet.available` quando o canal estiver em `wallet.billed`. Conferir apenas `sms.available` ou `call.available` continua funcionando (são estimativas pelo saldo da Carteira), mas o valor de referência passa a ser o saldo em reais.
{% endhint %}

***

#### Como o saldo é consumido

| Canal   | Unidade cobrada                                                                    | Na Carteira                                        |
| ------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
| SMS     | 1 por mensagem (`bill_factor`)                                                     | Preço do SMS no seu contrato                       |
| Ligação | 1 bloco a cada 30 segundos de áudio, por ligação **atendida** (`credits_per_call`) | Preço do bloco de ligação no seu contrato × blocos |

Os campos `bill_factor`, `credits_per_call`, `estimated_credits` e `total_credits_used` continuam expressos **em unidades** (SMS ou blocos de 30s), não em reais. Para quem é cobrado pela Carteira, o valor em reais é essa quantidade multiplicada pelo preço do seu contrato.

{% hint style="info" %}
O valor é **reservado** no momento do envio e **efetivado** quando a mensagem sai ou a ligação é atendida. Mensagens que não saem (telefone inválido, blacklist, cancelamento) e ligações não atendidas têm a reserva devolvida ao saldo.
{% endhint %}

***

#### Quando o saldo não é suficiente

O comportamento depende da forma de cobrança do canal.

**SMS — `POST /sms/messages`**

|                          | Pacote de créditos                                                                          | Carteira                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| No momento da requisição | Créditos menores que a quantidade de mensagens → `402 INSUFFICIENT_CREDITS`. Nada é criado. | A requisição é **sempre aceita** (`202`). O saldo é conferido no processamento.                    |
| Saldo cobre tudo         | Envia tudo.                                                                                 | Envia tudo.                                                                                        |
| Saldo cobre parte        | — (recusado antes, com 402)                                                                 | **Envio parcial**: sai o que o saldo paga, e o restante das mensagens fica com status `cancelled`. |
| Sem saldo                | — (recusado antes, com 402)                                                                 | Todas as mensagens ficam `cancelled`.                                                              |

{% hint style="warning" %}
Se a sua conta é cobrada pela Carteira, **um `202` não garante que todas as mensagens serão enviadas**. Acompanhe o broadcast em `GET /sms/broadcasts/{id}` (campo `metrics.failed`) ou pelo Webhook de status, e consulte `GET /credits` antes de grandes disparos.
{% endhint %}

**SMS de campanhas (sequências)**

A inserção de leads (`POST /lists/{id}/leads` e `POST /sms/campaigns/{id}/leads`) **não confere saldo**: os leads sempre entram e as sequências são agendadas. O saldo é conferido no momento de cada envio. Se não houver saldo, aquela mensagem da sequência é cancelada (`cancelled` em `GET /sms/sequences/{id}/messages`).

**Ligações — `POST /calls/broadcasts`**

A criação só é recusada com `402 INSUFFICIENT_CREDITS` quando **não há saldo nem para uma ligação**. Saldo menor que o custo total é aceito. O que acontece quando o saldo acaba no meio do disparo:

| Pacote de créditos                                                       | Carteira                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| O contato volta para a fila e é discado novamente depois de uma recarga. | Sai o que o saldo cobre. Enquanto houver ligações em andamento, o restante aguarda o resultado delas (ligação não atendida devolve o valor ao saldo). Sem nenhuma em andamento, os contatos restantes são encerrados como `cancelled`. |

**Áudios por TTS — `POST /calls/audios` e `POST /calls/audios/preview-tts`**

Exigem saldo disponível para ao menos uma ligação. Sem saldo, a resposta é `402 INSUFFICIENT_CREDITS`. O upload de arquivo não passa por essa verificação.

{% hint style="info" %}
No `402` das rotas de ligação, `details.available_credits` mostra o saldo **do pacote de créditos**. Se a sua conta é cobrada pela Carteira, consulte o saldo em `GET /credits` (`wallet.available`).
{% endhint %}

***

#### Recargas

`GET /recharges` lista as recargas confirmadas (veja Requisições). Recargas feitas **por valor** na Carteira aparecem com `"credits": 0`; nesse caso, o valor creditado é o `total`, em reais.

***

#### Agências

Ao operar uma conta filha com `X-On-Behalf-Of` (veja Agências), o saldo consultado e debitado é sempre **o da conta filha**, seja ele pacote de créditos ou Carteira.

***

#### Perguntas frequentes

**Minha integração lia `sms.available` e parou de funcionar. O que mudou?**\
Para contas cobradas pela Carteira, `sms.available` passou a ser a quantidade de SMS que cabe no saldo em reais. Se o seu código também lê `whatsapp`, trate a ausência desse bloco.

**Recebi `202` mas parte das mensagens ficou `cancelled`. Por quê?**\
Na Carteira, o saldo é conferido no processamento. Se ele cobria só parte do lote, o restante é cancelado e nada é cobrado pelas canceladas. Recarregue e reenvie apenas as mensagens canceladas.

**`wallet.available` veio `null`. Meu saldo zerou?**\
Não. `null` indica indisponibilidade temporária da consulta. Repita a chamada depois de alguns segundos.

**Os blocos com `deprecated: true` vão deixar de existir?**\
Eles continuam na resposta por compatibilidade. Para novas integrações, use o bloco `wallet`.

**Dúvidas?**

Em caso de dúvidas, entre em contato com nosso suporte.
