Consultar saldo
GEThttps://api.cfdi.express/v1/balanceAPI key
Devuelve el saldo prepagado de la cuenta, el precio por timbre vigente y cuántos timbres te quedan.
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.
Autenticación
Authorization: Bearer sk_test_... | sk_live_...Ejemplos
cURL
curl https://api.cfdi.express/v1/balance \
-H "Authorization: Bearer sk_test_..."Node.js
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
{
"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.