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 GET /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:

{
  "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

cURL

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"

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));

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()}")

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 [email protected].

Exemplo de Resposta de Erro:

{
  "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.