# Consultar saldo

> `GET https://api.cfdi.express/v1/balance` — Devuelve el saldo prepagado de la cuenta, el precio por timbre vigente y cuántos timbres te quedan.

URL de esta página: https://cfdi.express/docs/api/saldo
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)

El saldo es independiente por modo: tu llave `sk_test_` consulta el saldo de pruebas y tu llave `sk_live_` el de producción. El campo `livemode` te dice cuál estás viendo.

Todos los montos vienen en centavos de peso mexicano (MXN) para evitar errores de punto flotante.

## Ejemplos

### cURL

```bash
curl https://api.cfdi.express/v1/balance \
  -H "Authorization: Bearer sk_test_..."
```

### Node.js

```javascript
const res = await fetch("https://api.cfdi.express/v1/balance", {
  headers: { Authorization: `Bearer ${process.env.CFDI_API_KEY}` },
});

const balance = await res.json();
console.log(balance.timbresRemaining, "timbres disponibles");
```

## Respuesta

### 200 OK

```json
{
  "object": "balance",
  "livemode": false,
  "balanceCentavos": 48200,
  "currency": "MXN",
  "pricePerTimbreCentavos": 100,
  "timbresRemaining": 482
}
```

## Errores

| Status | code | Cuándo aparece |
|---|---|---|
| 401 | `unauthorized` | Falta el header Authorization o la llave es inválida. |
| 429 | `rate_limited` | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |

## Notas

- Un timbre se reserva al iniciar el timbrado y se confirma al recibir el UUID. Si el SAT rechaza o el PAC falla, el reembolso al saldo es automático.
- Las cancelaciones también consumen un timbre.

## Relacionados

- [POST /v1/billing/checkout_sessions](https://cfdi.express/docs/api/recargar-saldo) — Recargar saldo
- [GET /v1/billing/transactions](https://cfdi.express/docs/api/transacciones) — Transacciones de saldo
- [GET /v1/billing/usage](https://cfdi.express/docs/api/uso-mensual) — Uso mensual

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express