Saldo y consumo
Referencia de GET /v1/balance y GET /v1/usage: créditos de packs, plan gratuito, reservas y consumo diario por tipo de documento, con ejemplos.
Dos endpoints de solo lectura para saber cuántos créditos te quedan y en qué los has gastado. Ninguno consume créditos.
| Método y ruta | Qué hace |
|---|---|
GET /v1/balance | Saldo actual de la cuenta. |
GET /v1/usage | Consumo agregado por día, tipo de documento y endpoint. |
Precios y reglas de cobro en Créditos y facturación y en precios.
GET /v1/balance
curl https://api.constaia.com/v1/balance \
-H "Authorization: Bearer $CONSTAIA_API_KEY"{
"object": "balance",
"credits_available": 1000,
"credits_reserved": 2,
"free_tier_remaining": 118.4,
"credits_spendable": 1118.4,
"free_tier_resets_at": "2026-10-01T00:00:00.000Z"
}| Campo | Descripción |
|---|---|
credits_available | Créditos de packs comprados que puedes gastar. No incluye el plan gratuito. |
credits_reserved | Créditos reservados por análisis en curso. Se descuentan al terminar según las páginas reales, y se liberan si el análisis falla. |
free_tier_remaining | Lo que queda del plan gratuito del mes (150 créditos al mes). |
credits_spendable | Lo que puedes gastar ahora mismo: credits_available + free_tier_remaining. |
free_tier_resets_at | Cuándo se renueva el plan gratuito: el día 1 de cada mes a las 00:00 UTC. Lo que no gastes no se acumula. |
Lo que puedes gastar ahora mismo es credits_spendable (credits_available + free_tier_remaining). Primero se consume el plan gratuito y después los packs, del más antiguo al más reciente. Los valores pueden tener decimales porque classify cuesta 0,2 créditos.
El saldo es de la cuenta: devuelve lo mismo con una clave test que con una live. Las claves test no gastan créditos.
Si el saldo baja del umbral que configures en el panel, recibes el webhook credits.low (solo modo live, una vez hasta que recargues).
GET /v1/usage
| Parámetro | Formato | Por defecto |
|---|---|---|
from | YYYY-MM-DD | Hace 29 días (30 días contando hoy). |
to | YYYY-MM-DD | Hoy. |
Un formato de fecha incorrecto devuelve 422 invalid_parameter. El consumo es solo del modo de la clave: con una clave test ves el uso de test; con una live, el real.
curl -G https://api.constaia.com/v1/usage \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-d from=2026-09-01 -d to=2026-09-30{
"object": "usage",
"from": "2026-09-01",
"to": "2026-09-30",
"livemode": true,
"data": [
{ "date": "2026-09-28", "type": "es_dni", "kind": "analysis", "livemode": true, "count": 12, "pages": 14, "credits": 12 },
{ "date": "2026-09-28", "type": "invoice", "kind": "classification", "livemode": true, "count": 5, "pages": 7, "credits": 1 },
{ "date": "2026-09-29", "type": "payment_receipt", "kind": "analysis", "livemode": true, "count": 3, "pages": 3, "credits": 3 }
],
"totals": { "count": 20, "pages": 24, "credits": 16 }
}| Campo | Descripción |
|---|---|
from, to | Rango aplicado. |
livemode | Modo de la clave usada. |
data[] | Una fila por día, tipo de documento y kind, ordenadas por fecha. |
data[].date | Día (YYYY-MM-DD). |
data[].type | Tipo de documento detectado. |
data[].kind | analysis (analyze y lotes) o classification (classify). |
data[].count | Número de documentos. |
data[].pages | Páginas procesadas. |
data[].credits | Créditos cobrados. 0 en modo test. |
totals | Suma de count, pages y credits del rango. |
Los análisis fallidos no se cobran. Detalle en Créditos y facturación.
Ejemplo: comprobar saldo antes de un lote
import { Constaia } from "@constaia/sdk";
const constaia = new Constaia();
const balance = await constaia.balance();
const spendable = balance.credits_available + balance.free_tier_remaining;
const needed = 80; // p. ej. 80 documentos de hasta 2 páginas
if (constaia.livemode && spendable < needed) {
throw new Error(`Saldo insuficiente: ${spendable} créditos, necesitas ${needed}`);
}
const usage = await constaia.usage({ from: "2026-09-01", to: "2026-09-30" });
console.log(`Septiembre: ${usage.totals.count} documentos, ${usage.totals.credits} créditos`);Siguientes pasos
GET /v1/document-types
Referencia de GET /v1/document-types: catálogo público de tipos de documento con campos, JSON Schema, validadores y checks aplicables, sin clave de API.
Endpoints de webhook
Referencia de /v1/webhook-endpoints: crea, lista, consulta y borra las URLs que reciben los eventos de Constaia, con su secreto whsec_ y su modo.