Constaia
SDKs

SDK de JavaScript y TypeScript

Referencia de @constaia/sdk para Node.js, Bun, Deno y runtimes edge. Instalación, opciones, métodos, errores, reintentos y verificación de webhooks.

@constaia/sdk es el SDK oficial para JavaScript y TypeScript. No tiene dependencias, usa fetch nativo y funciona en Node.js ≥ 18, Bun, Deno y runtimes edge (Vercel Edge, Netlify Edge). Versión actual: 0.2.0.

Solo en el servidor

La clave (ck_live_… o ck_test_…) es secreta. Si el SDK detecta un navegador con una clave de Constaia, el constructor lanza un error con el código secret_key_in_browser. En el navegador usa el widget, que envía el fichero a tu backend.

Instalación

npm install @constaia/sdk

El paquete se publica en ESM y CommonJS, con tipos incluidos.

Configuración

constaia.ts
import { Constaia } from "@constaia/sdk";

export const constaia = new Constaia({
  apiKey: process.env.CONSTAIA_API_KEY, // por defecto: process.env.CONSTAIA_API_KEY
  baseUrl: "https://api.constaia.com", // por defecto; o CONSTAIA_BASE_URL
  timeout: 60_000, // ms por intento
  maxRetries: 2, // en 429, 408, 409 idempotency_in_progress, 5xx y errores de red
  maxConcurrency: 4, // peticiones en vuelo a la vez; el resto espera en cola
});
OpciónPor defectoDescripción
apiKeyprocess.env.CONSTAIA_API_KEYClave secreta. Sin clave, el constructor lanza un error.
baseUrlhttps://api.constaia.com (o CONSTAIA_BASE_URL)Útil para apuntar a un entorno local.
timeout60000Tiempo máximo por intento, en milisegundos.
maxRetries2Reintentos automáticos en 429, 408, 409 idempotency_in_progress, 5xx (salvo 501) y fallos de red. 0 los desactiva.
maxConcurrency4Peticiones en vuelo a la vez por cliente; el resto espera en una cola FIFO.
fetchglobalThis.fetchImplementación propia de fetch (tests, proxies).
defaultHeaders{}Cabeceras añadidas a todas las peticiones.
dangerouslyAllowBrowserfalsePermite usar la clave en un navegador. Solo para pruebas locales.

constaia.livemode indica si la clave es ck_live_ (true) o ck_test_ (false).

Qué ficheros acepta

analyze() y classify() aceptan:

EntradaEjemplo
File / Blobawait constaia.analyze(form.get("file") as File)
Buffer / Uint8Array / ArrayBufferawait constaia.analyze(buffer, { filename: "dni.jpg" })
ReadableStreamawait constaia.analyze({ file: stream, filename: "dni.jpg" })
Ruta local (Node, Bun, Deno)await constaia.analyze(await fromPath("./dni.jpg"))
URL remotaawait constaia.analyze({ fileUrl: "https://example.com/dni.jpg" })
Base64await constaia.analyze({ base64, filename: "dni.jpg" })

fromPath se importa de @constaia/sdk/node y solo existe donde hay sistema de ficheros. Un string suelto lanza un error: usa { fileUrl } para URLs y fromPath() para rutas.

Ficheros admitidos: JPEG, PNG, WEBP, HEIC y PDF, hasta 20 MB y 30 páginas en análisis síncrono (200 con async: true). En modo test, el nombre del fichero elige la respuesta: pasa filename cuando la entrada no tenga nombre. Ver Modo test.

Opciones

En el SDK las opciones van en camelCase y se convierten al snake_case de la API. Las respuestas llegan exactamente como las envía la API (snake_case), igual que en la referencia y en los webhooks.

SDKAPIDescripción
expectexpectTipo o lista de tipos esperados. Sin él el veredicto se calcula contra el tipo detectado (verdict.basis: "detected"), o es null si es generic.
extractextracttrue (plantilla del tipo) o tu propio JSON Schema.
checks.notExpiredchecks.not_expiredCaducidad. Activo por defecto en tipos con caducidad.
checks.referenceDatechecks.reference_dateFecha de referencia YYYY-MM-DD.
checks.maxAgeDayschecks.max_age_daysAntigüedad máxima de la fecha de emisión.
checks.minAgeYears / maxAgeYearsmin_age_years / max_age_yearsEdad del titular.
checks.holder.fullName…checks.holder.full_name…Titular esperado (fullName, firstName, lastName, documentNumber, birthDate).
checks.requireFieldschecks.require_fieldsCampos obligatorios.
checks.requireSignature / requireStamprequire_signature / require_stampFirma y sello.
checks.expectedAmount / expectedIban / expectedReferenceexpected_amount / expected_iban / expected_referenceJustificantes y facturas.
storagestoragenone, temporary o persistent.
ttlHoursttl_hoursHoras de retención con temporary.
keepResultskeep_resultsfalse para no guardar los resultados.
asyncasynctrue para responder 202 y avisar por webhook.
exportexport["xlsx", "csv", …].
verdictWithoutExpectverdict_without_expectv1.2. false para que, sin expect, verdict sea null en vez de calcularse contra el tipo detectado.
metadatametadataSe envía tal cual (las claves no se convierten).
languagelanguageIdioma de los mensajes: es, en, pt, fr.
filename(nombre del fichero)Nombre cuando la entrada no lo trae.

