Créditos y facturación

Constaia funciona con créditos de pago por uso. No hay suscripción: compras packs cuando los necesitas y, mientras tanto, tienes 150 créditos gratis cada mes. Precios y comparativa en /es/precios.

Cuánto cuesta cada operaciónCopy Anchor Link

La regla es créditos = ceil(páginas / 2), con un mínimo de 1. Un DNI por las dos caras en un solo fichero o en un PDF de 2 páginas cuesta 1 crédito.

En un lote, cada documento se cuenta por separado con la misma regla. Cada análisis indica lo que ha costado en usage:

"usage": { "credits": 1, "pages": 2 }

Qué no se cobraCopy Anchor Link

• Modo test. Las claves ck_test_ no gastan créditos (usage.credits: 0).
• Fallos por nuestra parte. Un análisis que acaba en status: "failed" (por ejemplo processing_failed) no se cobra.
• Rechazos por calidad antes del OCR. Si la imagen se rechaza antes de leerla, no se cobra.
• Reintentos con la misma Idempotency-Key en 24 h: devuelven la respuesta guardada sin cobrar dos veces.
• Exportaciones. Ya están incluidas.

Un análisis que termina en invalid o review sí se cobra: Constaia ha hecho el trabajo y te ha dado una respuesta.

Reserva y capturaCopy Anchor Link

Al empezar un análisis, Constaia reserva los créditos que costará. Al terminar:

• si se completa, la reserva se captura;
• si falla por nuestra parte o se rechaza por calidad antes del OCR, la reserva se libera y vuelve a tu saldo.

Mientras hay análisis en curso verás créditos en credits_reserved. Si no tienes saldo suficiente para reservar, la petición falla con un 402 insufficient_credits y no se analiza nada.

En modo live, un lote comprueba al crearse que tienes al menos 1 crédito por documento; si no, lo rechaza entero con 402. Después cada documento cuesta lo que le corresponda por páginas.

Plan gratisCopy Anchor Link

• 150 créditos al mes, que se renuevan el día 1 de cada mes (UTC). Los que no uses no se acumulan.
• Para gastarlos en modo live necesitas el email verificado.
• free_tier_resets_at en el saldo te dice cuándo se renuevan.

PacksCopy Anchor Link

Los packs son pagos únicos, sin suscripción. Precios sin IVA:

• Los packs caducan a los 12 meses de la compra.
• Orden de consumo: primero el plan gratis del mes y después los packs, del más antiguo al más reciente (FIFO).
• Enterprise: contrato, DPA, SLA y límites propios. Detalles en /es/precios.

Compra packs en Facturación en app.constaia.com. El pago va por Stripe Checkout y los créditos se suman a tu saldo en cuanto se confirma.

IVA y facturasCopy Anchor Link

• Los precios no incluyen IVA. Stripe Tax lo calcula al pagar según tus datos fiscales.
• Cada compra genera una factura que encontrarás en Facturación en el panel.
• Rellena los datos fiscales de tu empresa antes de la primera compra para que aparezcan en la factura.

Consultar el saldoCopy Anchor Link

GET /v1/balance devuelve:

{
  "object": "balance",
  "credits_available": 4210,
  "credits_reserved": 3,
  "free_tier_remaining": 12,
  "credits_spendable": 4222,
  "free_tier_resets_at": "2026-10-01T00:00:00.000Z"
}

Lo que puedes gastar ahora mismo es credits_spendable (credits_available + free_tier_remaining).

curl https://api.constaia.com/v1/balance \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Consultar el consumoCopy Anchor Link

GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD agrega el consumo por día y tipo de documento (por defecto, los últimos 30 días del modo de la clave):

curl "https://api.constaia.com/v1/usage?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

{
  "object": "usage",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "livemode": true,
  "data": [
    { "date": "2026-09-29", "type": "es_dni", "kind": "analysis", "livemode": true, "count": 42, "pages": 84, "credits": 42 }
  ],
  "totals": { "count": 42, "pages": 84, "credits": 42 }
}

Para repartir costes entre clientes o departamentos, envía metadata en cada análisis (por ejemplo { "club_id": "42" }) y filtra con GET /v1/analyses?metadata[club_id]=42. Más en Saldo y consumo.

Alerta de saldo bajoCopy Anchor Link

En los ajustes del panel defines un umbral de aviso (por defecto, 50 créditos). Cuando, tras un análisis cobrado en modo live, tu saldo gastable baja del umbral, Constaia:

• envía el webhook credits.low a los endpoints suscritos, y
• manda un email a los propietarios y administradores de la cuenta.

{
  "type": "credits.low",
  "created_at": "2026-09-29T10:00:00Z",
  "data": { "object": "balance", "credits_available": 0, "free_tier_remaining": 48, "credits_spendable": 48, "threshold": 50 }
}

Los campos significan lo mismo que en GET /v1/balance: credits_available son solo créditos de packs y credits_spendable es lo que puedes gastar (plan gratis más packs); el aviso salta cuando credits_spendable baja del umbral. Se envía una sola vez hasta que recargas con un pack o se renueva el plan gratis. Suscríbete desde Webhooks.

Gestionar el error 402Copy Anchor Link

Sin saldo suficiente, la API responde:

{
  "error": {
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "message": "…",
    "request_id": "req_…"
  }
}

No lo reintentes en bucle: no se resolverá solo. Deja el trabajo en cola, avisa a tu equipo y reanuda cuando haya saldo.

import { Constaia, InsufficientCreditsError } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia();

try {
  const analysis = await constaia.analyze(await fromPath("./dni.jpg"), { expect: "es_dni" });
  console.log(analysis.verdict?.status);
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // Guarda el documento para más tarde y avisa a quien compra los créditos.
    console.error(`Sin créditos (request ${err.requestId})`);
  } else {
    throw err;
  }
}

Tope de gasto mensualCopy Anchor Link

Puedes fijar un tope de créditos al mes para la cuenta: si un análisis en modo live lo superaría, se rechaza con 402 monthly_cap_reached sin cobrarse, y los owners y admins reciben un email al 80 % y al 100 %. Detalles en Límites de uso.

Siguientes pasosCopy Anchor Link