Apacuana SDK for Web

1. Introducción

El Apacuana SDK for Web es una librería de cliente diseñada para integrar las funcionalidades de la plataforma Apacuana en cualquier aplicación web.

Este SDK actúa como una capa de abstracción sobre apacuana-sdk-core, facilitando operaciones criptográficas complejas directamente en el navegador del cliente. Utiliza tecnologías web estándar como la Web Crypto API para la generación de claves y la firma de documentos, y IndexedDB para el almacenamiento seguro y persistente de material criptográfico (certificados y claves privadas) en el dispositivo del usuario.

Tabla de Contenidos

• Instalación
• Importación
• Configuración y conceptos clave
• Inicialización del SDK
• Conceptos Clave
  • Tipos de Integración
  • Acceso a funciones públicas/privadas
• Referencia de la API
  • Métodos públicos
    • getCertTypes
    • getCertRequerimentsByType
    • createApacuanaUser
  • Métodos privados
    • getCustomer
    • generateCert
    • getCertStatus
    • addSigner
    • getDocsByCustomer
    • signDocument
    • uploadSignatureVariant
    • getSignatureVariant
    • deleteSignatureVariant
    • startLivenessCheck
    • requestRevocation
    • getRevocationReasons
    • importCertificate
    • exportCertificateInJSON
    • isCertificateInDevice
• Manejo de Errores

Guía de Inicio Rápido

Esta sección te muestra cómo comenzar a usar el SDK Web de Apacuana en tu proyecto, desde la instalación hasta la inicialización y primer uso.

1. Instalación

Instala el SDK usando npm o yarn:

npm install apacuana-sdk-web
# o
yarn add apacuana-sdk-web

2. Importación

Importa la instancia única y preconfigurada del SDK en tu proyecto:

import { apacuanaWeb } from "apacuana-sdk-web";

3. Configuración y conceptos clave

Antes de inicializar el SDK, asegúrate de tener los datos de configuración proporcionados por Apacuana:

• apiUrl: URL base de la API de Apacuana.
• secretKey: Clave secreta de tu integración.
• apiKey: API Key de tu integración.
• verificationId: ID de verificación de tu cliente.
• customerId: (Opcional) ID único del usuario/cliente. Necesario para funciones privadas.
• integrationType: Tipo de integración (ONBOARDING recomendado).

Nota: Si inicializas el SDK sin customerId, solo tendrás acceso a funciones públicas. Para acceder a funciones privadas (como firma, gestión de certificados, etc.), debes incluir customerId en la configuración.

4. Inicialización del SDK

Inicializa el SDK una sola vez al cargar tu aplicación. Si la inicialización es exitosa, podrás usar todos los métodos públicos y privados según tu configuración.

import { apacuanaWeb } from "apacuana-sdk-web";

const config = {
  apiUrl: "https://api.tu-dominio.com",
  secretKey: "TU_SECRET_KEY",
  apiKey: "TU_API_KEY",
  verificationId: "ID_DE_VERIFICACION",
  customerId: "ID_DEL_CLIENTE", // Opcional, pero necesario para funciones privadas
  integrationType: "ONBOARDING",
};

async function initializeApp() {
  try {
    const isInitialized = await apacuanaWeb.init(config);
    if (isInitialized) {
      console.log("El SDK Web de Apacuana se ha inicializado correctamente.");
    }
  } catch (error) {
    if (
      error.name === "ApacuanaWebError" ||
      error.name === "ApacuanaAPIError"
    ) {
      console.error("Error al inicializar el SDK:", error.message);
    } else {
      console.error("Error inesperado:", error);
    }
  }
}

initializeApp();

Conceptos Clave

Tipos de Integración

El SDK soporta dos tipos de integración (integrationType) que determinan cómo se interactúa con la plataforma de Apacuana:

• ONBOARDING: En este modo, Apacuana gestiona la mayor parte del proceso, como el registro de usuarios y la generación de certificados. Es el modo recomendado y soportado para la mayoría de las integraciones.

• ONPREMISE: Este modo de integración no está soportado actualmente y se reserva para uso futuro. La mayoría de las operaciones del SDK lanzarán un error NOT_IMPLEMENTED si se utiliza este tipo.

