Cuenta y saldo

GET /api/v1/account

Devuelve la vista más completa de tu cuenta API.

Incluye:

• Identidad de la cuenta.
• Saldo disponible.
• Saldo retenido.
• IPs registradas automáticamente.
• Uso reciente.
• Límites activos.

Cuándo usarlo

Usa este endpoint cuando necesitas una vista completa de la cuenta API, por ejemplo:

• Al abrir tu panel interno de integrador.
• Para mostrar saldo, uso y actividad reciente.
• Para revisar qué IPs ya quedaron registradas.
• Para confirmar límites antes de un despliegue o cambio de infraestructura.

Ejemplo de respuesta

{
  "success": true,
  "requestId": "req_01K5CA4P8R7M6Y5T4W3Q2N1B0C",
  "timestamp": "2026-03-19T16:15:42.123Z",
  "data": {
    "user": {
      "userId": "user_01K5CA8D3F6G7H8J9K0L1M2N3P",
      "email": "[email protected]",
      "name": "Demo Merchant"
    },
    "wallet": {
      "currency": "MXN",
      "balance": 2500.00,
      "heldBalance": 125.50,
      "availableBalance": 2374.50
    },
    "api": {
      "allowedIps": [
        "203.0.113.24",
        "198.51.100.42"
      ],
      "usage": {
        "totalRequests": 128,
        "successfulRequests": 121,
        "failedRequests": 4,
        "blockedRequests": 3,
        "serviceReads": 90,
        "orderReads": 24,
        "orderCreates": 10,
        "accountReads": 4,
        "lastRequestAt": "2026-03-19T16:12:00.000Z"
      },
      "limits": {
        "requestsPerMinute": 60,
        "ordersPerMinute": 10,
        "monthlyRequests": null
      }
    }
  }
}

Qué significa cada bloque

user

Identifica la cuenta API autenticada.

wallet.balance

Saldo total actual de la cuenta.

wallet.heldBalance

Saldo retenido temporalmente por pedidos pendientes o en proceso.

wallet.availableBalance

Saldo realmente disponible para crear nuevos pedidos.

En la práctica, esta es la cifra más importante para tu operación diaria.

api.allowedIps

IPs que ya quedaron registradas como autorizadas para esa API key.

api.usage

Resumen de uso reciente por tipo de request.

api.limits

Límites operativos configurados para tu cuenta API.

GET /api/v1/balance

Devuelve solo el bloque de saldo de la cuenta API autenticada.

Importante:

• Este saldo corresponde a tu cuenta API.
• No corresponde a usuarios finales de tu sistema.
• No corresponde a tus clientes internos o subcuentas.

Cuándo usarlo

Este endpoint es útil sobre todo para:

• Diagnóstico manual.
• Paneles administrativos de revendedor.
• Verificaciones puntuales de cartera.

No está pensado como un endpoint que debas consultar antes de cada pedido si tu integración ya lleva control normal de operaciones.

Ejemplo de respuesta

{
  "success": true,
  "requestId": "req_01K5CAB0M7T6Y5U4I3O2P1A9S8",
  "timestamp": "2026-03-19T16:20:00.000Z",
  "data": {
    "currency": "MXN",
    "balance": 2500.00,
    "heldBalance": 125.50,
    "availableBalance": 2374.50
  }
}

Recomendación práctica

Si vas a mostrar saldo en tu panel:

• Usa GET /api/v1/account al cargar la vista principal.
• Usa GET /api/v1/balance solo para refrescos ligeros o diagnósticos.