consultame-sdk 1.2.2 → 1.2.3

package/README.md

@@ -5,8 +5,8 @@ que se necesitan para interactuar con **SIFEN** (Sistema Integrado de Facturaci
 Nacional de Paraguay – SET).
 
 La librería **no** hace las peticiones HTTP al web service de SIFEN: su responsabilidad es
-**construir los sobres XML** (consulta de RUC, consulta de lote, consulta de documento y
-evento de nominación de un documento ya emitido),
+**construir los sobres XML** (consulta de RUC, consulta de lote, consulta de documento,
+envío de lote, y los eventos de nominación y cancelación de un documento ya emitido),
 **extraer el certificado y la llave privada** desde un archivo de firma digital `.p12`/`.pfx`,
 **firmar digitalmente (XMLDSig)** el Documento Electrónico generado y **generar el código QR**
 que se incrusta en el documento electrónico ya firmado.
@@ -27,6 +27,8 @@ Con esa salida, la aplicación consumidora envía los mensajes por su cuenta.
   - [`generateDocument`](#generatedocumentgeneratedocumentoelectronicodto)
   - [`signedXml`](#signedxmlxml-tag-responsedigitalsign)
   - [`nominationInvoice`](#nominationinvoicenominationinvoicedto)
+  - [`generateBatch`](#generatebatchgeneratebatchdto)
+  - [`cancelInvoice`](#cancelinvoicecancelinvoicedto)
 - [DTOs (contratos de entrada)](#dtos-contratos-de-entrada)
 - [Funciones utilitarias internas](#funciones-utilitarias-internas)
 - [Arquitectura del proyecto](#arquitectura-del-proyecto)
@@ -186,6 +188,19 @@ const xmlNominacion = sifen.nominationInvoice({
   digitoVerificado: "1",
   razonSocial: "Cliente Ejemplo S.R.L.",
 });
+
+// 9) Armar el sobre de envío de lote (rEnvioLote) con el/los documento(s) ya preparados
+const xmlLoteEnvio = sifen.generateBatch({
+  id: 5,
+  xml: xmlConQr, // contenido que va dentro de <xDE>
+});
+
+// 10) Cancelar un documento ya emitido (evento de cancelación, sin firmar)
+const xmlCancelacion = sifen.cancelInvoice({
+  id: 6,
+  cdc: "01800123456001001000000012023052212345678901",
+  motivo: "Error en los datos de la operación",
+});
 ```
 
 ---
@@ -775,6 +790,113 @@ try {
 
 ---
 
+### `generateBatch(generateBatchDto)`
+
+Genera el sobre SOAP `rEnvioLote` que envuelve el contenido que la aplicación quiere enviar a
+SIFEN como **lote** de documentos electrónicos.
+
+> ⚠️ La librería **no** valida, comprime ni codifica el contenido: `xml` se inserta tal cual
+> dentro de `<xDE>`. Si el web service de SIFEN espera ese contenido comprimido/codificado,
+> la aplicación consumidora debe prepararlo antes de llamar a este método.
+
+| Parámetro | Tipo     | Descripción                                          |
+| --------- | -------- | ---------------------------------------------------- |
+| `id`      | `number` | Identificador de la petición (`dId`).                |
+| `xml`     | `string` | Contenido a incluir en `<xDE>` (documento/s del lote). |
+
+**Retorna:** `string` — XML SOAP. A diferencia de las consultas, **no pasa por `normalizeXML`**:
+el sobre conserva los saltos de línea y la indentación de la plantilla.
+
+```ts
+const xml = sifen.generateBatch({ id: 5, xml: xmlDocumentoFirmado });
+```
+
+<details>
+<summary>Ejemplo de salida</summary>
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+  <env:Header/>
+  <env:Body>
+    <rEnvioLote xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>5</dId>
+      <xDE>...</xDE>
+    </rEnvioLote>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `cancelInvoice(cancelInvoiceDto)`
+
+Genera el sobre SOAP `rEnviEventoDe` con el **evento de cancelación** (`rGeVeCan`) de un
+documento electrónico ya emitido, identificado por su **CDC**.
+
+> ⚠️ El XML devuelto **no está firmado**: la aplicación consumidora debe firmar el evento y
+> enviarlo a SIFEN por su cuenta.
+
+| Parámetro | Tipo     | Descripción                                                  |
+| --------- | -------- | ------------------------------------------------------------ |
+| `id`      | `number` | Identificador de la petición (`dId`).                        |
+| `cdc`     | `string` | CDC del documento a cancelar (`Id` de `rGeVeCan`).           |
+| `motivo`  | `string` | Motivo de la cancelación (`mOtEve`).                         |
+
+**Retorna:** `string` — XML SOAP con `dFecFirma` tomado de la fecha/hora actual y `dVerFor` = `150`.
+El evento interno (`dEvReg`) va normalizado en una sola línea, pero el sobre externo conserva los
+saltos de línea de la plantilla.
+
+> A diferencia de [`nominationInvoice`](#nominationinvoicenominationinvoicedto), este método
+> **no valida el DTO** (longitud del CDC o del motivo) y el atributo `Id` de `rEve` se emite
+> con valor fijo `1`; `id` solo se usa como `dId`.
+
+```ts
+const xml = sifen.cancelInvoice({
+  id: 6,
+  cdc: "01800123456001001000000012023052212345678901",
+  motivo: "Error en los datos de la operación",
+});
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</summary>
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+  <env:Header/>
+  <env:Body>
+    <rEnviEventoDe xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>6</dId>
+      <dEvReg>
+        <gGroupGesEve xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                      xsi:schemaLocation="http://ekuatia.set.gov.py/sifen/xsd siRecepEvento_v150.xsd">
+          <rGesEve>
+            <rEve Id="1">
+              <dFecFirma>2026-11-05T17:57:03</dFecFirma>
+              <dVerFor>150</dVerFor>
+              <gGroupTiEvt>
+                <rGeVeCan>
+                  <Id>01800123456001001000000012023052212345678901</Id>
+                  <mOtEve>Error en los datos de la operación</mOtEve>
+                </rGeVeCan>
+              </gGroupTiEvt>
+            </rEve>
+          </rGesEve>
+        </gGroupGesEve>
+      </dEvReg>
+    </rEnviEventoDe>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
 ## DTOs (contratos de entrada)
 
 Todos los DTOs de consulta extienden `GenerateIdDto`, que aporta el campo `id`.
@@ -819,6 +941,15 @@ interface NominationInvoiceDto extends GenerateIdDto {
   razonSocial: string;
   // ...y los campos opcionales del receptor (ruc, direccion, idDistricto, email, etc.)
 }
+
+interface GenerateBatchDto extends GenerateIdDto {
+  xml: string; // contenido que se inserta en <xDE>
+}
+
+interface CancelInvoiceDto extends GenerateIdDto {
+  cdc: string; // CDC del documento a cancelar
+  motivo: string; // motivo de la cancelación
+}
 ```
 
 Enums disponibles en [`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts):
@@ -835,15 +966,10 @@ enum LINK_SIFEN {
 }
 ```
 
-DTOs ya definidos pero **aún sin implementación** en la persistencia (ver
-[roadmap](#estado--roadmap)):
+DTO ya definido pero **aún sin implementación** en la persistencia (ver
+[roadmap](#estado--roadmap)); se importa por ruta y no está en el barrel `dtos/index.ts`:
 
 ```ts
-interface CancelInvoiceDto extends GenerateIdDto {
-  cdc: string;
-  motivo: string;
-}
-
 interface InvalidationInvoiceDto extends GenerateIdDto {
   timbrado: string;
   establecimiento: number;
@@ -879,7 +1005,9 @@ No forman parte de la API pública, pero es útil conocerlas:
 | `generateConsultDocumentXml` | Arma el string XML de consulta de documento por CDC.                                          |
 | `generateConsultBatchXml`    | Arma el string XML de consulta de lote.                                                       |
 | `generateNominationInvoiceXml` | Valida el `NominationInvoiceDto` y arma el sobre `rEnviEventoDe` del evento de nominación con `xml2js.Builder`, ya normalizado. |
-| `convertToFormatDateSET`     | Formatea una `Date` como fecha/hora SIFEN (usada para `dFecFirma` del evento).                |
+| `generateSendBatchXml`       | Arma el sobre `rEnvioLote` con el contenido recibido dentro de `<xDE>` (sin normalizar).      |
+| `generateCancelInvoiceXml`   | Arma el sobre `rEnviEventoDe` del evento de cancelación (`rGeVeCan`) con `xml2js.Builder`; evento interno normalizado, sin firmar. |
+| `convertToFormatDateSET`     | Formatea una `Date` como fecha/hora SIFEN (usada para `dFecFirma` de los eventos).            |
 | `normalizeXML`               | Colapsa el XML a una sola línea: elimina saltos, tabulaciones y espacios entre etiquetas.     |
 | `readDigitalSign`            | Lee el `.p12` con `node-forge` y extrae certificado + llave privada en PEM, emparejando el certificado correcto por módulo RSA cuando hay varios. |
 | `signXml`                     | Firma un XML (XMLDSig) con `xml-crypto`: `enveloped-signature` + `exc-c14n`, digest SHA-256, firma RSA-SHA256. _(async)_ |
@@ -947,6 +1075,10 @@ mantener estado intermedio (`jsonFactura`) mientras se arma cada sección del XM
 delegando en `generateNominationInvoiceXml`, que valida el DTO y arma el evento con
 `xml2js.Builder` (a diferencia de las consultas simples, que son strings de plantilla).
 
+`cancelInvoice` (`CancelDocumentUseCase` → `SifenPersistence.cancelationInvoice`, nombre del
+puerto) y `generateBatch` (`GenerateBatchUseCase` → `SifenPersistence.generateBatch`) siguen el
+mismo flujo, delegando en `generateCancelInvoiceXml` y `generateSendBatchXml` respectivamente.
+
 **Por qué esta separación:**
 
 - **`domain`** no depende de nada externo: define _qué_ se hace (casos de uso) y el
@@ -991,6 +1123,7 @@ consultame-sdk/
 │       │   │   ├── digitalSign.dto.ts
 │       │   │   ├── generationQr.dto.ts
 │       │   │   ├── nominationInvoice.dto.ts
+│       │   │   ├── generateBatch.dto.ts
 │       │   │   ├── cancelDocument.dto.ts
 │       │   │   └── invalidationInvoice.dto.ts
 │       │   └── services/
@@ -1008,6 +1141,8 @@ consultame-sdk/
 │       │       ├── generateQr.useCase.ts
 │       │       ├── generateDocument.useCase.ts
 │       │       ├── nominationInvoice.useCase.ts
+│       │       ├── generateBatch.useCase.ts
+│       │       ├── cancelDocument.useCase.ts   # (importado por ruta, no está en el barrel)
 │       │       └── signedXml.useCase.ts
 │       │
 │       └── infrastructure/               # Detalles concretos (ADAPTADORES)
@@ -1049,16 +1184,17 @@ Funcionalidades **implementadas**:
   Crédito/Débito y Remisión (`generateDocument`)
 - ✅ Firma digital XMLDSig del Documento Electrónico (`signedXml`)
 - ✅ Evento de nominación de un documento emitido (`nominationInvoice`)
+- ✅ Sobre de envío de lote (`generateBatch`)
+- ✅ Evento de cancelación de un documento emitido (`cancelInvoice`)
 
 Definidas pero **pendientes de implementación** (hoy lanzan `Method not implemented`
 o aún no están expuestas en `SifenService`):
 
-- ⏳ Cancelación de documento (`cancelationInvoice` / `CancelInvoiceDto`)
 - ⏳ Inutilización de documentos (`invalidationInvoice` / `InvalidationInvoiceDto`)
 
 ---
 
 > **Nota:** esta librería genera insumos (XML, credenciales, firma XMLDSig y el QR) para SIFEN,
 > pero no realiza el envío HTTP de los documentos — eso queda a cargo de la aplicación
-> consumidora. El evento que devuelve `nominationInvoice` tampoco viene firmado. `generateQr` **requiere** que el XML ya venga firmado (con `signedXml` o por
+> consumidora. Los eventos que devuelven `nominationInvoice` y `cancelInvoice` tampoco vienen firmados. `generateQr` **requiere** que el XML ya venga firmado (con `signedXml` o por
 > cualquier otro medio), porque toma el `DigestValue` de la firma para calcular el hash del QR.

package/dist/index.js

@@ -143,6 +143,18 @@ var GenerateBatchUseCase = class {
   }
 };
 
+// src/sifen/domain/useCases/cancelDocument.useCase.ts
+var CancelDocumentUseCase = class {
+  constructor(sifenRepository) {
+    this.sifenRepository = sifenRepository;
+  }
+  sifenRepository;
+  execute(cancelInvoiceDto) {
+    const xml = this.sifenRepository.cancelationInvoice(cancelInvoiceDto);
+    return xml;
+  }
+};
+
 // src/shared/utils/dictionary.utils.ts
 var TIPOS_DOCUMENTOS = [
   {
@@ -8516,6 +8528,48 @@ var signXml = async (xml, tag, responseDigitalSign) => {
     throw error;
   }
 };
+var generateCancelInvoiceXml = (cancelInvocieDto) => {
+  const json = {};
+  json.gGroupGesEve = {};
+  json.gGroupGesEve.rGesEve = {};
+  json.gGroupGesEve.$ = {};
+  json.gGroupGesEve.$["xmlns:xsi"] = "http://www.w3.org/2001/XMLSchema-instance";
+  json.gGroupGesEve.$["xsi:schemaLocation"] = "http://ekuatia.set.gov.py/sifen/xsd siRecepEvento_v150.xsd";
+  json.gGroupGesEve.rGesEve.rEve = {};
+  json.gGroupGesEve.rGesEve.rEve.$ = {};
+  json.gGroupGesEve.rGesEve.rEve.$.Id = 1;
+  json.gGroupGesEve.rGesEve.rEve.dFecFirma = convertToFormatDateSET(/* @__PURE__ */ new Date());
+  json.gGroupGesEve.rGesEve.rEve.dVerFor = 150;
+  json.gGroupGesEve.rGesEve.rEve.gGroupTiEvt = {};
+  json.gGroupGesEve.rGesEve.rEve.gGroupTiEvt.rGeVeCan = {
+    Id: cancelInvocieDto.cdc,
+    mOtEve: cancelInvocieDto.motivo
+  };
+  const builder = new xml2js__namespace.Builder({
+    xmldec: {
+      version: "1.0",
+      encoding: "UTF-8",
+      standalone: false
+    }
+  });
+  let xml = builder.buildObject(json);
+  xml = normalizeXML(xml);
+  xml = xml.replace(
+    '<?xml version="1.0" encoding="UTF-8" standalone="no"?>',
+    ""
+  );
+  return `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+  <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+      <env:Header/>
+      <env:Body>
+          <rEnviEventoDe xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+            <dId>${cancelInvocieDto.id}</dId>
+            <dEvReg>${xml}</dEvReg>
+          </rEnviEventoDe>
+      </env:Body>
+  </env:Envelope>
+`;
+};
 
 // src/shared/clases/detalleDocumento.ts
 var DetalleDocumento = class {
@@ -10135,7 +10189,7 @@ var SifenPersistence = class {
     return xmlFormated;
   }
   cancelationInvoice(cancelInvoiceDto) {
-    throw new Error("Method not implemented.");
+    return generateCancelInvoiceXml(cancelInvoiceDto);
   }
   invalidationInvoice(invalidationInvoiceDto) {
     try {
@@ -10212,6 +10266,7 @@ var SifenService = class {
   signedXmlUseCase;
   nominationInvoiceUseCase;
   generateBatchUseCase;
+  cancelDocumentUseCase;
   sifenRepository;
   constructor() {
     this.sifenRepository = new SifenPersistence();
@@ -10232,6 +10287,9 @@ var SifenService = class {
       this.sifenRepository
     );
     this.generateBatchUseCase = new GenerateBatchUseCase(this.sifenRepository);
+    this.cancelDocumentUseCase = new CancelDocumentUseCase(
+      this.sifenRepository
+    );
   }
   consultRuc(consultRucDto) {
     const ruc = this.consultRucUseCase.execute(consultRucDto);
@@ -10283,6 +10341,10 @@ var SifenService = class {
     const xml = this.generateBatchUseCase.execute(generateBatchDto);
     return xml;
   }
+  cancelInvoice(cancelInvocieDto) {
+    const xml = this.cancelDocumentUseCase.execute(cancelInvocieDto);
+    return xml;
+  }
 };
 
 exports.SifenService = SifenService;