Todas las opciones de la API están explicadas en POST /v1/analyze y Comprobaciones.

Analizar un documento

verify-dni.ts
import { Constaia } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia();

const analysis = await constaia.analyze(await fromPath("./dni_valid.jpg"), {
  expect: ["es_dni", "es_nie", "passport"],
  checks: {
    notExpired: true,
    minAgeYears: 18,
    holder: { fullName: "María García López", documentNumber: "12345678Z" },
  },
  storage: "none",
  metadata: { registration_id: "123" },
  language: "es",
});

switch (analysis.verdict?.status) {
  case "valid":
    console.log("OK", analysis.fields.document_number?.value);
    break;
  case "invalid":
    console.log(analysis.verdict.reasons.filter((r) => r.severity === "error").map((r) => r.message));
    break;
  case "review":
    console.log("Revisión manual", analysis.warnings);
    break;
}

Si el análisis tarda más de 30 segundos, la API responde 202 con status: "queued" o "processing" y el resultado llega por webhook. Comprueba analysis.status === "completed" antes de leer el veredicto.

Clasificar

classify() solo detecta el tipo (0,2 créditos). Acepta expect, language, metadata y filename.

const c = await constaia.classify(await fromPath("./factura.pdf"), { expect: "invoice" });
console.log(c.document?.type, c.candidates, c.verdict?.status);

Análisis guardados

const one = await constaia.analyses.get("an_01J…");

// Una página (await) …
const page = await constaia.analyses.list({ limit: 50, status: "completed", metadata: { event: "42" } });
console.log(page.data.length, page.has_more);

// … o todas las páginas (for await)
for await (const a of constaia.analyses.list({ type: "es_dni" })) {
  console.log(a.id, a.verdict?.status);
}

// Las 200 más recientes
const recent = await constaia.analyses.list().toArray(200);

await constaia.analyses.delete("an_01J…");

list() devuelve un PagedList: con await obtienes la primera página { object, data, has_more, url }; con for await recorres todos los elementos (el SDK pasa starting_after por ti). Ver Paginación.

Revisión humana

// Pendientes de revisión, del más antiguo al más reciente
for await (const a of constaia.reviews.list({ status: "pending", template: "tpl_01J…", metadata: { event: "42" } })) {
  const res = await constaia.analyses.file(a.id); // Response con el original (404 file_not_stored si ya no está)
  const bytes = await res.arrayBuffer();
  // … enséñaselo a tu revisor y registra su decisión:
  await constaia.analyses.review(a.id, { decision: "approve", reason: "Datos correctos" }, { idempotencyKey: `review-${a.id}` });
}

Ver Revisión humana desde tu backend.

Descargar una exportación

import { writeFile } from "node:fs/promises";

const res = await constaia.analyses.export("an_01J…", "xlsx"); // Response
await writeFile("analisis.xlsx", Buffer.from(await res.arrayBuffer()));

Lotes

const batch = await constaia.batches.create({
  items: [
    { fileUrl: "https://example.com/justificante-1.pdf" },
    { fileUrl: "https://example.com/justificante-2.pdf", options: { checks: { expectedAmount: 45 } } },
  ],
  options: { expect: "payment_receipt", export: ["xlsx"] },
});

// O subiendo ficheros (multipart files[])
const batch2 = await constaia.batches.create({
  files: [await fromPath("./a.pdf"), await fromPath("./b.pdf")],
  options: { expect: "invoice" },
});

const current = await constaia.batches.get(batch.id);

Los lotes siempre son asíncronos: espera el webhook batch.completed. Cada elemento de items es { fileUrl, options? } o { base64, filename, options? }. Ver Lotes.

Catálogo, saldo y uso

const types = await constaia.documentTypes.list({ language: "es" }); // array
const dni = await constaia.documentTypes.get("es_dni", { language: "es" });

const balance = await constaia.balance();
console.log(balance.credits_available + balance.free_tier_remaining);

const usage = await constaia.usage({ from: "2026-09-01", to: "2026-09-30" });

Endpoints de webhook

const endpoint = await constaia.webhookEndpoints.create({
  url: "https://example.com/webhooks/constaia",
  events: ["analysis.completed", "analysis.review_required", "batch.completed"],
});
console.log(endpoint.secret); // whsec_… — solo aparece ahora: guárdalo

const endpoints = await constaia.webhookEndpoints.list(); // array
const same = await constaia.webhookEndpoints.get(endpoint.id);
await constaia.webhookEndpoints.delete(endpoint.id);

