Consulta de Saldo

Descripción General

El endpoint de consulta de saldo le permite obtener información detallada sobre el saldo de la cuenta autenticada en tiempo real. La respuesta incluye tres tipos de saldo:

Saldo Bruto (Gross Balance): Valor total de la cuenta (disponible + bloqueado)
Saldo Bloqueado (Blocked Balance): Valores reservados para operaciones pendientes
Saldo Neto (Net Balance): Valor disponible para uso inmediato

Este endpoint requiere un token Bearer válido. Consulte la documentación de autenticación para más detalles.

Endpoint

GET /api/balance

Devuelve el saldo actual de la cuenta autenticada.

Encabezados Requeridos

Authorization: Bearer {token}

Solicitud

curl -X GET https://api.fypay.me/api/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Respuesta (200 OK)

{
  "grossBalance": 48734.90,
  "blockedBalance": 0.00,
  "netBalance": 48734.90,
  "consultedAt": "2025-11-19T20:18:29.384Z"
}

Estructura de la Respuesta

grossBalancenumbersempre presente

Saldo bruto total de la cuenta (saldo neto + saldo bloqueado)

Ejemplo: 48734.90

blockedBalancenumbersempre presente

Valor que existe en la cuenta pero no está disponible: pagos PIX en procesamiento, bloqueos cautelares (por ejemplo, de MED) y débitos pendientes de devolución o tarifa (grossBalance - netBalance)

Ejemplo: 0.00

netBalancenumbersempre presente

Saldo neto disponible para uso inmediato (grossBalance - blockedBalance)

Ejemplo: 48734.90

consultedAtstringsempre presente

Fecha y hora de la consulta en formato ISO 8601 (UTC)

Ejemplo: 2025-11-19T20:18:29.384Z

Ejemplos de Implementación

Node.js / TypeScript

import axios from 'axios';

interface BalanceResponse {
  grossBalance: number;
  blockedBalance: number;
  netBalance: number;
  consultedAt: string;
}

async function getBalance(token: string): Promise<BalanceResponse> {
  try {
    const response = await axios.get<BalanceResponse>(
      'https://api.fypay.me/api/balance',
      {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      }
    );

    console.log('=== Saldo de la Cuenta ===');
    console.log(`Saldo Bruto: R$ ${response.data.grossBalance.toFixed(2)}`);
    console.log(`Saldo Bloqueado: R$ ${response.data.blockedBalance.toFixed(2)}`);
    console.log(`Saldo Neto: R$ ${response.data.netBalance.toFixed(2)}`);
    console.log(`Consultado el: ${new Date(response.data.consultedAt).toLocaleString('es')}`);

    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error('Error al consultar el saldo:', error.response?.data);
      throw new Error(error.response?.data?.message || 'Error al consultar el saldo');
    }
    throw error;
  }
}

// Uso
const token = 'su_token_aqui';
getBalance(token);

Python

import requests
from datetime import datetime
from typing import Dict

def get_balance(token: str) -> Dict:
    """
    Consulta el saldo de la cuenta

    Args:
        token: Token Bearer válido

    Returns:
        Diccionario con información de saldo
    """
    url = 'https://api.fypay.me/api/balance'
    headers = {
        'Authorization': f'Bearer {token}'
    }

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()

        data = response.json()

        print('=== Saldo de la Cuenta ===')
        print(f"Saldo Bruto: R$ {data['grossBalance']:.2f}")
        print(f"Saldo Bloqueado: R$ {data['blockedBalance']:.2f}")
        print(f"Saldo Neto: R$ {data['netBalance']:.2f}")

        consulted_at = datetime.fromisoformat(data['consultedAt'].replace('Z', '+00:00'))
        print(f"Consultado el: {consulted_at.strftime('%d/%m/%Y %H:%M:%S')}")

        return data

    except requests.exceptions.RequestException as e:
        print(f'Error al consultar el saldo: {e}')
        if hasattr(e.response, 'json'):
            print(f'Detalles: {e.response.json()}')
        raise

# Uso
token = 'su_token_aqui'
balance = get_balance(token)

PHP

<?php

function getBalance(string $token): array
{
    $url = 'https://api.fypay.me/api/balance';

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("Error al consultar el saldo: HTTP $httpCode");
    }

    $data = json_decode($response, true);

    echo "=== Saldo de la Cuenta ===" . PHP_EOL;
    echo "Saldo Bruto: R$ " . number_format($data['grossBalance'], 2, ',', '.') . PHP_EOL;
    echo "Saldo Bloqueado: R$ " . number_format($data['blockedBalance'], 2, ',', '.') . PHP_EOL;
    echo "Saldo Neto: R$ " . number_format($data['netBalance'], 2, ',', '.') . PHP_EOL;
    echo "Consultado el: " . date('d/m/Y H:i:s', strtotime($data['consultedAt'])) . PHP_EOL;

    return $data;
}

// Uso
$token = 'su_token_aqui';
$balance = getBalance($token);

