Modo test

Las claves ck_test_... llaman a la misma API, con las mismas rutas, validaciones de opciones y formato de respuesta, pero en vez de analizar el documento con IA devuelven un resultado determinista elegido por el nombre del fichero. Sirven para desarrollar, para CI y para enseñar el producto sin gastar créditos.

Test frente a liveCopy Anchor Link

Los checks que pides (holder, min_age_years, max_age_days, expected_amount…) se evalúan sobre los datos simulados igual que en live, así que puedes probar también los casos de error.

Cómo se elige el resultadoCopy Anchor Link

1. Se toma el nombre del fichero sin extensión y en minúsculas.
2. Si coincide exactamente con un escenario (dni_valid, dni_expired, nie, passport, medical_certificate, sexual_offences_certificate, payment_receipt, invoice, blurry), se usa ese.
3. Si no, se buscan palabras clave en este orden: blur/borros, expired/caducad, nie/tie, passport/pasaporte, medical/medico/médico, sexual/delitos/penales, receipt/justificante/transfer, invoice/factura, dni. La primera que aparezca gana: dni_borroso.jpg da el escenario blurry, y dni_caducado.png, dni_expired.
4. Si no hay ninguna, el documento es generic.

El contenido tiene que ser un fichero real JPEG, PNG, WEBP, HEIC o PDF: el tipo se detecta por los primeros bytes, no por la extensión. Cualquier foto o PDF sirve. No necesitas un fichero por escenario: el nombre que cuenta es el que envías en la petición (el filename del multipart), así que puedes reutilizar el mismo fichero con nombres distintos.

EscenariosCopy Anchor Link

No hay escenarios para los tipos de EE. UU. ni para el resto del catálogo: un permiso de conducir o un W-9 en modo test da generic y, con expect, review. Para ver esos tipos, usa una clave live (los 150 créditos gratis del mes sirven).

Los mensajes con fechas relativas, como "Emitido hace 28 días (máximo 365).", dependen del día en que ejecutes la prueba.

Ejemplos de respuestaCopy Anchor Link

Forzar casos de errorCopy Anchor Link

Además de dni_expired y blurry, puedes provocar otros resultados combinando un fichero con opciones:

Mensajes en otro idiomaCopy Anchor Link

language cambia el idioma de reasons[].message, de los mensajes de checks y de document.label. Por ejemplo, dni_valid.jpg con {"expect":"es_dni","checks":{"holder":{"full_name":"Juan Pérez"},"min_age_years":18},"language":"en"}:

{
  "expected": ["es_dni"],
  "match": true,
  "status": "invalid",
  "reasons": [
    { "code": "type_match", "severity": "info", "message": "The document is Spanish ID card (DNI)." },
    { "code": "not_expired", "severity": "info", "message": "Valid until 12/03/2031." },
    { "code": "age", "severity": "info", "message": "The holder is 36 years old." },
    { "code": "holder", "severity": "error", "message": "Holder mismatch: full_name is “MARÍA GARCÍA LÓPEZ”, expected “Juan Pérez”." }
  ]
}

Los códigos no cambian con el idioma: programa siempre contra code y severity.

Tests automatizadosCopy Anchor Link

Recomendaciones para que tus tests no se rompan:

• Usa una clave ck_test_ dedicada a CI, en una variable de entorno propia (por ejemplo CONSTAIA_TEST_API_KEY), y comprueba que empieza por ck_test_ antes de lanzar nada.
• Afirma solo sobre verdict.status, los code y severity de verdict.reasons y warnings. No compares mensajes (dependen del idioma y, en algunos casos, de la fecha), ni id, fechas o size_bytes.
• Guarda en el repositorio un único JPEG y un único PDF pequeños y envíalos con distintos nombres.

import { beforeAll, describe, expect, it } from "vitest";
import { Constaia, type Analysis } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const apiKey = process.env.CONSTAIA_TEST_API_KEY ?? "";
const constaia = new Constaia({ apiKey });

// Mismo fichero real, distinto nombre: el nombre elige el escenario.
const jpeg = (name: string) => fromPath("test/fixtures/sample.jpg", name);

const codes = (a: Analysis, severity?: string): string[] =>
  (a.verdict?.reasons ?? []).filter((r) => !severity || r.severity === severity).map((r) => r.code);

describe("validación de DNI", () => {
  beforeAll(() => {
    if (!apiKey.startsWith("ck_test_")) throw new Error("CONSTAIA_TEST_API_KEY debe ser una clave ck_test_");
  });

  it("acepta un DNI vigente", async () => {
    const analysis = await constaia.analyze(await jpeg("dni_valid.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("valid");
    expect(codes(analysis)).toContain("type_match");
    expect(analysis.warnings).toEqual([]);
  });

  it("rechaza un DNI caducado", async () => {
    const analysis = await constaia.analyze(await jpeg("dni_expired.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("invalid");
    expect(codes(analysis, "error")).toContain("not_expired");
  });

  it("manda a revisión una foto borrosa", async () => {
    const analysis = await constaia.analyze(await jpeg("blurry.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("review");
    expect(analysis.warnings).toEqual(expect.arrayContaining(["blurry", "low_quality"]));
    expect(codes(analysis, "warning")).toContain("low_quality");
  });

  it("rechaza un pasaporte cuando se espera un DNI", async () => {
    const analysis = await constaia.analyze(await jpeg("passport.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("invalid");
    expect(codes(analysis, "error")).toContain("type_mismatch");
  });
});

Si lanzas muchos tests en paralelo, recuerda que el modo test tiene el mismo límite de peticiones por segundo que tu nivel (2 req/s en el plan gratuito): los SDKs reintentan los 429 respetando Retry-After, pero conviene limitar la concurrencia. Ver Límites de uso.

Webhooks en modo testCopy Anchor Link

Cada endpoint de webhook tiene el modo de la clave con que se creó (mode: "test" o "live") y solo recibe eventos de ese modo. Para probar webhooks en desarrollo:

1. Crea el endpoint con tu clave ck_test_ (POST /v1/webhook-endpoints) apuntando a una URL HTTPS pública (por ejemplo, un túnel hacia tu máquina).
2. Lanza análisis con async: true o lotes con la clave test: recibirás analysis.completed, analysis.review_required (con blurry.jpg), batch.completed…
3. Desde el panel también puedes enviar un evento de prueba (type: "test") y ver las últimas 100 entregas.

credits.low solo existe en modo live. Para tests unitarios del receptor sin red, genera cabeceras firmadas con signWebhook (SDK de JavaScript), Webhook::headers (SDK de PHP) o constaia.webhooks.sign (SDK de Python). Ver Webhooks.

Cuando pases a liveCopy Anchor Link

Las claves live nunca reciben resultados simulados. Si el entorno no tiene proveedores de IA reales disponibles, las llamadas con ck_live_ fallan con 503 live_mode_unavailable (en el SDK de JavaScript, APIError). Sigue usando la clave test mientras tanto. Los pasos para pasar a producción están en el inicio rápido.

Siguientes pasosCopy Anchor Link