# Consultando saldo

## Consultando o Saldo

A consulta de saldo na API do Pagou permite obter o saldo disponível do cliente associado à chave de API utilizada.

### Visão Geral Técnica

O endpoint <mark style="color:purple;">`GET`</mark>` ``/v1/customers/balance` retorna o saldo disponível do cliente em reais, identificado pela chave de API fornecida no cabeçalho `X-API-KEY`. A operação é síncrona, retornando `200 OK` com um corpo JSON contendo o campo balance.

**Especificações**:

* **Método**: GET
* **URL**:
  * Produção: `https://api.pagou.com.br/v1/customers/balance`
  * Sandbox: `https://sandbox.api.pagou.com.br/v1/customers/balance`
* **Autenticação**: Cabeçalho `X-API-KEY` com chave do painel.
* **Content-Type**: `application/json`
* **Resposta**: Status `200 OK` com corpo JSON contendo o saldo do cliente.
* **Erros**: `400 Bad Request`, `401 Unauthorized`, `404 Not Found`, `500 Internal Server Error`.

### Cabeçalhos

| Cabeçalho      | Valor                    | Descrição                                        |
| -------------- | ------------------------ | ------------------------------------------------ |
| `X-API-KEY`    | `sua_chave_api`          | Chave de autenticação.                           |
| `Content-Type` | `application/json`       | Formato JSON para a requisição.                  |
| `User-Agent`   | `NomeDaSuaAplicacao/1.0` | Identificador da aplicação (ex.: MinhaLoja/1.0). |

### Resposta

* **Status**: `200 OK`
* **Corpo**: JSON com o saldo disponível do cliente.

**Exemplo de Resposta**:

```json
{
  "balance": 1000.50
}
```

**Campos da Resposta**:

| Campo     | Tipo   | Descrição                                                             |
| --------- | ------ | --------------------------------------------------------------------- |
| `balance` | number | Saldo disponível do cliente em reais (ex.: 1000.50 para R$ 1.000,50). |

### Exemplos de Código

{% tabs %}
{% tab title="cURL" %}

```ruby
curl -X GET https://sandbox.api.pagou.com.br/v1/customers/balance \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaLoja/1.0"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const fetch = require('node-fetch');

// Configuração
const url = 'https://sandbox.api.pagou.com.br/v1/customers/balance';
const headers = {
    'X-API-KEY': 'sua_chave_api',
    'Content-Type': 'application/json',
    'User-Agent': 'MinhaLoja/1.0'
};

fetch(url, {
    method: 'GET',
    headers: headers
})
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); });
        }
        return response.json();
    })
    .then(data => {
        console.log(`Saldo disponível: R$ ${data.balance.toFixed(2)}`);
    })
    .catch(error => console.error('Erro na requisição:', error));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

# Configuração
url = "https://sandbox.api.pagou.com.br/v1/customers/balance"
headers = {
    "X-API-KEY": "sua_chave_api",
    "Content-Type": "application/json",
    "User-Agent": "MinhaLoja/1.0"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    print(f"Saldo disponível: R$ {data['balance']:.2f}")
except requests.RequestException as e:
    print(f"Erro na requisição: {e}")
    if e.response:
        print(f"Detalhes: {e.response.json()}")
```

{% endtab %}
{% endtabs %}

### Tratamento de Erros

| Código HTTP | Descrição             | Possível Causa                                     | Solução                                             |
| ----------- | --------------------- | -------------------------------------------------- | --------------------------------------------------- |
| 400         | Bad Request           | Requisição malformada (ex.: cabeçalhos inválidos). | Verificar formato dos cabeçalhos.                   |
| 401         | Unauthorized          | `X-API-KEY` inválido ou ausente.                   | Verificar chave.                                    |
| 500         | Internal Server Error | Erro interno da API.                               | Tentar novamente e contatar <contato@pagou.com.br>. |

**Exemplo de Resposta de Erro**:

```json
{
  "error": "Customer not found"
}
```

### Boas Práticas Técnicas

* **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições.
* **Monitoramento**: Registre todas as requisições e respostas (incluindo o valor de balance e código de status HTTP) em logs para auditoria e depuração.
* **Testes no Sandbox**: Use <https://sandbox.api.pagou.com.br/v1/customers/balance> para simular consultas de saldo sem impacto em produção.


---

# Agent Instructions: 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:

```
GET https://docs.pagou.com.br/integracao-com-a-api/consultando-saldo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.