Casos de Uso

1. Dashboard de Gestión Financiera

Muestre el saldo en tiempo real en un dashboard administrativo:

// Actualizar el saldo cada 30 segundos
setInterval(async () => {
  const balance = await getBalance(token);

  // Actualizar la UI
  document.getElementById('gross-balance').textContent =
    `R$ ${balance.grossBalance.toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`;

  document.getElementById('net-balance').textContent =
    `R$ ${balance.netBalance.toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`;

  // Alerta de saldo bajo
  if (balance.netBalance < 1000) {
    showLowBalanceAlert();
  }
}, 30000);

2. Validación Previa al Pago

Verifique si hay saldo suficiente antes de realizar un pago:

async function processPayment(amount: number, token: string) {
  // Consultar el saldo actual
  const balance = await getBalance(token);

  // Validar el saldo disponible
  if (balance.netBalance < amount) {
    throw new Error(
      `Saldo insuficiente. Disponible: R$ ${balance.netBalance.toFixed(2)} | ` +
      `Necesario: R$ ${amount.toFixed(2)}`
    );
  }

  // Continuar con el pago
  return await createPixPayment(amount, token);
}

3. Reporte de Conciliación

Genere reportes de conciliación con el saldo actual:

import json

def generate_reconciliation_report(token: str):
    """Genera un reporte de conciliación"""
    balance = get_balance(token)

    report = {
        'report_date': datetime.now().isoformat(),
        'balance_snapshot': balance,
        'status': 'OK' if balance['netBalance'] > 0 else 'ALERT',
        'blocked_percentage': (
            balance['blockedBalance'] / balance['grossBalance'] * 100
            if balance['grossBalance'] > 0 else 0
        )
    }

    # Guardar el reporte
    with open(f"reconciliation_{datetime.now().strftime('%Y%m%d')}.json", 'w') as f:
        json.dump(report, f, indent=2)

    return report

Entendiendo el Saldo Bloqueado

El saldo bloqueado representa valores temporalmente no disponibles debido a:

Códigos de Respuesta

Código	Descripción	Significado
`200`	Éxito	Saldo consultado con éxito
`401`	Token Inválido	Token no proporcionado, expirado o inválido

Consulte la Referencia de la API para detalles completos de los campos de respuesta.

Consideraciones

El saldo devuelto refleja el estado en el momento exacto de la consulta. Para operaciones críticas, consulte siempre el saldo inmediatamente antes de la transacción.

Caché: No recomendamos almacenar el saldo en caché por más de 1 minuto
Precisión: Los valores se devuelven con 2 decimales
Moneda: Todos los valores están en Reales (BRL)

Monitoreo y Alertas

Implementando Alertas de Saldo

class BalanceMonitor {
  constructor(token, thresholds) {
    this.token = token;
    this.thresholds = {
      critical: thresholds.critical || 500,
      warning: thresholds.warning || 2000,
      high: thresholds.high || 10000
    };
  }

  async checkAndAlert() {
    const balance = await getBalance(this.token);
    const netBalance = balance.netBalance;

    if (netBalance < this.thresholds.critical) {
      this.sendAlert('CRITICAL', `Saldo crítico: R$ ${netBalance.toFixed(2)}`);
    } else if (netBalance < this.thresholds.warning) {
      this.sendAlert('WARNING', `Saldo bajo: R$ ${netBalance.toFixed(2)}`);
    }

    // Alerta de saldo bloqueado alto
    const blockedPercentage = (balance.blockedBalance / balance.grossBalance) * 100;
    if (blockedPercentage > 50) {
      this.sendAlert('WARNING', `${blockedPercentage.toFixed(1)}% del saldo está bloqueado`);
    }

    return balance;
  }

  sendAlert(level, message) {
    console.log(`[${level}] ${message}`);
    // Integrar con el sistema de alertas (email, SMS, Slack, etc.)
  }
}

// Uso
const monitor = new BalanceMonitor(token, {
  critical: 1000,
  warning: 5000
});

// Ejecutar cada 5 minutos
setInterval(() => monitor.checkAndAlert(), 5 * 60 * 1000);

Consulta de Saldo

Descripción General

Endpoint

GET /api/balance

Encabezados Requeridos

Solicitud

Respuesta (200 OK)

Estructura de la Respuesta

Ejemplos de Implementación

Node.js / TypeScript

Python

PHP

Casos de Uso

1. Dashboard de Gestión Financiera

2. Validación Previa al Pago

3. Reporte de Conciliación

Entendiendo el Saldo Bloqueado

Códigos de Respuesta

Consideraciones

Monitoreo y Alertas

Implementando Alertas de Saldo

Próximos Pasos

Realizar Pago PIX

Generar Cobro PIX

En esta página

Consulta de Saldo

Pagos PIX en Procesamiento

Cobros Esperando Confirmación

Bloqueos cautelares (MED)

Débitos pendientes

Realizar Pago PIX

Generar Cobro PIX

En esta página