apacuana-sdk-core 0.6.2 → 0.7.0

package/README.md

@@ -53,22 +53,19 @@ Inicializa el SDK con la configuración proporcionada.
 
 - `Promise<boolean>` que se resuelve a `true` cuando la inicialización es exitosa.
 
+### close()
+
+Cierra la sesión actual del SDK y restablece la configuración a sus valores por defecto, dejando la instancia lista para una nueva inicialización.
+
+**Parámetros:** Ninguno
+
+**Retorna:** Nada
+
 **Ejemplo:**
 
 ```javascript
-try {
-  await apacuana.init({
-    apiUrl: "https://api.apacuana.com",
-    secretKey: "YOUR_SECRET_KEY",
-    apiKey: "YOUR_API_KEY",
-    verificationId: "VERIFICATION_ID",
-    customerId: "CUSTOMER_ID",
-    integrationType: "ONBOARDING",
-  });
-  console.log("SDK inicializado correctamente");
-} catch (error) {
-  console.error("Error al inicializar el SDK:", error);
-}
+apacuana.close();
+console.log("La sesión del SDK ha sido cerrada.");
 ```
 
 ### getConfig()
@@ -81,18 +78,11 @@ Obtiene la configuración actual del SDK.
 
 - `Object`: Configuración actual del SDK
 
-**Ejemplo:**
-
-```javascript
-const config = apacuana.getConfig();
-console.log("Configuración actual:", config);
-```
-
 ### getCustomer()
 
 Obtiene la información del cliente utilizando los datos de configuración.
 
-**Parámetros:** Ninguno (utiliza `verificationId` y `customerId` de la configuración)
+**Parámetros:** Ninguno
 
 **Retorna:**
 
@@ -101,37 +91,19 @@ Obtiene la información del cliente utilizando los datos de configuración.
   - `userData` (Object): Datos del usuario.
   - `success` (Boolean): Indicador de éxito de la operación.
 
-**Ejemplo:**
-
-```javascript
-try {
-  const { token, userData, success } = await apacuana.getCustomer();
-  if (success) {
-    console.log("Token de sesión:", token);
-    console.log("Datos del usuario:", userData);
-  }
-} catch (error) {
-  console.error("Error al obtener información del cliente:", error);
-}
-```
-
-### generateCert(csr)
+### generateCert(encryptedCSR)
 
-Genera un certificado digital basado en el tipo de integración configurado. Para la integración `ONBOARDING`, esta función valida la Solicitud de Firma de Certificado (CSR) y la envía a la API de Apacuana para su registro.
+Genera un certificado digital. El comportamiento y el parámetro esperado varían según el `integrationType`.
 
 **Parámetros:**
 
-- `csr` (String): Una cadena de texto en formato Base64 que representa la Solicitud de Firma de Certificado.
-
-**Validaciones:**
+- `encryptedCSR` (`EncryptedCSRObject`): Un objeto que contiene la Solicitud de Firma de Certificado (CSR) encriptada.
+  - `csr` (String): La CSR en formato Base64.
 
-- **csr**:
-  - Es un parámetro requerido.
-  - Debe ser una cadena de texto (`string`).
-  - No puede ser una cadena vacía.
-  - Debe estar codificada en formato Base64 válido.
+**Comportamiento por `integrationType`:**
 
-Si alguna de estas validaciones falla, la función lanzará una `ApacuanaAPIError` con el código `INVALID_PARAMETER` o `INVALID_PARAMETER_FORMAT`.
+- **`ONBOARDING`**: Valida la CSR y la envía a la API para su registro.
+- **`ONPREMISE`**: No soportado. Lanza una `ApacuanaAPIError` con el código `NOT_IMPLEMENTED`.
 
 **Retorna:**
 
@@ -142,20 +114,15 @@ Si alguna de estas validaciones falla, la función lanzará una `ApacuanaAPIErro
 **Ejemplo:**
 
 ```javascript