La elección del integrationType en la init es fundamental, ya que afecta a la disponibilidad y el comportamiento de muchos de los métodos del SDK.

Acceso a funciones públicas/privadas

El SDK puede inicializarse sin el parámetro customerId, lo que permite el acceso únicamente a las funciones públicas. Para acceder a las funciones privadas, es necesario inicializar el SDK incluyendo el customerId en la configuración.

Funciones públicas disponibles sin customerId:

• getCertTypes()
• getCertRequerimentsByType(params)
• createApacuanaUser(userData)

Funciones privadas (requieren customerId):

• getCustomer()
• generateCert(encryptedCSR)
• getCertStatus(isCertificateInDevice)
• addSigner(signerData)
• getDocsByCustomer(params)
• signDocument(signData)
• uploadSignatureVariant(data)
• getSignatureVariant()
• deleteSignatureVariant()
• startLivenessCheck()
• requestRevocation(params)
• getRevocationReasons()
• importCertificate()
• exportCertificateInJSON()
• isCertificateInDevice()

El SDK valida automáticamente si tienes acceso a cada función según la configuración actual, y lanzará un error si intentas acceder a una función privada sin haber inicializado correctamente con el customerId.

Referencia de la API

Todos los métodos deben ser llamados a través de la instancia apacuanaWeb.

Métodos públicos

getCertTypes()

Obtiene los tipos de certificados disponibles.

Comportamiento

• Solo disponible para integrationType: ONBOARDING. Si se usa con ONPREMISE, lanzará un error NOT_IMPLEMENTED.
• Devuelve una instancia de ApacuanaSuccess con la propiedad types, que es un array de tipos de certificado.

Respuesta

{
  success: true,
  data: {
    types: [
      { /* tipo de certificado */ },
      // ...otros tipos de certificado
    ]
  }
}

Ejemplo:

try {
  const response = await apacuanaWeb.getCertTypes();
  console.log("Tipos de certificados:", response.data.types);
} catch (error) {
  console.error("Error al obtener los tipos de certificado:", error.message);
}

getCertRequerimentsByType(params)

Obtiene los requisitos para un tipo de certificado y usuario.

Parámetros

• params: Objeto con la propiedad obligatoria:
  • type (Number): El tipo de certificado.

Comportamiento

• Solo disponible para integrationType: ONBOARDING. Si se usa con ONPREMISE, lanzará un error NOT_IMPLEMENTED.
• Devuelve una instancia de ApacuanaSuccess con los requisitos solicitados.

Respuesta

{
  success: true,
  data: {
    ...
 }
}

Ejemplo:

try {
  const response = await apacuanaWeb.getRequerimentsByTypeUser({ type: 1 });
  console.log("Requisitos:", response.data.requirements);
} catch (error) {
  console.error("Error al obtener los requisitos:", error.message);
}

createApacuanaUser(userData)

Crea un nuevo usuario en la plataforma de Apacuana. Este método puede llamarse varias veces para ir completando la información de forma parcial; no es necesario enviar todos los datos en una sola llamada. Sin embargo, en cada actualización es obligatorio enviar el número de documento de identidad (kinddoc+doc). El registro inicial debe incluir el documento de identidad.

Los documentos requeridos para el usuario se obtienen previamente usando el método getRequerimentsByTypeUser y deben enviarse bajo la estructura { file-ID: File }, donde cada clave corresponde al identificador del documento y el valor es el archivo correspondiente.

Nota importante: El objeto retornado en la respuesta tendrá un atributo id, el cual corresponde con el customerId de Apacuana. Este valor debe ser asociado y almacenado en tu sistema para cada usuario. Cuando tu usuario esté autenticado en tu aplicación y desee conectarse a Apacuana, deberá usar este id como customerId en la configuración del SDK. Este valor se obtiene luego de solicitar un certificado por primera vez.

El objeto completo de usuario que puede acompañar la solicitud es:

{
  email: "[email protected]",
  typeuser: 1,
  name: "Nombre",
  lastname: "Apellido",
  kinddoc: "V",
  doc: 12345678,
  birthdate: "1990-01-01",
  kindrif: "V",
  gender: "M",
  rif: 12345678,
  phone: 4121234567,
  kindphone: "0424",
  state: "Estado",
  municipality: "Municipio",
  parish: "Parroquia",
  postalcode: "1010",
  address: "Dirección",
  fiscaladdress: "Dirección fiscal",
  fiscalkindphone: "0424",
  fiscalphone: 4121234567,
  occupation: "Ocupación",
  degree: "Título",
  university: "Universidad",
  graduationyear: "2010",
  collegiatenumber: "12345",
  collegiateyear: "2011",
  companyname: "Empresa",
  companykindrif: "J",
  companyrif: "J12345678",
  companystate: "Estado",
  companymunicipality: "Municipio",
  companyparish: "Parroquia",
  companyaddress: "Dirección empresa",
  companykindphone: "0212",
  companyphone: "2121234567",
  companypostalcode: "1010",
  companywebpage: "https://empresa.com",
  companycommercialregister: "Registro comercial",
  companyregisterdate: "2015-01-01",
  companyregisternumber: "123456",
  companyconstitutiondate: "2015-01-01",
  companypublishdate: "2015-01-01",
  companyconstitutiondecree: "Decreto",
  companynumberdecree: "123",
  positionprivate: "Cargo privado",
  departmentprivate: "Departamento privado",
  authorizedprivate: "Autorizado privado",
  functionsprivate: "Funciones privado",
  publishprivate: "2015-01-01",
  issuedateprivate: "2015-01-01",
  kindphoneprivate: "0424",
  phoneprivate: 4121234567,
  positionpublic: "Cargo público",
  departmentpublic: "Departamento público",
  authorizedpublic: "Autorizado público",
  functionspublic: "Funciones público",
  publishpublic: "2015-01-01",
  issuedatepublic: "2015-01-01",
  kindphonepublic: "0424",
  phonepublic: 4121234567,
  companyid: "uuid-empresa"
}

Ejemplo:

try {
  const userData = {
    usr: "[email protected]",
    pwd: "contraseñaSegura123",
    kinddoc: "V",
    doc: "12345678",
    // ...otros campos opcionales
    files: {
      "file-1": file1, // Instancia de File
      "file-2": file2,
      // ...otros documentos según los requerimientos
    },
  };
  const response = await apacuanaWeb.createApacuanaUser(userData);
  console.log("Usuario creado:", response.data);
} catch (error) {
  console.error("Error al crear el usuario:", error.message);
}

Comportamiento

• Permite crear o actualizar usuarios de forma parcial o total.
• Los documentos requeridos se obtienen previamente usando getCertRequerimentsByType.
• Devuelve una instancia de ApacuanaSuccess con la información del usuario creado o actualizado.

Métodos privados

getCustomer()

Obtiene los datos del cliente autenticado.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Devuelve una instancia de ApacuanaSuccess con los datos del usuario y el token de autenticación.

Ejemplo de uso:

const result = await apacuanaWeb.getCustomer();
// result.data contendrá los datos del usuario y el token

generateCert(params)

Genera un nuevo certificado digital y lo almacena localmente.

Parámetros:

• params: (String) Contrase;a unica para generar y posteriormente utilizar el certificado

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Genera un par de claves, crea una CSR, la envía al servidor y almacena el certificado y la clave privada cifrada en el dispositivo.

Respuesta

{
  success: true,
  data: {
  ...
  }
}

getCertStatus()

Verifica el estado del certificado del usuario.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Devuelve el estado actual del certificado, incluyendo texto y descripción.

Respuesta

{
  success: true,
  data: {
    status: {
      text: "...",
      descriptionText: "..."
    }
  }
}

Los posibles valores de text incluyen:

• "Por verificar"
• "En revisión"
• "Por generar"
• "Vigente"
• "Por revocar"
• "Revocado"
• "Verificado"
• "Certificado expirado"

Ejemplo:

try {
  const response = await apacuanaWeb.getCertStatus();
  console.log("Estado del certificado:", response.data.status.text);
  if (response.data.status.descriptionText) {
    console.log("Descripción:", response.data.status.descriptionText);
  }
} catch (error) {
  console.error("Error al obtener el estado del certificado:", error.message);
}

addSigner(params)

Añade un firmante a un documento. El comportamiento y los campos obligatorios dependen del integrationType configurado durante la inicialización.

