apacuana-sdk-core 0.1.0 → 0.3.0

package/README.md

@@ -97,43 +97,69 @@ Obtiene la información del cliente utilizando los datos de configuración.
 **Retorna:**
 
 - Promise que se resuelve con un objeto que contiene:
-  - `token` (String): ID de sesión para autenticación
-  - `userData` (Object): Datos del usuario
+  - `token` (String): ID de sesión para autenticación.
+  - `userData` (Object): Datos del usuario.
+  - `success` (Boolean): Indicador de éxito de la operación.
 
 **Ejemplo:**
 
 ```javascript
 try {
-  const { token, userData } = await apacuana.getCustomer();
-  console.log("Token de sesión:", token);
-  console.log("Datos del usuario:", userData);
+  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()
+### generateCert(csr)
 
-Genera un certificado digital basado en el tipo de integración configurado.
+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.
 
-**Parámetros:** Ninguno (utiliza la configuración previa y datos del usuario)
+**Parámetros:**
+
+- `csr` (String): Una cadena de texto en formato Base64 que representa la Solicitud de Firma de Certificado.
+
+**Validaciones:**
+
+- **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.
+
+Si alguna de estas validaciones falla, la función lanzará una `ApacuanaAPIError` con el código `INVALID_PARAMETER` o `INVALID_PARAMETER_FORMAT`.
 
 **Retorna:**
 
-- Promise que se resuelve con la respuesta de la API de generación de certificados
+- `Promise` 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 certificateResponse = await apacuana.generateCert();
-  console.log("Certificado generado:", certificateResponse);
+  const { cert, success } = await apacuana.generateCert(myBase64Csr);
+  if (success) {
+    console.log("Certificado generado exitosamente:", cert);
+  }
 } catch (error) {
-  console.error("Error al generar certificado:", error);
+  if (error.name === "ApacuanaAPIError") {
+    console.error(`Error de API (${error.code}):`, error.message);
+  } else {
+    console.error("Ocurrió un error inesperado:", error);
+  }
 }
 ```
 
-### getCertStatus()
+### getCertStatus(isCertificateInDevice)
 
 Obtiene el estado actual del certificado del usuario.
 
@@ -141,19 +167,59 @@ Obtiene el estado actual del certificado del usuario.
 
 **Retorna:**
 
-- Promise que se resuelve con el estado del certificado (ver sección de Estados de Certificado)
+- Un objeto que contiene:
+  - `status` (String): El estado del certificado (ver sección de Estados de Certificado).
+  - `success` (Boolean): Indicador de éxito de la operación.
 
 **Ejemplo:**
 
 ```javascript
 try {
-  const status = await apacuana.getCertStatus();
-  console.log("Estado del certificado:", status);
+  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);
 }
 ```
 
+### signDocument(signData)
+
+Esta función está actualmente deshabilitada y lanzará un error si se invoca.
+
+**Parámetros:**
+
+- `signData` (Object): Datos para la firma.
+
+**Retorna:**
+
+- `Promise<void>`
+
+**Posibles `ApacuanaAPIError`:**
+
+- `NOT_IMPLEMENTED`: La función no está implementada para el tipo de integración.
+
+### getDigest(signData)
+
+Obtiene el digest de un documento que se va a firmar.
+
+- **Parámetros:**
+
+  - `signData` (Object): Objeto que contiene los datos para la firma.
+    - `cert` (String): Certificado en formato PEM.
+    - `signatureId` (String): Identificador único de la firma.
+
+- **Retorna:** `Promise<object>` - Un objeto que contiene:
+
+  - `digest` (String): El digest del documento a firmar.
+  - `success` (Boolean): Indicador de éxito de la operación.
+
+- **Posibles `ApacuanaAPIError`:**
+  - `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.
+
 ### requestRevocation(reasonCode)
 
 Solicita la revocación de un certificado.
@@ -177,67 +243,121 @@ try {
 }
 ```
 
-### signDocument(documentData, signatureData)
+#### `getDocs(data)`
+
+Obtiene una lista de documentos paginada. El comportamiento de esta función varía según el `integrationType` configurado.
+
+- **Parámetros:**
+
+  - `data` (object): 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
+
+- **Retorna:** `Promise<object>` - Un objeto que contiene:
+
+  - `totalRecords` (Number): El número total de documentos que coinciden con la consulta.
+  - `records` (Array): Un array de objetos, donde cada objeto es un documento.
+  - `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`.
+
+### addSigner(signerData)
 
-Firma un documento utilizando el certificado del usuario.
+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`).
 
 **Parámetros:**
 
-- `documentData` (Object): Datos del documento a firmar
-- `signatureData` (Object): Datos de la firma
+- `signerData` (Object): Un objeto que contiene la información del firmante. Su estructura es específica para cada tipo de integración.
 
-**Retorna:**
+---
 
-- Promise que se resuelve con la respuesta de la API de firma
+#### Flujo de Integración: ONBOARDING
 
-**Ejemplo:**
+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.
 
-```javascript
-try {
-  const documentData = {
-    id: "doc123",
-    content: "Base64EncodedContent...",
-  };
-
-  const signatureData = {
-    position: { x: 100, y: 200 },
-    page: 1,
-  };
-
-  const signResponse = await apacuana.signDocument(documentData, signatureData);
-  console.log("Documento firmado:", signResponse);
-} catch (error) {
-  console.error("Error al firmar documento:", error);
+**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
+    }
+  ]
 }
 ```
 
-### addSigner(signerData)
+**Validaciones (ONBOARDING):**
 
-Añade un firmante adicional a un documento.
+- **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.
 
-**Parámetros:**
+Si alguna validación falla, se lanzará una `ApacuanaAPIError` con el código `INVALID_PARAMETER` o `INVALID_PARAMETER_FORMAT`.
 
-- `signerData` (Object): Datos del firmante a añadir
+---
 
 **Retorna:**
 
-- Promise que se resuelve con la respuesta de la API
+- `Promise` que se resuelve con un objeto que contiene el ID del firmante (`signerId`) y el estado (`status`) si la operación es exitosa.
 
-**Ejemplo:**
+**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 signerData = {
-    documentId: "doc123",
-    email: "signer@example.com",
-    name: "John Doe",
-    role: "Approver",
-  };
-
-  const response = await apacuana.addSigner(signerData);
-  console.log("Firmante añadido:", response);
+  const response = await apacuana.addSigner(signerInfo);
+  console.log("Firmante agregado exitosamente:", response);
 } catch (error) {
-  console.error("Error al añadir firmante:", error);
+  if (error.name === "ApacuanaAPIError") {
+    console.error(`Error de API (${error.code}):`, error.message);
+  } else {
+    console.error("Ocurrió un error inesperado:", error);
+  }
 }
 ```