-// Asumiendo que 'myBase64Csr' es una variable que contiene tu CSR en formato Base64
-const myBase64Csr = "MIIC...==";
+const myCsrObject = { csr: "MIIC...==" };
 
 try {
-  const { cert, success } = await apacuana.generateCert(myBase64Csr);
+  const { cert, success } = await apacuana.generateCert(myCsrObject);
   if (success) {
     console.log("Certificado generado exitosamente:", cert);
   }
 } catch (error) {
-  if (error.name === "ApacuanaAPIError") {
-    console.error(`Error de API (${error.code}):`, error.message);
-  } else {
-    console.error("Ocurrió un error inesperado:", error);
-  }
+  console.error("Error al generar el certificado:", error.message);
 }
 ```
 
@@ -173,60 +140,62 @@ Obtiene el estado actual del certificado del usuario.
   - `status` (String): El estado del certificado (ver sección de Estados de Certificado).
   - `success` (Boolean): Indicador de éxito de la operación.
 
-**Ejemplo:**
+### addSigner(signerData)
 
-```javascript
-try {
-  const { status, success } = apacuana.getCertStatus(true);
-  if (success) {
-    console.log("Estado del certificado:", status);
-  }
-} catch (error) {
-  console.error("Error al obtener estado del certificado:", error);
-}
-```
+Agrega un firmante a un documento. El comportamiento y la estructura del objeto `signerData` varían según el `integrationType`.
 
-### signDocument(signData)
+**Parámetros:**
 
-Firma un documento utilizando un certificado digital y un digest previamente firmado. Esta función es compatible únicamente con el flujo de integración `ONBOARDING`.
+- `signerData` (`OnboardingSignerData` | `object`): Un objeto que contiene la información del firmante.
 
-**Parámetros:**
+---
 
-- `signData` (`SignDocumentData`): Un objeto que contiene los datos necesarios para la firma.
-  - `signature` (Object): Objeto con información de la firma.
-    - `id` (String): ID de la firma.
-    - `positions` (Array<Object>): Posiciones de la firma en el documento.
-  - `cert` (String): El certificado del firmante en formato base64.
-  - `signedDigest` (String): El digest del documento, ya firmado.
+#### Flujo de Integración: ONBOARDING
 
-**Retorna:**
+Para el tipo de integración `ONBOARDING`, la función espera un objeto `signerData` con una estructura específica y realiza validaciones estrictas sobre cada campo.
 
-- `Promise<object>`: Una promesa que se resuelve con la respuesta de la API tras completar la firma.
+**Estructura de `signerData` para ONBOARDING:**
 
-**Posibles `ApacuanaAPIError`:**
+```json
+{
+  "name": "Nombre del Documento",
+  "reference": "Referencia Externa",
+  "typedoc": "V",
+  "doc": "26122862",
+  "signature": [
+    {
+      "page": 1,
+      "x": 0.5,
+      "y": 0.85
+    }
+  ]
+}
+```
 
-- `NOT_IMPLEMENTED`: Si se invoca con un `integrationType` diferente a `ONBOARDING`.
-- `INVALID_PARAMETER`: Si los datos en `signData` son incorrectos o están incompletos.
+**Campos de `signerData`:**
 
-**Ejemplo:**
+-   **`name`** (`string`, requerido): Nombre del documento.
+-   **`reference`** (`string`, requerido): Referencia externa del documento en el gestor documental.
+-   **`typedoc`** (`string`, requerido): Tipo de documento de identidad. Valores permitidos: `V`, `P`, `E`.
+-   **`doc`** (`string`, requerido): Número del documento de identidad.
+-   **`signature`** (`Array<SignaturePosition>`, requerido): Un array de objetos que definen la posición de la firma.
+    -   **`page`** (`number`, requerido): Número de página (entero positivo).
+    -   **`x`** (`number`, requerido): Coordenada X (entre 0 y 1).
+    -   **`y`** (`number`, requerido): Coordenada Y (entre 0 y 1).
 
-```javascript
-const signData = {
-  signature: {
-    id: "unique-signature-id",
-    positions: [{ page: 1, x: 0.5, y: 0.8 }],
-  },
-  cert: "base64-encoded-certificate",
-  signedDigest: "signed-digest-of-the-document",
-};
+---
 
