Apacuana SDK Core

Descripción

Apacuana SDK Core es una biblioteca de JavaScript que proporciona una interfaz para interactuar con los servicios de Apacuana, permitiendo la generación de certificados digitales, firma de documentos, y otras operaciones relacionadas con la identidad digital.

Tabla de Contenidos

• Instalación
• Inicialización
• Conceptos Clave
• Interfaz Pública
• Manejo de Errores
• Licencia

Instalación

npm install apacuana-sdk-core

Inicialización

Antes de utilizar el SDK, debes inicializarlo con tu configuración.

import apacuana from "apacuana-sdk-core";

const config = {
  apiUrl: "https://api.url",
  secretKey: "tu-secret-key",
  apiKey: "tu-api-key",
  verificationId: "tu-verification-id",
  customerId: "tu-customer-id",
  integrationType: "ONBOARDING", // o "onpremise"
};

try {
  await apacuana.init(config);
  console.log("SDK inicializado correctamente.");
} catch (error) {
  console.error("Error al inicializar el SDK:", error);
}

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.

Inicialización y 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:

• getConfig()
• getCertTypes()
• getRequerimentsByTypeUser(params)
• createApacuanaUser(params)

Funciones privadas (requieren customerId):

• getCustomer()
• generateCert(params)
• getCertStatus(params)
• addSigner(params)
• getDocs(params)
• getDigest(params)
• signDocument(params)
• uploadSignatureVariant(params)
• getSignatureVariant()
• deleteSignatureVariant()
• createFaceLivenessSession()
• validateFaceLiveness({ sessionId })
• requestRevocation(params)
• getRevocationReasons()

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.

Interfaz Pública

Todas las funciones asíncronas devuelven una instancia de ApacuanaSuccess si tienen éxito, o lanzan una ApacuanaAPIError si fallan.

init(config)

Inicializa el SDK.

Parámetros requeridos en config:

| Propiedad | Tipo | Descripción | | ----------------- | ------ | ------------------------------------------------------------------------ | | apiUrl | String | URL base de la API de Apacuana. | | secretKey | String | Clave secreta proporcionada por Apacuana. | | apiKey | String | API Key proporcionada por Apacuana. | | verificationId | String | Identificador de verificación del cliente. | | integrationType | String | Tipo de integración. Valores permitidos: ONBOARDING, ONPREMISE. | | customerId | String | (Opcional) Identificador del usuario. Requerido para funciones privadas. |

Comportamiento:

• Si se inicializa sin customerId, el SDK solo permite el uso de funciones públicas.
• Si se inicializa con customerId, el SDK obtiene el token y los datos del usuario, permitiendo el acceso a funciones privadas.
• Si falta algún campo obligatorio o el integrationType no es válido, se lanzará un error.

Ejemplo:

import apacuana from "apacuana-sdk-core";

const config = {
  apiUrl: "https://api.url",
  secretKey: "tu-secret-key",
  apiKey: "tu-api-key",
  verificationId: "tu-verification-id",
  integrationType: "ONBOARDING", // o "ONPREMISE"
  customerId: "tu-customer-id", // Opcional
};

try {
  await apacuana.init(config);
  console.log("SDK inicializado correctamente.");
} catch (error) {
  console.error("Error al inicializar el SDK:", error);
}

close()

Cierra la sesión del SDK y limpia la configuración.

Ejemplo:

apacuana.close();
console.log("Sesión del SDK cerrada.");

getConfig()

Devuelve la configuración actual.

Ejemplo:

const currentConfig = apacuana.getConfig();
console.log("Configuración actual:", currentConfig);

getCustomer()

Obtiene los datos del usuario autenticado (customer) y su token de sesión. Este método solo está disponible si el SDK fue inicializado con customerId. No requiere parámetros de entrada. El resultado vendrá en el objeto data del response, incluyendo información relevante del usuario y el token de autenticación.

Ejemplo de uso:

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

generateCert(params)

Genera un nuevo certificado digital.

Parámetros:

• params: Objeto con la propiedad obligatoria:
  • csr (String): Certificate Signing Request encriptado (por ejemplo, en formato Base64).

Comportamiento:

• Solo disponible para integrationType: ONBOARDING. Si se usa con ONPREMISE, lanzará un error NOT_IMPLEMENTED.
• Realiza una solicitud a la API y devuelve una instancia de ApacuanaSuccess.

Respuesta:

{
  success: true,
  data: {
    cert: "...", // Certificado generado en formato string
    certifiedid: "..." // ID del certificado generado
  }
}

Ejemplo:

try {
  const csr = { csr: "MIIC...==" }; // CSR en formato Base64
  const response = await apacuana.generateCert(csr);
  console.log("Certificado generado:", response.data.cert);
  console.log("ID del certificado:", response.data.certifiedid);
} catch (error) {
  console.error("Error al generar el certificado:", error.message);
}

getCertStatus(params)

Obtiene el estado del certificado del usuario.

Parámetros:

• params (Boolean): Indica si el certificado ya está almacenado localmente en el dispositivo.

Respuesta:

{
  success: true,
  data: {
    status: {
      text: "...", // Estado legible del certificado
      descriptionText: "..." // Descripción adicional (puede ser undefined)
    }
  }
}

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 apacuana.getCertStatus(false);
  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);
}

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: [
      { ... },
      // ...otros tipos de certificado
    ]
  }
}

Ejemplo:

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

getRequerimentsByTypeUser(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

Respuesta:

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

Ejemplo:

try {
  const response = await apacuana.getRequerimentsByTypeUser({ type: 1 });
  console.log("Requisitos:", response.data.requirements);
} catch (error) {
  console.error("Error al obtener los requisitos:", 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);
}

getDocs(data)

Obtiene una lista paginada de documentos asociados al usuario autenticado, permitiendo aplicar filtros avanzados.

• data: Objeto con parámetros de paginación (page, size) y filtros opcionales (status). Puedes combinar estos filtros para obtener solo los documentos que cumplan con los criterios deseados.

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

Ejemplo:

try {
  const params = {
    page: 1,
    size: 10,
    status: 0, // Estado del documento
  };
  const response = await apacuana.getDocs(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.
• Los filtros disponibles pueden variar según la integración y la versión de la API.

getDigest(params)

Obtiene el digest (resumen criptográfico) de un documento para el usuario autenticado. Este método requiere que el SDK esté inicializado con customerId.

El parámetro params debe incluir:

• cert (String, obligatorio): Certificado en formato Base64.
• signatureId (String, obligatorio): ID de la firma que se está procesando.
• document (File, opcional): Archivo del documento a firmar.

Importante:

• Si en el método addSigner se utilizó el parámetro reference, no es necesario incluir el archivo document al obtener el digest, 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 obtener el digest.

Ejemplo de uso:

// Caso con documento referenciado
const result = await apacuana.getDigest({
  cert: "MIIC...==",
  signatureId: "sig-123",
  // No se requiere document
});

// Caso con documento por archivo
const result = await apacuana.getDigest({
  cert: "MIIC...==",
  signatureId: "sig-123",
  document: documentFile, // Instancia de File
});
// result.data contendrá el digest y detalles para la firma

signDocument(params)

Firma un documento utilizando el digest firmado y los datos de la firma. Este método requiere que el SDK esté inicializado con customerId.

El parámetro params debe incluir:

• signature (Object, obligatorio):
  • id (String): ID de la firma.
  • positions (Array): Posiciones de la firma en el documento.
• cert (String, obligatorio): Certificado en formato Base64.
• signedDigest (String, obligatorio): Digest firmado del 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.

Ejemplo de uso:

// Caso con documento referenciado
const result = await apacuana.signDocument({
  signature: { id: "sig-123", positions: [{ page: 1, x: 0.5, y: 0.5 }] },
  cert: "MIIC...==",
  signedDigest: "abc...",
  // 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 }] },
  cert: "MIIC...==",
  signedDigest: "abc...",
  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. Este método requiere que el SDK esté inicializado con customerId.

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.

Ejemplo de uso:

// En un entorno de navegador
const imageFile = new File(
  [
    /* datos */
  ],
  "firma.png",
  { type: "image/png" }
);
const result = await apacuana.uploadSignatureVariant({ file: imageFile });
// result.data contendrá la información de la variante subida

getSignatureVariant()

Obtiene la imagen de la variante de firma registrada para el usuario autenticado. Este método solo está disponible si el SDK fue inicializado con customerId. No requiere parámetros de entrada. El resultado vendrá en el objeto data del response, normalmente como una cadena en formato Base64 que representa la imagen de la firma.

Ejemplo de uso:

const result = await apacuana.getSignatureVariant();
// result.data contendrá la imagen en Base64

deleteSignatureVariant()

Elimina la variante de firma almacenada para el usuario autenticado. Este método solo está disponible si el SDK fue inicializado con un customerId. No requiere parámetros de entrada. Si la operación es exitosa, el resultado vendrá en el objeto data del response. Si no existe una variante de firma registrada, la operación no tendrá efecto y el resultado indicará el estado actual.

Ejemplo:

try {
  const response = await apacuana.deleteSignatureVariant();
  console.log(response.data);
} catch (error) {
  console.error("Error al eliminar la firma:", error.message);
}

createFaceLivenessSession()

Crea una nueva sesión de prueba de vida (face liveness) para el usuario autenticado. Este método solo está disponible si el SDK fue inicializado con customerId. No requiere parámetros de entrada. El resultado vendrá en el objeto data del response, incluyendo el identificador único de la sesión creada.

Ejemplo de uso:

const result = await apacuana.createFaceLivenessSession();
// result.data contendrá el ID de la sesión de prueba de vida

validateFaceLiveness({ sessionId })

Valida el resultado de una sesión de prueba de vida.

• sessionId (String, obligatorio): El ID de la sesión de prueba de vida que se va a validar.

Ejemplo:

try {
  const response = await apacuana.validateFaceLiveness({
    sessionId: "your-session-id",
  });
  console.log("Resultado de la validación:", response.data);
} catch (error) {
  console.error("Error al validar la sesión de prueba de vida:", error.message);
}

requestRevocation(params)

Solicita la revocación de un certificado.

Ejemplo de estructura de parámetros:

{
  reasonCode: 1, // Código de la razón de revocación
}

Comportamiento:

• Solo disponible para integrationType: ONBOARDING. Si se usa con ONPREMISE, lanzará un error NOT_IMPLEMENTED.
• Realiza una solicitud a la API y devuelve una instancia de ApacuanaSuccess con un mensaje de confirmación.

Respuesta:

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

Ejemplo:

try {
  const response = await apacuana.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 para integrationType: ONBOARDING. Si se usa con ONPREMISE, lanzará un error NOT_IMPLEMENTED.
• Devuelve una instancia de ApacuanaSuccess con un array de razones.

Respuesta:

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

Ejemplo:

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

createApacuanaUser(params)

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.

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 apacuana.createApacuanaUser(userData);
  console.log("Usuario creado:", response.data);
} catch (error) {
  console.error("Error al crear el usuario:", error.message);
}

Manejo de Errores

El SDK utiliza dos clases personalizadas para gestionar los resultados: ApacuanaSuccess para éxitos y ApacuanaAPIError para fallos.

ApacuanaSuccess

Cuando una operación se completa correctamente, la promesa se resuelve con una instancia de ApacuanaSuccess.

Propiedades:

• success (Boolean): Siempre true.
• statusCode (Number): El código de estado HTTP de la respuesta (ej. 200).
• data (Object): El cuerpo de la respuesta de la API.

ApacuanaAPIError

Cuando la API devuelve un error, la promesa es rechazada con una instancia de ApacuanaAPIError.

Propiedades:

• success (Boolean): Siempre false.
• statusCode (Number): El código de estado HTTP del error (ej. 400, 404, 500).
• errorCode (String): Un código de error específico de Apacuana (ej. INVALID_PARAMS).
• message (String): Una descripción legible del error.

Ejemplo de manejo de errores:

try {
  // Forzamos un error
  await apacuana.addSigner({ doc: null });
} catch (error) {
  if (error.name === "ApacuanaAPIError") {
    console.error("Ocurrió un error de la API de Apacuana:");
    console.error("- Mensaje:", error.message);
    console.error("- Código de estado HTTP:", error.statusCode);
    console.error("- Código de error interno:", error.errorCode);
  } else {
    console.error("Ocurrió un error inesperado:", error);
  }
}

Listado de Códigos de Error

| errorCode | Descripción | | :----------------------------- | :---------------------------------------------------------------------- | | CONFIGURATION_ERROR | Error en la configuración del SDK (ej. falta apiKey). | | INVALID_API_RESPONSE | La respuesta de la API no tiene el formato esperado. | | INVALID_PARAMETER | Uno o más parámetros de la función son inválidos. | | INVALID_PARAMETER_FORMAT | El formato de un parámetro es incorrecto. | | LOGICAL_API_ERROR | Error lógico devuelto por la API. | | NETWORK_ERROR | Error de red, CORS o timeout. | | NOT_IMPLEMENTED | La funcionalidad no está implementada para el integrationType actual. | | UNSUPPORTED_HTTP_METHOD | Se utilizó un método HTTP no soportado. | | UNSUPPORTED_INTEGRATION_TYPE | El integrationType no es válido. | | UNKNOWN_REQUEST_ERROR | Error desconocido durante la petición. | | API_RESPONSE_ERROR | La respuesta de la API contiene un error. |

Licencia

Este SDK está distribuido bajo una licencia propietaria. Para más detalles, contacte con el equipo de Apacuana.