apacuana-sdk-core 0.11.0 → 0.13.0

package/README.md

@@ -1,49 +1,22 @@
 # 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.
+`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](#instalación)
 - [Inicialización](#inicialización)
 - [Conceptos Clave](#conceptos-clave)
-  - [Tipos de Integración](#tipos-de-integración)
 - [Interfaz Pública](#interfaz-pública)
-  - [`init(config)`](#initconfig)
-  - [`close()`](#close)
-  - [`getConfig()`](#getconfig)
-  - [`getCustomer()`](#getcustomer)
-  - [`generateCert(encryptedCSR)`](#generatecertencryptedcsr)
-  - [`getCertStatus(isCertificateInDevice)`](#getcertstatusiscertificateindevice)
-  - [`getCertTypes()`](#getcerttypes)
-  - [`getRequerimentsByTypeUser(params)`](#getrequerimentsbytypeuserparams)
-  - [`requestCertificate(params)`](#requestcertificateparams)
-  - [`addSigner(signerData)`](#addsignersignerdata)
-  - [`getDocs(data)`](#getdocsdata)
-  - [`getDigest(signData)`](#getdigestsigndata)
-  - [`signDocument(signData)`](#signdocumentsigndata)
-  - [`uploadSignatureVariant(data)`](#uploadsignaturevariantdata)
-  - [`getSignatureVariant()`](#getsignaturevariant)
-  - [`deleteSignatureVariant()`](#deletesignaturevariant)
-  - [`createFaceLivenessSession()`](#createfacelivenesssession)
-  - [`requestRevocation(params)`](#requestrevocationparams)
-  - [`getRevocationReasons()`](#getrevocationreasons)
 - [Manejo de Errores](#manejo-de-errores)
-  - [`ApacuanaSuccess`](#apacuanasuccess)
-  - [`ApacuanaAPIError`](#apacuanaapierror)
-  - [Listado de Códigos de Error](#listado-de-códigos-de-error)
 - [Licencia](#licencia)
 
 ## Instalación
-
 ```bash
 npm install apacuana-sdk-core
 ```
 
 ## Inicialización
-
 Antes de utilizar el SDK, debes inicializarlo con tu configuración.
 
 ```javascript