-try {
-  const response = await apacuana.signDocument(signData);
-  console.log("Documento firmado exitosamente:", response);
-} catch (error) {
-  console.error("Error al firmar el documento:", error.message);
-}
-```
+#### Flujo de Integración: ONPREMISE
+
+Esta funcionalidad aún no está implementada para el tipo de integración `ONPREMISE`. Invocar `addSigner` en este modo lanzará una `ApacuanaAPIError` con el código `NOT_IMPLEMENTED`.
+
+---
+
+**Retorna:**
+
+- `Promise<AddSignerResponse>` que se resuelve con un objeto que contiene:
+  - `signer` (String): Un identificador del firmante, construido a partir de `typedoc` y `doc`.
+  - `success` (Boolean): Indicador de éxito de la operación.
 
 ### getDigest(signData)
 
@@ -244,11 +213,22 @@ Obtiene el `digest` de un documento que se va a firmar. Este `digest` es un resu
   - `digest` (String): El digest del documento a firmar.
   - `success` (Boolean): Indicador de éxito de la operación.
 
-**Posibles `ApacuanaAPIError`:**
+### signDocument(signData)
+
+Firma un documento utilizando un certificado digital y un digest previamente firmado. Esta función es compatible únicamente con el flujo de integración `ONBOARDING`.
+
+**Parámetros:**
+
+- `signData` (`SignDocumentData`): Un objeto que contiene los datos necesarios para la firma.
+  - `signature` (Object): Objeto con información de la firma.
+    - `id` (String): ID de la firma.
+    - `positions` (Array<Object>): Posiciones de la firma en el documento.
+  - `cert` (String): El certificado del firmante en formato base64.
+  - `signedDigest` (String): El digest del documento, ya firmado.
+
+**Retorna:**
 
-- `INVALID_PARAMETER`: Si `cert` o `signatureId` no son válidos.
-- `API_RESPONSE_ERROR`: Si la API no devuelve un digest.
-- `NOT_IMPLEMENTED`: Si se llama con un `integrationType` no soportado (`ONPREMISE`).
+- `Promise<object>`: Una promesa que se resuelve con la respuesta de la API tras completar la firma.
 
 ### requestRevocation(reasonCode)
 
@@ -264,221 +244,58 @@ Solicita la revocación de un certificado.
   - `revocationStatus` (String): El estado de la solicitud (ej. "pending").
   - `requestId` (String | Number): El ID de la solicitud de revocación.
 
-**Ejemplo:**
+### getRevocationReasons()
 
-```javascript
-try {
-  const revocationResponse = await apacuana.requestRevocation("COMPROMISED");
-  console.log("Revocación solicitada:", revocationResponse);
-} catch (error) {
-  console.error("Error al solicitar revocación:", error);
-}
-```
+Obtiene la lista de códigos de motivo de revocación disponibles que se pueden usar en la función `requestRevocation`.
 
-### getDocs(data)
-
-Obtiene una lista de documentos paginada. El comportamiento de esta función varía según el `integrationType` configurado.
-
-**Parámetros:**
-
-- `data` (`GetDocsParams`): Objeto que contiene los parámetros para la consulta.
-  - `page` (Number): Número de página para la paginación.
-  - `size` (Number): Cantidad de resultados por página.
-  - `status` (Number, opcional): Filtra los documentos por su estado. Los valores permitidos son:
-    - `-1`: Rechazado
-    - `0`: Pendiente
-    - `1`: Firmado
-    - `2`: En proceso
+**Parámetros:** Ninguno
 
 **Retorna:**
 
-- `Promise<GetDocsResponse>`: Un objeto que contiene:
-  - `totalRecords` (Number): El número total de documentos que coinciden con la consulta.
-  - `records` (Array<Object>): Un array de objetos, donde cada objeto es un documento.
+- `Promise<RevocationReasonsResponse>`: Un objeto que contiene:
+  - `reasons` (Array<Object>): Un array de objetos, donde cada objeto representa un motivo de revocación con `code` y `description`.
   - `success` (Boolean): Indicador de éxito de la operación.
 
 **Comportamiento por `integrationType`:**
 
-- **`ONBOARDING`**: Obtiene los documentos asociados al `customerId` configurado.
-- **`ONPREMISE`**: No soportado. Lanza un `ApacuanaAPIError` con el código `NOT_IMPLEMENTED`.
-
-**Ejemplo (`ONBOARDING`):**
-
-```javascript
-try {
-  const documents = await apacuana.getDocs({ page: 1, size: 10, status: 1 });
-  console.log("Documentos:", documents);
-} catch (error) {
-  console.error("Error al obtener documentos:", error.message);
-}
-```
-
-**Posibles `ApacuanaAPIError`:**
-
-- `INVALID_PARAMETER`: Si `page`, `size` o `status` no son válidos.
-- `CONFIGURATION_ERROR`: Si el `customerId` no está configurado en la inicialización.
-- `NOT_IMPLEMENTED`: Si se llama con `integrationType` igual a `ONPREMISE`.
+- **`ONBOARDING`**: Obtiene la lista de motivos desde la API.
+- **`ONPREMISE`**: No soportado. Lanza una `ApacuanaAPIError` con el código `NOT_IMPLEMENTED`.
 
-### addSigner(signerData)
+### getDocs(data)
 
-Agrega un firmante a un documento. El comportamiento de esta función y la estructura del objeto `signerData` varían según el `integrationType` configurado (`ONBOARDING` u `ONPREMISE`).
+Obtiene una lista de documentos paginada.
 
 **Parámetros:**
 
-- `signerData` (Object): Un objeto que contiene la información del firmante. Su estructura es específica para cada tipo de integración.
-
----
-
-#### Flujo de Integración: ONBOARDING
-
-Para el tipo de integración `ONBOARDING`, la función espera un objeto `signerData` con la siguiente estructura y realiza validaciones estrictas sobre cada campo.
-
-**Estructura de `signerData` para ONBOARDING:**
-
-```json
-{
-  "name": "Nombre del Documento",
-  "reference": "Referencia Externa",
-  "typedoc": "V",
-  "doc": "26122862",
-  "signature": [
-    {
-      "page": 1,
-      "x": 0.5,
-      "y": 0.85
-    }
-  ]
-}
-```
-
-**Validaciones (ONBOARDING):**
-
-- **signerData**: Debe ser un objeto no vacío.
-- **name**: Requerido, `string`.
-- **reference**: Requerido, `string`. (referencia del documento en el gestor documental)
-- **typedoc**: Requerido, debe ser `V`, `P` o `E`.
-- **doc**: Requerido, `string`.
-- **signature**: Requerido, `array` no vacío.
-  - Cada objeto en el `array` debe tener:
-    - `page`: Requerido, `número` entero positivo.
-    - `x`: Requerido, `número` entre 0 y 1.
-    - `y`: Requerido, `número` entre 0 y 1.
-
-Si alguna validación falla, se lanzará una `ApacuanaAPIError` con el código `INVALID_PARAMETER` o `INVALID_PARAMETER_FORMAT`.
-
----
+- `data` (`GetDocsParams`): Objeto que contiene los parámetros para la consulta.
+  - `page` (Number): Número de página.
+  - `size` (Number): Cantidad de resultados por página.
+  - `status` (Number, opcional): Filtra por estado (`-1`: Rechazado, `0`: Pendiente, `1`: Firmado, `2`: En proceso).
 
 **Retorna:**
 
-- `Promise<AddSignerResponse>` que se resuelve con un objeto que contiene:
-  - `signer` (String): Un identificador del firmante, construido a partir de `typedoc` y `doc`.
+- `Promise<GetDocsResponse>`: Un objeto que contiene:
+  - `totalRecords` (Number): El número total de documentos.
+  - `records` (Array<Object>): Un array de documentos.
   - `success` (Boolean): Indicador de éxito de la operación.
 
-**Ejemplo (ONBOARDING):**
-
-```javascript
-const signerInfo = {
-  name: "Contrato de Servicios",
-  reference: "CS-2024-001",
-  typedoc: "V",
-  doc: "12345678",
-  signature: [{ page: 5, x: 0.25, y: 0.75 }],
-};
-
-try {
-  const response = await apacuana.addSigner(signerInfo);
-  console.log("Firmante agregado exitosamente:", response);
-} catch (error) {
-  if (error.name === "ApacuanaAPIError") {
-    console.error(`Error de API (${error.code}):`, error.message);
-  } else {
-    console.error("Ocurrió un error inesperado:", error);
-  }
-}
-```
-
 ## Estados de Certificado
 
-El SDK utiliza los siguientes estados para los certificados:
-
-- `PENDING`: El certificado está pendiente de generación o procesamiento
-- `ACTIVE`: El certificado está activo y puede ser utilizado
-- `EXPIRED`: El certificado ha caducado
-- `REVOKED`: El certificado ha sido revocado
-- `SUSPENDED`: El certificado está temporalmente suspendido
+- `PENDING`: Pendiente de generación.
+- `ACTIVE`: Activo y listo para usar.
+- `EXPIRED`: Caducado.
+- `REVOKED`: Revocado.
+- `SUSPENDED`: Suspendido temporalmente.
 
 ## Tipos de Integración
 
-El SDK soporta los siguientes tipos de integración:
-
-- `ONBOARDING`: Proceso de registro inicial y generación de certificado.
-- `ONPREMISE`: Integración donde el cliente gestiona su propia infraestructura. Algunas funcionalidades no están soportadas en este modo.
+- `ONBOARDING`: Proceso de registro y generación de certificado gestionado por Apacuana.
+- `ONPREMISE`: Integración donde el cliente gestiona su propia infraestructura.
 
 ## Manejo de Errores
 
-El SDK utiliza la clase `ApacuanaAPIError` para manejar errores específicos de la API. Esta clase extiende `Error` y proporciona información adicional sobre el error:
-
-```javascript
-try {
-  await apacuana.generateCert();
-} catch (error) {
-  if (error.name === "ApacuanaAPIError") {
-    console.error("Error de API:", error.message);
-    console.error("Código de error:", error.code);
-    console.error("Detalles:", error.details);
-  } else {
-    console.error("Error general:", error);
-  }
-}
-```
-
-## Seguridad
-
-El SDK implementa las siguientes medidas de seguridad:
-
-- Generación de pares de claves criptográficas (RSA)
-- Creación de CSR (Certificate Signing Request)
-- Comunicación segura con la API mediante HTTPS
-- Autenticación mediante apiKey y secretKey
+El SDK utiliza la clase `ApacuanaAPIError` para manejar errores específicos de la API, la cual extiende `Error` y añade las propiedades `code` y `details`.
 
 ## Licencia
 
-Este SDK está licenciado bajo términos propietarios. Consulte el acuerdo de licencia para más detalles.
-
-#### `generateCert(encryptedCSR)`
-
-Genera un nuevo certificado para un usuario ya existente.
-
--   **Parámetros:**
-    -   `encryptedCSR` (Object): Un objeto que contiene la Solicitud de Firma de Certificado (CSR) encriptada. Este objeto debe tener la siguiente estructura:
-        ```json
-        {
-          "csr": "string"
-        }
-        ```
-        Donde el valor de `csr` es la cadena de texto resultante de la encriptación.
-
--   **Retorna:** `Promise<Object>`
-  - `Promise<GenerateCertResponse>` que se resuelve con un objeto que contiene:
-    - `cert` (String): El certificado generado.
-    - `success` (Boolean): Indicador de éxito de la operación.
-
-**Ejemplo:**
-
-```javascript
-// Asumiendo que 'myBase64Csr' es una variable que contiene tu CSR en formato Base64
-const myBase64Csr = "MIIC...==";
-
-try {
-  const { cert, success } = await apacuana.generateCert(myBase64Csr);
-  if (success) {
-    console.log("Certificado generado exitosamente:", cert);
-  }
-} catch (error) {
-  if (error.name === "ApacuanaAPIError") {
-    console.error(`Error de API (${error.code}):`, error.message);
-  } else {
-    console.error("Ocurrió un error inesperado:", error);
-  }
-}
-```
+Este SDK está licenciado bajo términos propietarios.