Parámetros:

• params: Objeto con los datos del firmante y el documento.
  • name (String, obligatorio): Nombre del documento.
  • document (File, opcional): El archivo del documento a firmar (ej. un PDF). No puede coexistir con reference.
  • reference (String, opcional): Referencia única para un documento ya existente en la plataforma. No puede coexistir con document.
  • typedoc (String, obligatorio): Tipo de documento de identidad del firmante. Valores permitidos: "V", "P", "E".
  • doc (String, obligatorio): Número de documento de identidad del firmante.
  • signature (Array, obligatorio): Un array de objetos que definen la posición de la firma. Debe contener al menos un objeto con:
    • page (Number, obligatorio): Página donde se estampará la firma (entero positivo).
    • x (Number, obligatorio): Coordenada X (de 0 a 1, porcentual respecto al ancho del PDF).
    • y (Number, obligatorio): Coordenada Y (de 0 a 1, porcentual respecto al alto del PDF).

Notas sobre document y reference:

• Solo uno de estos parámetros debe ser enviado. Si el cliente tiene integración con el gestor documental de Apacuana, se debe usar reference para referenciar el documento existente en la plataforma.
• Si no existe integración documental, se debe enviar el archivo document (File). Este archivo será posteriormente solicitado para la firma del documento luego de ser asignado.

Notas sobre posicionamiento:

• Las coordenadas x e y son porcentuales y van de 0 a 1.
• El origen (0,0) está en la esquina superior izquierda del PDF.
• Ejemplos de posicionamiento:
  • Esquina superior izquierda: { x: 0, y: 0 }
  • Esquina superior derecha: { x: 1, y: 0 }
  • Esquina inferior izquierda: { x: 0, y: 1 }
  • Centro de la página: { x: 0.5, y: 0.5 }

Ejemplo:

try {
  const signer = {
    name: "Contrato",
    document: documentFile, // Instancia de File
    typedoc: "V",
    doc: "12345678",
    signature: [
      { page: 1, x: 0, y: 0 }, // Esquina superior izquierda
      { page: 1, x: 1, y: 0 }, // Esquina superior derecha
      { page: 1, x: 0, y: 1 }, // Esquina inferior izquierda
      { page: 1, x: 0.5, y: 0.5 }, // Centro de la página
    ],
  };
  const response = await apacuana.addSigner(signer);
  console.log("Firmante añadido:", response.data);
} catch (error) {
  console.error("Error al añadir firmante:", error.message);
}

getDocsByCustomer(params)

Obtiene la lista de documentos asociados al usuario.

Parámetros

• params: Objeto con parámetros de paginación y filtros.

  • page (Number, obligatorio)
  • size (Number, obligatorio)
  • status (Number, opcional)

• (status) 0 pendiente, 1 = completado/firmado, -1 rechazado

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Permite filtrar y paginar los documentos asociados al usuario.

Respuesta

{
  success: true,
  data: {
    /* lista de documentos */
  }
}

Ejemplo:

try {
  const params = {
    page: 1,
    size: 10,
    status: 0, // Estado del documento
  };
  const response = await apacuanaWeb.getDocsByCustomer(params);
  console.log("Documentos filtrados:", response.data);
} catch (error) {
  console.error("Error al obtener los documentos:", error.message);
}

Notas:

• Si no se especifican filtros, se devolverán todos los documentos paginados.

signChallenge(params)

Firma criptográficamente una cadena de desafío (challenge) proporcionada por el servidor, utilizando el certificado y la clave privada almacenados localmente. Este método es fundamental para la Autenticación Fuerte o Prueba de Posesión (Proof of Possession).

Parámetros

• params: Objeto con parámetros de challenge y pin.
  • challenge (String, obligatorio)
  • pin (String, obligatorio)

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Recuperación segura: Utiliza el pin para descifrar y recuperar el certificado y la clave privada del almacenamiento seguro (IndexedDB).
• Firma Local: Calcula el digest (resumen) del challenge (usando SHA-512) y lo firma localmente con la clave privada.
• Validación Local: Verifica la firma generada usando el certificado público del usuario para asegurar que la clave privada funcionó correctamente.
• Devolución: Si la firma es válida, devuelve los datos necesarios para completar la autenticación en el servidor.
• Permite filtrar y paginar los documentos asociados al usuario.