Verificar webhooks

constaia.webhooks.verify() comprueba la firma Standard Webhooks (HMAC-SHA256, tolerancia de 5 minutos) y devuelve el evento ya parseado. Es asíncrona (usa WebCrypto). Pásale el cuerpo sin procesar.

app/api/webhooks/constaia/route.ts
import { Constaia, WebhookVerificationError } from "@constaia/sdk";

const constaia = new Constaia();

export async function POST(request: Request) {
  const raw = await request.text();
  try {
    const event = await constaia.webhooks.verify(raw, request.headers, process.env.CONSTAIA_WEBHOOK_SECRET!);
    if (event.type === "analysis.completed") {
      console.log(event.data.id, event.data.verdict?.status);
    }
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response("invalid signature", { status: 400 });
    throw err;
  }
}

También puedes importar las funciones sueltas:

import { signWebhook, verifyWebhook } from "@constaia/sdk";

const event = await verifyWebhook(raw, headers, secret, { tolerance: 300 });

// En tus tests: genera cabeceras firmadas como las de Constaia
const body = JSON.stringify({ type: "analysis.completed", created_at: new Date().toISOString(), data: {} });
const signed = await signWebhook(body, "whsec_…");

headers puede ser un objeto Headers, un objeto plano (como req.headers de Express) o cualquier cosa con get(). Más en Webhooks.

Errores

Todas las clases heredan de ConstaiaError, con status, type, code, param, requestId, headers y raw.

ClaseCuándo
InvalidRequestError400, 409, 413, 415, 422: cualquier error de tipo invalid_request (unsupported_file_type, file_too_large, invalid_parameter…).
AuthenticationError401: falta la clave o no es válida.
InsufficientCreditsError402: sin créditos.
PermissionError403.
NotFoundError404: el análisis no existe, se borró o se creó con keep_results: false.
RateLimitError429, tras agotar los reintentos. retryAfter en segundos.
APIError5xx, por ejemplo 503 live_mode_unavailable.
APIConnectionError / APITimeoutErrorNo se pudo conectar o se agotó el tiempo.
WebhookVerificationErrorFirma de webhook no válida.
import {
  ConstaiaError,
  InsufficientCreditsError,
  InvalidRequestError,
  RateLimitError,
} from "@constaia/sdk";

try {
  await constaia.analyze(file, { expect: "es_dni" });
} catch (err) {
  if (err instanceof InvalidRequestError) console.log(err.code, err.param);
  else if (err instanceof InsufficientCreditsError) alertBilling();
  else if (err instanceof RateLimitError) console.log(`reintenta en ${err.retryAfter} s`);
  else if (err instanceof ConstaiaError) console.log(err.status, err.type, err.requestId);
  else throw err;
}

Todos los códigos, en Errores.

Reintentos, tiempos e idempotencia

  • Reintenta automáticamente en 429, 408, 409 idempotency_in_progress, 5xx (nunca 501) y errores de red, hasta maxRetries veces. Respeta Retry-After (hasta 60 s); si no hay, espera con backoff exponencial (0,5 s a 8 s, con jitter).
  • Cada POST lleva una Idempotency-Key aleatoria, la misma en todos sus reintentos, así que un reintento no cobra dos veces.
  • Todos los métodos aceptan un último argumento RequestOptions:
const controller = new AbortController();

await constaia.analyze(file, { expect: "es_dni" }, {
  idempotencyKey: "registration-123-dni", // la tuya, para deduplicar entre procesos
  timeout: 90_000,
  maxRetries: 4,
  signal: controller.signal,
  headers: { "X-Trace": "abc" },
});

Con maxConcurrency (por defecto 4) el cliente nunca tiene más peticiones en vuelo que ese número; las demás esperan en cola. Tras cada respuesta, constaia.lastRateLimit trae las cabeceras de límite (limit, remaining, reset, policy, retryAfter) y constaia.lastRequestId el X-Request-Id. Con varios procesos, el límite por clave es compartido. Ver Límites de uso.

Tipos de TypeScript

El paquete exporta los tipos de las respuestas (Analysis, Classification, Batch, Balance, Usage, WebhookEvent…) y de las opciones (AnalyzeOptions, Checks). DocumentType, ReasonCode y WarningCode autocompletan los valores conocidos y aceptan cualquier string, para que tu código no se rompa cuando se añaden tipos o códigos nuevos. Trata reasons[].code como un string y compáralo con los códigos estables de Veredictos.

Plantillas, expedientes, sesiones y privacidad

El SDK también cubre constaia.templates, constaia.dossiers, constaia.sessions (con sessions.submit() para el navegador con una clave pk_), constaia.analytics() y constaia.analyses.deleteByMetadata() / exportByMetadata(). Los campos y ejemplos están en Plantillas, Expedientes, Sesiones y claves publicables, Analítica y Privacidad avanzada.

Siguientes pasos

En esta página