consultame-sdk 1.1.2 → 1.2.0

package/README.md

@@ -5,7 +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),
+**construir los sobres XML** (consulta de RUC, consulta de lote, consulta de documento y
+evento de nominació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.
@@ -25,6 +26,7 @@ Con esa salida, la aplicación consumidora envía los mensajes por su cuenta.
   - [`generateQr`](#generateqrgenerationqrdto)
   - [`generateDocument`](#generatedocumentgeneratedocumentoelectronicodto)
   - [`signedXml`](#signedxmlxml-tag-responsedigitalsign)
+  - [`nominationInvoice`](#nominationinvoicenominationinvoicedto)
 - [DTOs (contratos de entrada)](#dtos-contratos-de-entrada)
 - [Funciones utilitarias internas](#funciones-utilitarias-internas)
 - [Arquitectura del proyecto](#arquitectura-del-proyecto)
@@ -69,7 +71,7 @@ Todo el punto de entrada público es la clase **`SifenService`**. Se instancia s
 argumentos y ya arma internamente sus casos de uso y dependencias.
 
 ```ts
-import { SifenService } from "consultame-skd";
+import { SifenService } from "consultame-sdk";
 
 const sifen = new SifenService();
 
@@ -170,6 +172,21 @@ const xmlConQr = await sifen.generateQr({
   idCsc: "0001",
   ambiente: "test", // "test" | "produccion"
 });
+
+// 8) Nominar un documento ya emitido a un receptor (evento de nominación, sin firmar)
+const xmlNominacion = sifen.nominationInvoice({
+  id: 4,
+  cdc: "01800123456001001000000012023052212345678901",
+  motivo: "Nominación solicitada por el cliente",
+  idTipoReceptor: 1, // 1 = contribuyente
+  idTipoOperacion: 1, // 1 = B2B
+  idPais: "PRY",
+  esContribuyente: true,
+  idTipoContribuyente: 2,
+  ruc: "80099999",
+  digitoVerificado: "1",
+  razonSocial: "Cliente Ejemplo S.R.L.",
+});
 ```
 
 ---
@@ -342,7 +359,7 @@ Toma un documento electrónico (`rDE`) **ya firmado digitalmente**, calcula el e
 código QR exigido por SIFEN y devuelve el **mismo XML con el nodo `<gCamFuFD><dCarQR>`
 incrustado**.
 
-> ⚠️ Este es el único método **asíncrono** de la librería: devuelve `Promise<string>`.
+> ⚠️ Método **asíncrono**: devuelve `Promise<string>`.
 
 | Parámetro  | Tipo     | Descripción                                                            |
 | ---------- | -------- | ---------------------------------------------------------------------- |
@@ -634,6 +651,131 @@ try {
 
 ---
 
+### `nominationInvoice(nominationInvoiceDto)`
+
+Genera el sobre SOAP `rEnviEventoDe` con el **evento de nominación** (`rGEveNom`): asocia los
+datos de un receptor a 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.
+
+Método **síncrono** que valida el DTO antes de armar el XML.
+
+| Parámetro             | Tipo                | Descripción                                                                                   |
+| --------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
+| `id`                  | `number`            | Identificador de la petición (`dId`); también se usa como `Id` del evento (`rEve`).           |
+| `cdc`                 | `string`            | CDC de 44 dígitos del documento a nominar (`Id` de `rGEveNom`).                               |
+| `motivo`              | `string`            | Motivo del evento (`mOtEve`), de 5 a 500 caracteres.                                          |
+| `idTipoReceptor`      | `number`            | `1` = contribuyente, `2` = no contribuyente (`iNatRec`).                                      |
+| `idTipoOperacion`     | `number`            | `1` = B2B, `2` = B2C, `4` = B2F (`iTiOpe`).                                                   |
+| `idPais`              | `string`            | Código de país del receptor (ej. `"PRY"`); debe existir en `PAISES`.                          |
+| `esContribuyente`     | `boolean`           | Si el receptor es contribuyente.                                                              |
+| `razonSocial`         | `string`            | Nombre o razón social del receptor (`dNomRec`), de 4 a 255 caracteres.                        |
+| `idTipoContribuyente` | `number?`           | `1` = persona física, `2` = persona jurídica. Obligatorio si `esContribuyente`.               |
+| `ruc`                 | `string?`           | RUC del receptor. Obligatorio si `esContribuyente`.                                           |
+| `digitoVerificado`    | `string \| number?` | Dígito verificador del RUC. Obligatorio si `esContribuyente`.                                 |
+| `idTipoDocumento`     | `number?`           | Tipo de documento de identidad. Obligatorio si **no** es contribuyente.                       |
+| `numeroDocumento`     | `string?`           | Número de documento. Obligatorio si **no** es contribuyente.                                  |
+| `otroTipoDocumento`   | `string?`           | Descripción del tipo de documento cuando `idTipoDocumento = 9` (Otro).                        |
+| `nombreFantasia`      | `string?`           | Nombre de fantasía del receptor.                                                              |
+| `direccion`           | `string?`           | Dirección del receptor. Obligatoria si `idTipoOperacion = 4` (B2F).                           |
+| `numeroCasa`          | `string?`           | Obligatorio si se informa `direccion`.                                                        |
+| `idDepartamento`, `idDistricto`, `idCiudad` | `number?` | Ubicación del receptor. **Se ignoran en B2F.**                                |
+| `telefono`, `celular`, `email`, `codigoCliente` | `string?` | Datos de contacto opcionales.                                           |
+
+> El campo se llama `idDistricto` (con esa grafía) en el DTO.
+
+**Retorna:** `string` — XML SOAP normalizado (una sola línea), con `dFecFirma` tomado de la
+fecha/hora actual y `dVerFor` = `150`.
+
+```ts
+const xml = sifen.nominationInvoice({
+  id: 4,
+  cdc: "01800123456001001000000012023052212345678901",
+  motivo: "Nominación solicitada por el cliente",
+  idTipoReceptor: 1,
+  idTipoOperacion: 1,
+  idPais: "PRY",
+  esContribuyente: true,
+  idTipoContribuyente: 2,
+  ruc: "80099999",
+  digitoVerificado: "1",
+  razonSocial: "Cliente Ejemplo S.R.L.",
+});
+```
+
+<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>4</dId>
+      <dEvReg>
+        <gGroupGesEve xmlns="http://ekuatia.set.gov.py/sifen/xsd"
+                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                      xsi:schemaLocation="http://ekuatia.set.gov.py/sifen/xsd siRecepEvento_v150.xsd">
+          <rGesEve xsi:schemaLocation="http://ekuatia.set.gov.py/sifen/xsd siRecepEvento_v150.xsd">
+            <rEve Id="4">
+              <dFecFirma>2026-10-14T16:43:03</dFecFirma>
+              <dVerFor>150</dVerFor>
+              <gGroupTiEvt>
+                <rGEveNom>
+                  <Id>01800123456001001000000012023052212345678901</Id>
+                  <mOtEve>Nominación solicitada por el cliente</mOtEve>
+                  <iNatRec>1</iNatRec>
+                  <iTiOpe>1</iTiOpe>
+                  <cPaisRec>PRY</cPaisRec>
+                  <dDesPaisRe>Paraguay</dDesPaisRe>
+                  <iTiContRec>2</iTiContRec>
+                  <dRucRec>80099999</dRucRec>
+                  <dDVRec>1</dDVRec>
+                  <dNomRec>Cliente Ejemplo S.R.L.</dNomRec>
+                </rGEveNom>
+              </gGroupTiEvt>
+            </rEve>
+          </rGesEve>
+        </gGroupGesEve>
+      </dEvReg>
+    </rEnviEventoDe>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+#### Reglas de validación
+
+Antes de armar el XML se valida el DTO y se lanza un `Error` con un mensaje descriptivo si
+algo no cumple:
+
+- `cdc` debe tener exactamente 44 dígitos.
+- `motivo` de 5 a 500 caracteres y `razonSocial` de 4 a 255 (ambos sin contar espacios en los extremos).
+- `idTipoReceptor` debe ser coherente con `esContribuyente` (`1` ⇔ contribuyente).
+- `idTipoOperacion` debe ser `1`, `2` o `4`; B2B (`1`) exige receptor contribuyente, y B2C (`2`) /
+  B2F (`4`) exigen no contribuyente.
+- `idPais` debe ser `"PRY"`, salvo en B2F (`4`), donde debe ser **distinto** de `"PRY"`.
+- Contribuyente: `idTipoContribuyente`, `ruc` y `digitoVerificado` son obligatorios.
+- No contribuyente: `idTipoDocumento` y `numeroDocumento` son obligatorios.
+- B2F: `direccion` es obligatoria; y si se informa `direccion`, también `numeroCasa`.
+
+También lanza error si algún código (`idPais`, `idTipoDocumento`, `idDepartamento`, `idDistricto`,
+`idCiudad`) no existe en los catálogos de
+[`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts).
+
+```ts
+try {
+  const xml = sifen.nominationInvoice({ ... });
+} catch (error) {
+  // DTO inválido (ver reglas de validación) o código inexistente en el diccionario
+}
+```
+
+---
+
 ## DTOs (contratos de entrada)
 
 Todos los DTOs de consulta extienden `GenerateIdDto`, que aporta el campo `id`.
@@ -666,6 +808,18 @@ interface GenerationQrDto {
   idCsc: string; // Identificador del CSC
   ambiente: string; // "test" | "produccion"
 }
+
+// Campos completos y reglas en la sección `nominationInvoice`
+interface NominationInvoiceDto extends GenerateIdDto {
+  cdc: string;
+  motivo: string;
+  idTipoReceptor: number;
+  idTipoOperacion: number;
+  idPais: string;
+  esContribuyente: boolean;
+  razonSocial: string;
+  // ...y los campos opcionales del receptor (ruc, direccion, idDistricto, email, etc.)
+}
 ```
 
 Enums disponibles en [`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts):
@@ -725,6 +879,8 @@ No forman parte de la API pública, pero es útil conocerlas:
 | `generateConsultRucXml`      | Arma el string XML de consulta de RUC.                                                        |
 | `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).                |
 | `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)_ |
@@ -787,6 +943,11 @@ mantener estado intermedio (`jsonFactura`) mientras se arma cada sección del XM
 `SifenRepository` → `SifenPersistence.signedXml`), delegando en la función utilitaria `signXml`
 (`src/shared/functions/functions.utils.ts`), que envuelve `xml-crypto`.
 
+`nominationInvoice` también sigue el mismo flujo (`SifenService.nominationInvoice` →
+`NominationInvoiceUseCase` → `SifenRepository` → `SifenPersistence.nominationInvoice`),
+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).
+
 **Por qué esta separación:**
 
 - **`domain`** no depende de nada externo: define _qué_ se hace (casos de uso) y el
@@ -830,6 +991,7 @@ consultame-sdk/
 │       │   │   ├── consultBatch.dto.ts
 │       │   │   ├── digitalSign.dto.ts
 │       │   │   ├── generationQr.dto.ts
+│       │   │   ├── nominationInvoice.dto.ts
 │       │   │   ├── cancelDocument.dto.ts
 │       │   │   └── invalidationInvoice.dto.ts
 │       │   └── services/
@@ -846,6 +1008,7 @@ consultame-sdk/
 │       │       ├── obtainDigitalSign.useCase.ts
 │       │       ├── generateQr.useCase.ts
 │       │       ├── generateDocument.useCase.ts
+│       │       ├── nominationInvoice.useCase.ts
 │       │       └── signedXml.useCase.ts
 │       │
 │       └── infrastructure/               # Detalles concretos (ADAPTADORES)
@@ -886,6 +1049,7 @@ Funcionalidades **implementadas**:
 - ✅ Generación del XML completo del Documento Electrónico — Factura, Autofactura, Nota de
   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`)
 
 Definidas pero **pendientes de implementación** (hoy lanzan `Method not implemented`
 o aún no están expuestas en `SifenService`):
@@ -897,5 +1061,5 @@ o aún no están expuestas en `SifenService`):
 
 > **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. `generateQr` **requiere** que el XML ya venga firmado (con `signedXml` o por
+> consumidora. El evento que devuelve `nominationInvoice` tampoco viene firmado. `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

@@ -120,6 +120,18 @@ var SignedXmlUseCase = class {
   }
 };
 
+// src/sifen/domain/useCases/nominationInvoice.useCase.ts
+var NominationInvoiceUseCase = class {
+  constructor(sifenRepository) {
+    this.sifenRepository = sifenRepository;
+  }
+  sifenRepository;
+  execute(nominationInvoiceDto) {
+    const xml = this.sifenRepository.nominationInvoice(nominationInvoiceDto);
+    return xml;
+  }
+};
+
 // src/shared/utils/dictionary.utils.ts
 var TIPOS_DOCUMENTOS = [
   {
@@ -8157,6 +8169,139 @@ var generateConsultBatchXml = (consultBatchDto) => {
             </env:Envelope>
 `;
 };
+var validateNominationInvoice = (dto) => {
+  if (!/^\d{44}$/.test(dto.cdc)) {
+    throw new Error("El CDC debe tener 44 d\xEDgitos");
+  }
+  if (dto.motivo.trim().length < 5 || dto.motivo.trim().length > 500) {
+    throw new Error("El motivo debe tener entre 5 y 500 caracteres");
+  }
+  if (dto.razonSocial.trim().length < 4 || dto.razonSocial.trim().length > 255) {
+    throw new Error("La raz\xF3n social debe tener entre 4 y 255 caracteres");
+  }
+  if (dto.esContribuyente !== (dto.idTipoReceptor === 1)) {
+    throw new Error(
+      "idTipoReceptor (1 = contribuyente, 2 = no contribuyente) no coincide con esContribuyente"
+    );
+  }
+  if (![1, 2, 4].includes(dto.idTipoOperacion)) {
+    throw new Error("idTipoOperacion debe ser 1 (B2B), 2 (B2C) o 4 (B2F)");
+  }
+  if (dto.esContribuyente !== (dto.idTipoOperacion === 1)) {
+    throw new Error(
+      "B2B exige receptor contribuyente; B2C y B2F exigen no contribuyente"
+    );
+  }
+  if (dto.idTipoOperacion === 4 === (dto.idPais === "PRY")) {
+    throw new Error(
+      "idPais debe ser PRY, salvo en B2F donde debe ser distinto de PRY"
+    );
+  }
+  if (dto.esContribuyente) {
+    if (!dto.idTipoContribuyente || !dto.ruc || dto.digitoVerificado === void 0) {
+      throw new Error(
+        "Receptor contribuyente: idTipoContribuyente, ruc y digitoVerificado son obligatorios"
+      );
+    }
+  } else if (!dto.idTipoDocumento || !dto.numeroDocumento) {
+    throw new Error(
+      "Receptor no contribuyente: idTipoDocumento y numeroDocumento son obligatorios"
+    );
+  }
+  if (dto.idTipoOperacion === 4 && !dto.direccion) {
+    throw new Error("B2F: la direcci\xF3n del receptor es obligatoria");
+  }
+  if (dto.direccion && !dto.numeroCasa) {
+    throw new Error("numeroCasa es obligatorio si se informa la direcci\xF3n");
+  }
+};
+var generateNominationInvoiceXml = (dto) => {
+  validateNominationInvoice(dto);
+  const pais = PAISES.find((item) => item.codigo === dto.idPais).descripcion;
+  const rGEveNom = {
+    Id: dto.cdc,
+    mOtEve: dto.motivo.trim(),
+    iNatRec: dto.idTipoReceptor,
+    iTiOpe: dto.idTipoOperacion,
+    cPaisRec: dto.idPais,
+    dDesPaisRe: pais
+  };
+  if (dto.esContribuyente) {
+    rGEveNom.iTiContRec = dto.idTipoContribuyente;
+    rGEveNom.dRucRec = dto.ruc;
+    rGEveNom.dDVRec = dto.digitoVerificado;
+  } else {
+    rGEveNom.iTipIDRec = dto.idTipoDocumento;
+    rGEveNom.dDTipIDRec = dto.idTipoDocumento === 9 && dto.otroTipoDocumento ? dto.otroTipoDocumento : TIPOS_DOCUMENTOS.find((item) => item.codigo === dto.idTipoDocumento).descripcion;
+    rGEveNom.dNumIDRec = dto.numeroDocumento.trim();
+  }
+  rGEveNom.dNomRec = dto.razonSocial.trim();
+  if (dto.nombreFantasia) rGEveNom.dNomFanRec = dto.nombreFantasia.trim();
+  if (dto.direccion) {
+    rGEveNom.dDirRec = dto.direccion.trim();
+    rGEveNom.dNumCasRec = dto.numeroCasa.trim();
+  }
+  if (dto.idTipoOperacion !== 4) {
+    if (dto.idDepartamento) {
+      rGEveNom.cDepRec = dto.idDepartamento;
+      rGEveNom.dDesDepRec = DEPARTAMENTOS.find(
+        (item) => item.codigo === dto.idDepartamento
+      ).descripcion;
+    }
+    if (dto.idDistricto) {
+      rGEveNom.cDisRec = dto.idDistricto;
+      rGEveNom.dDesDisRec = DISTRICTOS.find(
+        (item) => item.codigo === dto.idDistricto
+      ).descripcion;
+    }
+    if (dto.idCiudad) {
+      rGEveNom.cCiuRec = dto.idCiudad;
+      rGEveNom.dDesCiuRec = CIUDADES.find(
+        (item) => item.codigo === dto.idCiudad
+      ).descripcion;
+    }
+  }
+  if (dto.telefono) rGEveNom.dTelRec = dto.telefono.trim();
+  if (dto.celular) rGEveNom.dCelRec = dto.celular.trim();
+  if (dto.email) rGEveNom.dEmailRec = dto.email.trim();
+  if (dto.codigoCliente) rGEveNom.dCodCliente = dto.codigoCliente.trim();
+  const xsd = "http://ekuatia.set.gov.py/sifen/xsd";
+  const schemaLocation = `${xsd} siRecepEvento_v150.xsd`;
+  const envelope = {
+    "env:Envelope": {
+      $: { "xmlns:env": "http://www.w3.org/2003/05/soap-envelope" },
+      "env:Header": {},
+      "env:Body": {
+        rEnviEventoDe: {
+          $: { xmlns: xsd },
+          dId: dto.id,
+          dEvReg: {
+            gGroupGesEve: {
+              $: {
+                xmlns: xsd,
+                "xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
+                "xsi:schemaLocation": schemaLocation
+              },
+              rGesEve: {
+                $: { "xsi:schemaLocation": schemaLocation },
+                rEve: {
+                  $: { Id: dto.id },
+                  dFecFirma: convertToFormatDateSET(/* @__PURE__ */ new Date()),
+                  dVerFor: 150,
+                  gGroupTiEvt: { rGEveNom }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  };
+  const builder = new xml2js__namespace.Builder({
+    xmldec: { version: "1.0", encoding: "UTF-8", standalone: false }
+  });
+  return normalizeXML(builder.buildObject(envelope));
+};
 var OIDS_KEYS = [forge__default.default.pki.oids.pkcs8ShroudedKeyBag, forge__default.default.pki.oids.keyBag];
 var obtainBags = (almacen) => almacen.safeContents.flatMap((contenido) => contenido.safeBags);
 var readDigitalSign = (digitalSignDto) => {
@@ -9976,6 +10121,14 @@ var SifenPersistence = class {
       throw error;
     }
   }
+  nominationInvoice(nominationInvoiceDto) {
+    try {
+      return generateNominationInvoiceXml(nominationInvoiceDto);
+    } catch (error) {
+      console.log(error);
+      throw error;
+    }
+  }
   obtainDigitalSign(digitalSignDto) {
     try {
       const digitalSign = readDigitalSign(digitalSignDto);
@@ -10026,6 +10179,7 @@ var SifenService = class {
   generateQrUseCase;
   generateDocumentUseCase;
   signedXmlUseCase;
+  nominationInvoiceUseCase;
   sifenRepository;
   constructor() {
     this.sifenRepository = new SifenPersistence();
@@ -10042,6 +10196,9 @@ var SifenService = class {
     );
     this.signedXmlUseCase = new SignedXmlUseCase(this.sifenRepository);
     this.generateQrUseCase = new GenerateQrUseCase(this.sifenRepository);
+    this.nominationInvoiceUseCase = new NominationInvoiceUseCase(
+      this.sifenRepository
+    );
   }
   consultRuc(consultRucDto) {
     const ruc = this.consultRucUseCase.execute(consultRucDto);
@@ -10055,6 +10212,10 @@ var SifenService = class {
     const invoice = this.consultDocumentUseCase.execute(consultDocumentDto);
     return invoice;
   }
+  nominationInvoice(nominationInvoiceDto) {
+    const xml = this.nominationInvoiceUseCase.execute(nominationInvoiceDto);
+    return xml;
+  }
   obtainDigitalSign(digitalSignDto) {
     const digitalSign = this.obtainDigitalSignUseCase.execute(digitalSignDto);
     return digitalSign;