Notas:

• Este método no interactúa con la API de Apacuana para el proceso de firma. Solo genera la firma localmente. La aplicación cliente es responsable de tomar la respuesta (signature y certificate) y enviarla al servidor para que este la verifique.

Respuesta

{
  success: true,
  data: {
    signature: "BASE64_DE_LA_FIRMA_DEL_CHALLENGE",
    certificate: "BASE64_DEL_CERTIFICADO_DEL_USUARIO",
    challenge: "LA_CADENA_DE_DESAFIO_ORIGINAL",
  }
}

Ejemplo:

try {
  const challengeToken = "d7e9b0c2a5f1e8d4c7b0a3f6e9d2c5b8";
  const userPin = "MiPinSecreto123";

  const response = await apacuanaWeb.signChallenge({
    challenge: challengeToken,
    pin: userPin,
  });

  console.log("Firma generada:", response.data.signature);
} catch (error) {
  console.error("Error al firmar el desafío:", error.message);
}

Notas:

• Si no se especifican filtros, se devolverán todos los documentos paginados.

signDocument(params)

Firma un documento usando el certificado y clave privada local.

Parámetros

El parámetro params debe incluir:

• signature (Object, obligatorio):

  • id (String): ID de la firma.
  • positions (Array): Posiciones de la firma en el documento.

• document (File, opcional): Archivo del documento a firmar.

  Importante:

• El objeto signature debe ser obtenido directamente del array de documentos devuelto por el método getDocsByCustomer, específicamente del atributo signaturedata de dicho documento.

• Si en el método addSigner se utilizó el parámetro reference, no es necesario incluir el archivo document al firmar, ya que el documento está referenciado en la plataforma.

• Si en addSigner se utilizó el parámetro document (archivo), será necesario proporcionar nuevamente el archivo en este método para completar la firma.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Recupera el certificado y clave privada, obtiene el digest, firma localmente y envía la firma al servidor.

Respuesta

{
  success: true,
  data: {
    /* información del documento firmado */
  }
}

Ejemplo:

// Caso con documento referenciado
const result = await apacuana.signDocument({
  signature: { id: "sig-123", positions: [{ page: 1, x: 0.5, y: 0.5 }] },
  // No se requiere document
});

// Caso con documento por archivo
const result = await apacuana.signDocument({
  signature: { id: "sig-123", positions: [{ page: 1, x: 0.5, y: 0.5 }] },
  document: documentFile, // Instancia de File
});
// result.data contendrá la información del documento firmado

uploadSignatureVariant(params)

Sube una imagen de variante de firma para el usuario autenticado.

Parámetros

El parámetro params debe incluir:

• file (File, obligatorio): Archivo de imagen en formato PNG (image/png).

Notas importantes:

• El archivo debe ser una instancia de File y tener el tipo MIME image/png.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Sube la imagen de la firma y la asocia al usuario.

Respuesta

{
  success: true,
  data: {
    /* información de la variante subida */
  }
}

Ejemplo:

const imageFile = new File(
  [
    /* datos */
  ],
  "firma.png",
  { type: "image/png" }
);
try {
  const response = await apacuanaWeb.uploadSignatureVariant({
    file: imageFile,
  });
  console.log(response.data);
} catch (error) {
  console.error(error.message);
}

getSignatureVariant()

Obtiene la imagen de la variante de firma registrada.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Devuelve la imagen en Base64 o información asociada.

Respuesta

{
  success: true,
  data: {
    /* imagen de la firma en Base64 */
  }
}

Ejemplo

try {
  const response = await apacuanaWeb.getSignatureVariant();
  console.log(response.data);
} catch (error) {
  console.error(error.message);
}

deleteSignatureVariant()

Elimina la variante de firma almacenada.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Elimina la variante de firma si existe.

Respuesta

{
  success: true,
  data: {
    /* información del estado tras eliminar la variante */
  }
}

Ejemplo

try {
  const response = await apacuanaWeb.deleteSignatureVariant();
  console.log(response.data);
} catch (error) {
  console.error(error.message);
}
---

startLivenessCheck(container?)

