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/sdkEl paquete se publica en ESM y CommonJS, con tipos incluidos.
Configuración
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ón | Por defecto | Descripción |
|---|---|---|
apiKey | process.env.CONSTAIA_API_KEY | Clave secreta. Sin clave, el constructor lanza un error. |
baseUrl | https://api.constaia.com (o CONSTAIA_BASE_URL) | Útil para apuntar a un entorno local. |
timeout | 60000 | Tiempo máximo por intento, en milisegundos. |
maxRetries | 2 | Reintentos automáticos en 429, 408, 409 idempotency_in_progress, 5xx (salvo 501) y fallos de red. 0 los desactiva. |
maxConcurrency | 4 | Peticiones en vuelo a la vez por cliente; el resto espera en una cola FIFO. |
fetch | globalThis.fetch | Implementación propia de fetch (tests, proxies). |
defaultHeaders | {} | Cabeceras añadidas a todas las peticiones. |
dangerouslyAllowBrowser | false | Permite 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:
| Entrada | Ejemplo |
|---|---|
File / Blob | await constaia.analyze(form.get("file") as File) |
Buffer / Uint8Array / ArrayBuffer | await constaia.analyze(buffer, { filename: "dni.jpg" }) |
ReadableStream | await constaia.analyze({ file: stream, filename: "dni.jpg" }) |
| Ruta local (Node, Bun, Deno) | await constaia.analyze(await fromPath("./dni.jpg")) |
| URL remota | await constaia.analyze({ fileUrl: "https://example.com/dni.jpg" }) |
| Base64 | await 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.
| SDK | API | Descripción |
|---|---|---|
expect | expect | Tipo o lista de tipos esperados. Sin él el veredicto se calcula contra el tipo detectado (verdict.basis: "detected"), o es null si es generic. |
extract | extract | true (plantilla del tipo) o tu propio JSON Schema. |
checks.notExpired | checks.not_expired | Caducidad. Activo por defecto en tipos con caducidad. |
checks.referenceDate | checks.reference_date | Fecha de referencia YYYY-MM-DD. |
checks.maxAgeDays | checks.max_age_days | Antigüedad máxima de la fecha de emisión. |
checks.minAgeYears / maxAgeYears | min_age_years / max_age_years | Edad del titular. |
checks.holder.fullName… | checks.holder.full_name… | Titular esperado (fullName, firstName, lastName, documentNumber, birthDate). |
checks.requireFields | checks.require_fields | Campos obligatorios. |
checks.requireSignature / requireStamp | require_signature / require_stamp | Firma y sello. |
checks.expectedAmount / expectedIban / expectedReference | expected_amount / expected_iban / expected_reference | Justificantes y facturas. |
storage | storage | none, temporary o persistent. |
ttlHours | ttl_hours | Horas de retención con temporary. |
keepResults | keep_results | false para no guardar los resultados. |
async | async | true para responder 202 y avisar por webhook. |
export | export | ["xlsx", "csv", …]. |
verdictWithoutExpect | verdict_without_expect | v1.2. false para que, sin expect, verdict sea null en vez de calcularse contra el tipo detectado. |
metadata | metadata | Se envía tal cual (las claves no se convierten). |
language | language | Idioma 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
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.
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.
| Clase | Cuándo |
|---|---|
InvalidRequestError | 400, 409, 413, 415, 422: cualquier error de tipo invalid_request (unsupported_file_type, file_too_large, invalid_parameter…). |
AuthenticationError | 401: falta la clave o no es válida. |
InsufficientCreditsError | 402: sin créditos. |
PermissionError | 403. |
NotFoundError | 404: el análisis no existe, se borró o se creó con keep_results: false. |
RateLimitError | 429, tras agotar los reintentos. retryAfter en segundos. |
APIError | 5xx, por ejemplo 503 live_mode_unavailable. |
APIConnectionError / APITimeoutError | No se pudo conectar o se agotó el tiempo. |
WebhookVerificationError | Firma 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, hastamaxRetriesveces. RespetaRetry-After(hasta 60 s); si no hay, espera con backoff exponencial (0,5 s a 8 s, con jitter). - Cada
POSTlleva unaIdempotency-Keyaleatoria, 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
Referencia de la API
Referencia interactiva y especificación OpenAPI 3.1 de la API de Constaia, convenciones de /v1, generación de clientes e importación en Postman.
SDK de PHP
Referencia de constaia/constaia-php para PHP 8.1+: instalación con Composer, entradas, opciones, métodos, paginación, excepciones, reintentos y webhooks.