@@ -55,7 +28,7 @@ const config = {
   apiKey: "tu-api-key",
   verificationId: "tu-verification-id",
   customerId: "tu-customer-id",
-  integrationType: "ONBOARDING", // o "ONPREMISE"
+  integrationType: "ONBOARDING", // o "onpremise"
 };
 
 try {
@@ -67,54 +40,45 @@ try {
 ```
 
 ## 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.
+
+- **`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.
 
 ## 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.
 
-- **`config`**: Objeto de configuración.
+- `config`: Objeto de configuración.
 
 ### `close()`
-
 Cierra la sesión del SDK y limpia la configuración.
 
 **Ejemplo:**
-
 ```javascript
 apacuana.close();
 console.log("Sesión del SDK cerrada.");
 ```
 
 ### `getConfig()`
-
 Devuelve la configuración actual.
 
 **Ejemplo:**
-
 ```javascript
 const currentConfig = apacuana.getConfig();
 console.log("Configuración actual:", currentConfig);
 ```
 
 ### `getCustomer()`
-
-Obtiene los datos del cliente.
+Obtiene los datos del cliente. Este método es el punto de entrada para iniciar una sesión y obtener el token y la información del usuario.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.getCustomer();
@@ -125,13 +89,12 @@ try {
 ```
 
 ### `generateCert(encryptedCSR)`
-
 Genera un nuevo certificado digital.
 
-- **`encryptedCSR`**: Objeto con la CSR encriptada.
+- `encryptedCSR`: Objeto con la CSR encriptada.
+  - `csr` (String): El Certificate Signing Request encriptado.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const csr = { csr: "MIIC...==" }; // CSR en formato Base64
@@ -143,13 +106,11 @@ try {
 ```
 
 ### `getCertStatus(isCertificateInDevice)`
-
 Obtiene el estado del certificado del usuario.
 
-- **`isCertificateInDevice`**: Booleano que indica si el certificado está en el dispositivo.
+- `isCertificateInDevice` (Boolean): Indica si el certificado ya está almacenado localmente.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.getCertStatus(false);
@@ -160,11 +121,9 @@ try {
 ```
 
 ### `getCertTypes()`
-
 Obtiene los tipos de certificados disponibles.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.getCertTypes();
@@ -175,13 +134,12 @@ try {
 ```
 
 ### `getRequerimentsByTypeUser(params)`
+Obtiene los requisitos para un tipo de certificado y usuario.
 
-Obtiene los requisitos para un tipo de usuario.
-
-- **`params`**: Objeto con la propiedad `type` (numérico).
+- `params`: Objeto con los parámetros de la consulta.
+  - `type` (Number): El tipo de certificado.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.getRequerimentsByTypeUser({ type: 1 });
@@ -191,56 +149,77 @@ try {
 }
 ```
 
-### `requestCertificate(params)`
-
-Solicita un certificado.
-
-- **`params`**: Objeto con las propiedades `type` (numérico) y `documents` (array).
-
-**Ejemplo:**
-
-```javascript
-try {
-  const params = { type: 1, documents: ["doc1.pdf", "doc2.pdf"] };
-  const response = await apacuana.requestCertificate(params);
-  console.log("Solicitud de certificado enviada:", response.data);
-} catch (error) {
-  console.error("Error al solicitar el certificado:", error.message);
-}
-```
-
 ### `addSigner(signerData)`
 
-Añade un firmante a un documento.
-
-- **`signerData`**: Objeto con los datos del firmante.
-
-**Ejemplo:**
-
-```javascript
-try {
-  const signer = {
-    name: "Contrato",
-    reference: "REF-001",
-    typedoc: "V",
-    doc: "12345678",
-    signature: [{ page: 1, x: 0.5, y: 0.5 }],
-  };
-  const response = await apacuana.addSigner(signer);
-  console.log("Firmante añadido:", response.data);
-} catch (error) {
-  console.error("Error al añadir firmante:", error.message);
-}
-```
+Añade un firmante a un documento. El comportamiento de esta función y sus campos obligatorios dependen del `integrationType` configurado durante la inicialización.
+
+- **Para `integrationType: 'ONBOARDING'`**:
+  Esta integración requiere que el documento se envíe como un archivo (`File` object). La validación de los datos se realiza a través de un helper que exige los siguientes campos:
+
+  - **`signerData`**: Objeto con los datos del firmante y el documento.
+    - `name` (String, **obligatorio**): Nombre del documento.
+    - `document` (File, **obligatorio**): El archivo del documento a firmar (ej. un PDF). No se puede usar junto con `reference`.
+    - `reference` (String, **obligatorio**): Referencia única para un documento ya existente en la plataforma. No se puede usar junto 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).
+      - `y` (Number, **obligatorio**): Coordenada Y (de 0 a 1).
+
+  **Ejemplo (`ONBOARDING`):**
+  ```javascript
+  try {
+    // documentFile debe ser una instancia de File
+    const documentFile = new File(["contenido"], "contrato.pdf", { type: "application/pdf" });
+
+    const signer = {
+      name: "Contrato",
+      document: documentFile,
+      typedoc: "V",
+      doc: "12345678",
+      signature: [{ page: 1, x: 0.5, y: 0.5 }],
+    };
+    const response = await apacuana.addSigner(signer);
+    console.log("Firmante añadido:", response.data);
+  } catch (error) {
+    console.error("Error al añadir firmante:", error.message);
+  }
+  ```
+
+- **Para `integrationType: 'onpremise'`**:
+  En esta integración, el `signerData` se envía como un objeto JSON. El documento no se envía como un archivo. La validación es más flexible en el lado del cliente.
+
+  - **`signerData`**: Objeto con los datos del firmante.
+    - `name` (String): Nombre del documento.
+    - `reference` (String): Referencia única para el documento.
+    - `typedoc` (String): Tipo de documento de identidad del firmante.
+    - `doc` (String): Número de documento de identidad del firmante.
+    - `signature` (Array): Posición de la firma.
+
+  **Ejemplo (`onpremise`):**
+  ```javascript
+  try {
+    const signer = {
+      name: "Contrato",
+      reference: "REF-001",
+      typedoc: "V",
+      doc: "12345678",
+      signature: [{ page: 1, x: 0.5, y: 0.5 }],
+    };
+    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.
 
-- **`data`**: Objeto con parámetros de paginación (`page`, `size`) y filtro (`status`).
+- `data`: Objeto con parámetros de paginación (`page`, `size`) y filtro (`status`).
 
 **Ejemplo:**
-
 ```javascript
 try {
   const params = { page: 1, size: 10, status: 0 };
@@ -252,16 +231,19 @@ try {
 ```
 
 ### `getDigest(signData)`
+Obtiene el digest de un documento para ser firmado. Un helper valida que se incluyan los siguientes campos obligatorios:
 
-Obtiene el digest de un documento para ser firmado.
-
-- **`signData`**: Objeto con `cert` y `signatureId`.
+- **`signData`**: Objeto con los siguientes datos:
+  - `cert` (String, **obligatorio**): El certificado en formato Base64.
+  - `signatureId` (String, **obligatorio**): El ID de la firma que se está procesando.
 
 **Ejemplo:**
-
 ```javascript
 try {
-  const params = { cert: "MIIC...==", signatureId: "sig-123" };
+  const params = {
+    cert: "MIIC...==", // Certificado en Base64
+    signatureId: "sig-123",
+  };
   const response = await apacuana.getDigest(params);
   console.log("Digest del documento:", response.data);
 } catch (error) {
@@ -270,17 +252,24 @@ try {
 ```
 
 ### `signDocument(signData)`
+Firma un documento utilizando el digest firmado. Un helper valida que se incluyan los siguientes campos obligatorios:
 
-Firma un documento.
-
-- **`signData`**: Objeto con `signature`, `cert` y `signedDigest`.
+- **`signData`**: Objeto con los siguientes datos:
+  - `signature` (Object, **obligatorio**): Objeto que contiene el ID de la firma y las posiciones.
+    - `id` (String, **obligatorio**): El ID de la firma.
+    - `positions` (Array, **obligatorio**): Un array de objetos para ajustar la posición de la firma.
+  - `cert` (String, **obligatorio**): El certificado en formato Base64.
+  - `signedDigest` (String, **obligatorio**): El digest del documento ya firmado.
+  - `document` (File, opcional): El archivo del documento, si es necesario para la integración.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const params = {
-    signature: { id: "sig-123" },
+    signature: { 
+      id: "sig-123",
+      positions: [{ page: 1, x: 0.5, y: 0.5, status: 1 }]
+    },
     cert: "MIIC...==",
     signedDigest: "abc...",
   };
@@ -292,13 +281,11 @@ try {
 ```
 
 ### `uploadSignatureVariant(data)`
-
 Sube una imagen de firma.
 
-- **`data`**: Objeto con la propiedad `file` (instancia de `File`, tipo `image/png`).
+- `data`: Objeto con la propiedad `file` (instancia de `File`, tipo `image/png`).
 
 **Ejemplo:**
-
 ```javascript
 // Este código se ejecutaría en un entorno de navegador
 const imageFile = new File(["..."], "firma.png", { type: "image/png" });
@@ -311,11 +298,9 @@ try {
 ```
 
 ### `getSignatureVariant()`
-
 Obtiene la imagen de la firma del usuario.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.getSignatureVariant();
@@ -327,11 +312,9 @@ try {
 ```
 
 ### `deleteSignatureVariant()`
-
 Elimina la imagen de la firma del usuario.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.deleteSignatureVariant();
@@ -342,11 +325,9 @@ try {
 ```
 
 ### `createFaceLivenessSession()`
-
 Crea una sesión de prueba de vida.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.createFaceLivenessSession();
@@ -356,14 +337,27 @@ try {
 }
 ```
 
-### `requestRevocation(params)`
+### `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:**
+```javascript
+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.
 
-- **`params`**: Objeto con la propiedad `reasonCode` (numérico).
+- `params`: Objeto con la propiedad `reasonCode` (numérico).
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.requestRevocation({ reasonCode: 1 });
@@ -374,11 +368,9 @@ try {
 ```
 
 ### `getRevocationReasons()`
-
 Obtiene la lista de razones para la revocación.
 
 **Ejemplo:**
-
 ```javascript
 try {
   const response = await apacuana.getRevocationReasons();
@@ -389,51 +381,30 @@ try {
 ```
 
 ## Manejo de Errores
-
-El SDK utiliza dos clases personalizadas para gestionar los resultados de las operaciones asíncronas: `ApacuanaSuccess` para éxitos y `ApacuanaAPIError` para fallos.
+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`. Esta clase encapsula la respuesta de la API y proporciona una estructura consistente para los datos devueltos.
+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.
 
-**Ejemplo de uso:**
-
-```javascript
-try {
-  // getCertTypes devuelve una instancia de ApacuanaSuccess
-  const response = await apacuana.getCertTypes();
-
-  console.log("La operación fue exitosa:", response.success); // true
-  console.log("Tipos de certificados:", response.data);
-} catch (error) {
-  // Manejo de errores (ver abajo)
-  console.error(error);
-}
-```
-
 ### `ApacuanaAPIError`
-
-Cuando la API devuelve un error o ocurre un problema durante la solicitud, la promesa es rechazada con una instancia de `ApacuanaAPIError`. Esta clase extiende el `Error` nativo de JavaScript y añade información contextual sobre el fallo.
+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`, `NOT_IMPLEMENTED`).
+- `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:**
-
 ```javascript
 try {
-  // Forzamos un error pasando parámetros inválidos
-  await apacuana.requestCertificate({ type: 999, documents: [] });
+  // Forzamos un error
+  await apacuana.addSigner({ doc: null });
 } catch (error) {
   if (error.name === "ApacuanaAPIError") {
     console.error("Ocurrió un error de la API de Apacuana:");
@@ -441,7 +412,6 @@ try {
     console.error("- Código de estado HTTP:", error.statusCode);
     console.error("- Código de error interno:", error.errorCode);
   } else {
-    // Captura de otros errores inesperados (ej. problemas de red)
     console.error("Ocurrió un error inesperado:", error);
   }
 }
@@ -449,22 +419,19 @@ try {
 
 ### Listado de Códigos de Error
 
-A continuación se muestra una lista de los `errorCode` más comunes que puede devolver el SDK:
-
-| `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.                               |
+| `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.