Inicia una prueba de vida (liveness check) para el usuario.

Parámetros

• container (opcional): Elemento HTML donde se renderiza la prueba. Si se omite, se muestra en un modal.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Crea una sesión de prueba de vida y muestra la interfaz correspondiente.

Respuesta

{
  success: true,
  data: {
    /* resultado de la prueba de vida */
  }
}

Ejemplo:

try {
  const response = await apacuanaWeb.startLivenesCheck();
  console.log("Resultado de fe de vida:", response.data);
} catch (error) {
  console.error("Error al procesar la fe de vida:", error.message);
}

requestRevocation(params)

Solicita la revocación de un certificado.

Parámetros

• params: Objeto con la propiedad obligatoria:

  • reasonCode (Number): ID de la razón de revocación.

  Nota importante: el atributo reasonCode debe provenir de la lista de razones de revocacion, la cual obtenemos con el metodo: getRevocationReasons()

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Permite enviar la solicitud de revocación y documentos asociados.

Respuesta

{
  success: true,
  data: {
    /* información de la revocación */
  }
}

Ejemplo:

try {
  const response = await apacuanaWeb.requestRevocation({ reasonCode: 1 });
  console.log("Solicitud de revocación enviada:", response.data);
} catch (error) {
  console.error("Error al solicitar la revocación:", error.message);
}

getRevocationReasons()

Obtiene la lista de razones para la revocación de certificados.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Devuelve un array de razones de revocación proporcionadas por la API.

Respuesta

{
  success: true,
  data: {
    reasons: [ /* array de razones de revocación */ ]
  }
}

Ejemplo:

try {
  const response = await apacuanaWeb.getRevocationReasons();
  console.log("Razones de revocación:", response.data.reasons);
} catch (error) {
  console.error("Error al obtener las razones de revocación:", error.message);
}

importCertificate(params)

Importa un certificado previamente exportado.

Parámetros

• params: Objeto con el archivo y el PIN para importar el certificado.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Permite importar un certificado y clave privada previamente exportados.

Respuesta

{
  success: true,
  data: {
    /* información del proceso de importación */
  }
}

exportCertificateInJSON(params)

Exporta el certificado y claves del usuario a un archivo JSON seguro.

Parámetros

• params: Objeto con el PIN y nombre de archivo para exportar el certificado.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Exporta el certificado y clave privada cifrada a un archivo JSON con sello de integridad.

Respuesta

{
  success: true,
  data: {
    isExport: true
  }
}

isCertificateInDevice()

Verifica si existe un certificado almacenado localmente para el usuario.

Comportamiento

• Solo disponible si el SDK fue inicializado con customerId.
• Realiza una comprobación rápida en el almacenamiento local.

Respuesta

{
  success: true,
  data: {
    isExist: true // o false
  }
}

Ejemplo:

try {
  const response = await apacuanaWeb.isCertificateInDevice();
  console.log(
    "Certificado existente en el dispositivo:",
    response.data.isExist
  );
} catch (error) {
  console.error(
    "Error al verificar si existe el certificado en el dispositivo:",
    error.message
  );
}

5. Manejo de Errores

El SDK utiliza un sistema de errores personalizado para facilitar la depuración.

• ApacuanaWebError: Errores generados por el SDK web. Suelen estar relacionados con el estado de la aplicación (ej. SDK no inicializado), validaciones (ej. PIN vacío) o problemas con IndexedDB.
• ApacuanaAPIError: Errores generados por apacuana-sdk-core. Estos errores se relanzan directamente y suelen estar relacionados con problemas de comunicación con la API de Apacuana (ej. apiKey inválida, errores del servidor).

Todos los errores lanzados por el SDK pueden ser capturados con un bloque try...catch.

ApacuanaWebErrorCode

Los errores de tipo ApacuanaWebError incluyen un código para identificar la causa raíz:

• NOT_INITIALIZED: Se intentó usar un método antes de llamar a init().
• VALIDATION_ERROR: Un parámetro de entrada no pasó la validación (ej. pin vacío).
• NOT_FOUND: No se encontró un recurso esperado (ej. la clave privada en IndexedDB).
• UNKNOWN_ERROR: Un error inesperado ocurrió dentro del SDK.