consultame-sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,585 +1,901 @@
-# consultame-sdk
-
-Librería en **TypeScript** para generar los mensajes XML (SOAP) e insumos criptográficos
-que se necesitan para interactuar con **SIFEN** (Sistema Integrado de Facturación Electrónica
-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),
-**extraer el certificado y la llave privada** desde un archivo de firma digital `.p12`/`.pfx`
-y **generar el código QR** que se incrusta en el documento electrónico firmado.
-Con esa salida, la aplicación consumidora firma y envía los mensajes por su cuenta.
-
----
-
-## Tabla de contenido
-
-- [Instalación](#instalación)
-- [Uso rápido](#uso-rápido)
-- [API pública](#api-pública)
-  - [`consultRuc`](#consultrucconsultrucdto)
-  - [`consultDocument`](#consultdocumentconsultdocumentdto)
-  - [`consultBatch`](#consultbatchconsultbatchdto)
-  - [`obtainDigitalSign`](#obtaindigitalsigndigitalsigndto)
-  - [`generateQr`](#generateqrgenerationqrdto)
-- [DTOs (contratos de entrada)](#dtos-contratos-de-entrada)
-- [Funciones utilitarias internas](#funciones-utilitarias-internas)
-- [Arquitectura del proyecto](#arquitectura-del-proyecto)
-- [Estructura de carpetas](#estructura-de-carpetas)
-- [Scripts de desarrollo](#scripts-de-desarrollo)
-- [Estado / roadmap](#estado--roadmap)
-
----
-
-## Instalación
-
-```bash
-pnpm add consultame-sdk
-# o
-npm install consultame-sdk
-```
-
-Dependencias en tiempo de ejecución:
-
-| Paquete                                                  | Para qué se usa                                              |
-| -------------------------------------------------------- | ------------------------------------------------------------ |
-| [`node-forge`](https://www.npmjs.com/package/node-forge) | Leer los certificados `.p12`/`.pfx` y exportarlos a PEM.     |
-| [`xml2js`](https://www.npmjs.com/package/xml2js)         | Parsear y reconstruir el XML del documento al generar el QR. |
-| [`crypto-js`](https://www.npmjs.com/package/crypto-js)   | Calcular el hash SHA-256 (`cHashQR`) del código QR.          |
-
-La librería se publica en formato dual **CommonJS + ESM** con tipos incluidos:
-
-```ts
-// ESM
-import { SifenService } from "consultame-sdk";
-
-// CommonJS
-const { SifenService } = require("consultame-sdk");
-```
-
----
-
-## Uso rápido
-
-Todo el punto de entrada público es la clase **`SifenService`**. Se instancia sin
-argumentos y ya arma internamente sus casos de uso y dependencias.
-
-```ts
-import { SifenService } from "consultame-skd";
-
-const sifen = new SifenService();
-
-// 1) Consultar un RUC → devuelve el XML SOAP listo, normalizado en una sola línea
-const xmlRuc = sifen.consultRuc({
-  id: 1,
-  ruc: "80012345-6",
-});
-
-// 2) Consultar un documento electrónico por su CDC
-const xmlDocumento = sifen.consultDocument({
-  id: 2,
-  cdc: "01800123456001001000000012023052212345678901",
-});
-
-// 3) Consultar el estado de un lote enviado
-const xmlLote = sifen.consultBatch({
-  id: 3,
-  codigoLote: "1234567890",
-});
-
-// 4) Extraer certificado + llave privada desde la firma digital (.p12)
-const firma = sifen.obtainDigitalSign({
-  camino: "./certificados/firma.p12",
-  contraseña: "mi-clave-secreta",
-});
-
-console.log(firma.certificado); // PEM del certificado
-console.log(firma.llavePrivada); // PEM de la llave privada
-
-// 5) Generar el QR e incrustarlo en un documento electrónico ya firmado (asíncrono)
-const xmlConQr = await sifen.generateQr({
-  xml: xmlFirmado, // XML del rDE ya firmado digitalmente
-  csc: "ABCD0000000000000000000000000000",
-  idCsc: "0001",
-  ambiente: "test", // "test" | "produccion"
-});
-```
-
----
-
-## API pública
-
-Todos los métodos viven en la clase `SifenService`. Son **síncronos**, salvo
-[`generateQr`](#generateqrgenerationqrdto), que es **asíncrono** y devuelve una `Promise`.
-
-### `consultRuc(consultRucDto)`
-
-Genera el sobre SOAP `rEnviConsRUC` para consultar los datos de un contribuyente por RUC.
-
-| Parámetro | Tipo     | Descripción                           |
-| --------- | -------- | ------------------------------------- |
-| `id`      | `number` | Identificador de la petición (`dId`). |
-| `ruc`     | `string` | RUC del contribuyente a consultar.    |
-
-**Retorna:** `string` — XML SOAP normalizado (sin saltos de línea ni tabulaciones).
-
-```ts
-const xml = sifen.consultRuc({ id: 1, ruc: "80012345-6" });
-```
-
-<details>
-<summary>Ejemplo de salida (formateada para lectura)</summary>
-
-```xml
-<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
-  <env:Header/>
-  <env:Body>
-    <rEnviConsRUC xmlns="http://ekuatia.set.gov.py/sifen/xsd">
-      <dId>1</dId>
-      <dRUCCons>80012345-6</dRUCCons>
-    </rEnviConsRUC>
-  </env:Body>
-</env:Envelope>
-```
-
-</details>
-
----
-
-### `consultDocument(consultDocumentDto)`
-
-Genera el sobre SOAP `rEnviConsDeRequest` para consultar un documento electrónico
-(factura, nota, etc.) mediante su **CDC** (Código de Control).
-
-| Parámetro | Tipo     | Descripción                           |
-| --------- | -------- | ------------------------------------- |
-| `id`      | `number` | Identificador de la petición (`dId`). |
-| `cdc`     | `string` | CDC de 44 dígitos del documento.      |
-
-**Retorna:** `string` — XML SOAP normalizado.
-
-```ts
-const xml = sifen.consultDocument({
-  id: 2,
-  cdc: "01800123456001001000000012023052212345678901",
-});
-```
-
-<details>
-<summary>Ejemplo de salida (formateada para lectura)</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>
-    <rEnviConsDeRequest xmlns="http://ekuatia.set.gov.py/sifen/xsd">
-      <dId>2</dId>
-      <dCDC>01800123456001001000000012023052212345678901</dCDC>
-    </rEnviConsDeRequest>
-  </env:Body>
-</env:Envelope>
-```
-
-</details>
-
----
-
-### `consultBatch(consultBatchDto)`
-
-Genera el sobre SOAP `rEnviConsLoteDe` para consultar el estado de un **lote**
-previamente enviado a SIFEN.
-
-| Parámetro    | Tipo     | Descripción                                     |
-| ------------ | -------- | ----------------------------------------------- |
-| `id`         | `number` | Identificador de la petición (`dId`).           |
-| `codigoLote` | `string` | Número de protocolo del lote (`dProtConsLote`). |
-
-**Retorna:** `string` — XML SOAP normalizado.
-
-```ts
-const xml = sifen.consultBatch({ id: 3, codigoLote: "1234567890" });
-```
-
-<details>
-<summary>Ejemplo de salida (formateada para lectura)</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>
-    <rEnviConsLoteDe xmlns="http://ekuatia.set.gov.py/sifen/xsd">
-      <dId>3</dId>
-      <dProtConsLote>1234567890</dProtConsLote>
-    </rEnviConsLoteDe>
-  </env:Body>
-</env:Envelope>
-```
-
-</details>
-
----
-
-### `obtainDigitalSign(digitalSignDto)`
-
-Lee un archivo de firma digital `.p12`/`.pfx`, valida que contenga llave privada y
-certificado, y los devuelve en formato **PEM**.
-
-| Parámetro    | Tipo     | Descripción                              |
-| ------------ | -------- | ---------------------------------------- |
-| `camino`     | `string` | Ruta al archivo `.p12`/`.pfx`.           |
-| `contraseña` | `string` | Contraseña que protege la firma digital. |
-
-**Retorna:** `ResponseDigitalSign`
-
-```ts
-interface ResponseDigitalSign {
-  certificado: string; // certificado en formato PEM
-  llavePrivada: string; // llave privada en formato PEM
-}
-```
-
-**Errores que puede lanzar:**
-
-- `"La firma digital no contiene una llave privada"` — el `.p12` no tiene llave.
-- `"La firma digital no contiene un certificado"` — el `.p12` no tiene certificado.
-- Errores de `node-forge` si la contraseña es incorrecta o el archivo está corrupto.
-
-```ts
-try {
-  const { certificado, llavePrivada } = sifen.obtainDigitalSign({
-    camino: "./certificados/firma.p12",
-    contraseña: "clave",
-  });
-} catch (error) {
-  // contraseña incorrecta, archivo inválido o sin llave/certificado
-}
-```
-
----
-
-### `generateQr(generationQrDto)`
-
-Toma un documento electrónico (`rDE`) **ya firmado digitalmente**, calcula el enlace del
-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>`.
-
-| Parámetro  | Tipo     | Descripción                                                            |
-| ---------- | -------- | ---------------------------------------------------------------------- |
-| `xml`      | `string` | XML del `rDE` **firmado** (debe contener el nodo `Signature`).         |
-| `csc`      | `string` | Código de Seguridad del Contribuyente (secreto, entregado por la SET). |
-| `idCsc`    | `string` | Identificador del CSC (ej. `"0001"`).                                  |
-| `ambiente` | `string` | `"test"` o `"produccion"`. Define el dominio base del enlace del QR.   |
-
-**Retorna:** `Promise<string>` — el XML reconstruido con el nodo `dCarQR`.
-
-```ts
-const xmlConQr = await sifen.generateQr({
-  xml: xmlFirmado,
-  csc: "ABCD0000000000000000000000000000",
-  idCsc: "0001",
-  ambiente: "test",
-});
-```
-
-#### Cómo se construye el QR
-
-1. Se parsea el XML y se **valida que exista el nodo `Signature`**; si no está, lanza error.
-2. Se elige el dominio base según el ambiente:
-   - `test` → `https://ekuatia.set.gov.py/consultas-test`
-   - `produccion` → `https://ekuatia.set.gov.py/consultas`
-3. Se le concatena `/qr?` y los parámetros extraídos del documento, **en este orden**:
-
-   | Parámetro                 | Origen en el XML                                         | Notas                                           |
-   | ------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
-   | `nVersion`                | `rDE > dVerFor`                                          | Versión del formato.                            |
-   | `Id`                      | `rDE > DE[@Id]`                                          | El CDC del documento.                           |
-   | `dFeEmiDE`                | `rDE > DE > gDatGralOpe > dFeEmiDE`                      | Convertido a **hexadecimal**.                   |
-   | `dRucRec` _o_ `dNumIDRec` | `... > gDatRec`                                          | `dRucRec` si `iNatRec == 1`, si no `dNumIDRec`. |
-   | `dTotGralOpe`             | `rDE > DE > gTotSub > dTotGralOpe`                       | `0` si no existe.                               |
-   | `dTotIVA`                 | `rDE > DE > gTotSub > dTotIVA`                           | `0` si no existe.                               |
-   | `cItems`                  | Cantidad de `gDtipDE > gCamItem`                         | `0` si no hay ítems.                            |
-   | `DigestValue`             | `rDE > Signature > SignedInfo > Reference > DigestValue` | Convertido a **hexadecimal**.                   |
-   | `IdCSC`                   | Parámetro `idCsc`                                        | Último antes del hash.                          |
-   | `cHashQR`                 | `SHA256(cadena_de_parámetros + csc)`                     | Se agrega al final.                             |
-
-4. El enlace resultante se escribe en `rDE > gCamFuFD > dCarQR` y se reconstruye el XML.
-
-<details>
-<summary>Ejemplo del enlace generado dentro de <code>dCarQR</code></summary>
-
-```
-https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&Id=01800123456001001000000012023052212345678901&dFeEmiDE=323032332d30352d32325431303a30303a3030&dRucRec=80012345&dTotGralOpe=550000&dTotIVA=50000&cItems=3&DigestValue=6a4b2c...&IdCSC=0001&cHashQR=9f2a7c1e4b8d...
-```
-
-Y así queda incrustado en el XML de salida:
-
-```xml
-<rDE>
-  <dVerFor>150</dVerFor>
-  <DE Id="01800123456001001000000012023052212345678901">
-    ...
-  </DE>
-  <Signature>...</Signature>
-  <gCamFuFD>
-    <dCarQR>https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&amp;Id=...&amp;cHashQR=...</dCarQR>
-  </gCamFuFD>
-</rDE>
-```
-
-</details>
-
-**Errores que puede lanzar:**
-
-- `"XML debe estar firmado digitalmente para generar el QR"` — el XML no tiene nodo `Signature`.
-- Errores de parseo de `xml2js` si el XML está malformado.
-- `TypeError` si el documento no respeta la estructura esperada del `rDE` (por ejemplo,
-  falta `gDatRec` o `gDtipDE`).
-
-```ts
-try {
-  const xmlConQr = await sifen.generateQr({
-    xml: xmlFirmado,
-    csc: process.env.SIFEN_CSC!,
-    idCsc: "0001",
-    ambiente: "produccion",
-  });
-} catch (error) {
-  // XML sin firmar, malformado o con estructura inesperada
-}
-```
-
-> **Nota sobre el `ambiente`:** internamente se compara contra el enum `SIFEN_ENVIRONMENT`
-> (`"test"` / `"produccion"`). Cualquier valor distinto de `"test"` cae en el enlace de
-> **producción**, así que conviene pasar el valor exacto.
-
----
-
-## DTOs (contratos de entrada)
-
-Todos los DTOs de consulta extienden `GenerateIdDto`, que aporta el campo `id`.
-
-```ts
-interface GenerateIdDto {
-  id: number;
-}
-
-interface ConsultRucDto extends GenerateIdDto {
-  ruc: string;
-}
-
-interface ConsultDocumentDto extends GenerateIdDto {
-  cdc: string;
-}
-
-interface ConsultBatchDto extends GenerateIdDto {
-  codigoLote: string;
-}
-
-interface DigitalSignDto {
-  camino: string; // ruta al .p12
-  contraseña: string; // clave del .p12
-}
-
-interface GenerationQrDto {
-  xml: string; // XML del rDE ya firmado
-  csc: string; // Código de Seguridad del Contribuyente
-  idCsc: string; // Identificador del CSC
-  ambiente: string; // "test" | "produccion"
-}
-```
-
-Enums disponibles en [`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts):
-
-```ts
-enum SIFEN_ENVIRONMENT {
-  TEST = "test",
-  PRODUCCION = "produccion",
-}
-
-enum LINK_SIFEN {
-  TEST = "https://ekuatia.set.gov.py/consultas-test",
-  PRODUCCION = "https://ekuatia.set.gov.py/consultas",
-}
-```
-
-DTOs ya definidos pero **aún sin implementación** en la persistencia (ver
-[roadmap](#estado--roadmap)):
-
-```ts
-interface CancelInvoiceDto extends GenerateIdDto {
-  cdc: string;
-  motivo: string;
-}
-
-interface InvalidationInvoiceDto extends GenerateIdDto {
-  timbrado: string;
-  establecimiento: number;
-  puntoExpedicion: number;
-  desde: number;
-  hasta: number;
-  tipoDocumento: number;
-  motivo: string;
-}
-```
-
----
-
-## Funciones utilitarias internas
-
-Viven en [`src/shared/functions/functions.utils.ts`](src/shared/functions/functions.utils.ts).
-No forman parte de la API pública, pero es útil conocerlas:
-
-| Función                      | Qué hace                                                                                      |
-| ---------------------------- | --------------------------------------------------------------------------------------------- |
-| `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.                                                       |
-| `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.                   |
-| `generateQr`                 | Arma el enlace del QR (params + hash SHA-256) y lo incrusta en `gCamFuFD > dCarQR`. _(async)_ |
-| `calculateDigitVerification` | Calcula el dígito verificador (DV) de una cédula/RUC según el algoritmo módulo 11.            |
-
----
-
-## Arquitectura del proyecto
-
-El proyecto sigue una **arquitectura hexagonal (puertos y adaptadores)** combinada con
-principios de **Clean Architecture**, organizada por el módulo de negocio `sifen`.
-
-```
-             ┌──────────────────────────────────────────────┐
-             │                 applications                 │
-             │   SifenService  (punto de entrada / fachada)  │
-             │   DTOs (contratos de entrada)                 │
-             └───────────────────────┬──────────────────────┘
-                                     │ orquesta
-                                     ▼
-             ┌──────────────────────────────────────────────┐
-             │                    domain                     │
-             │   useCases  (ConsultRuc, ConsultBatch, ...)   │
-             │   repository (SifenRepository = PUERTO)        │
-             └───────────────────────┬──────────────────────┘
-                                     │ implementado por
-                                     ▼
-             ┌──────────────────────────────────────────────┐
-             │                infrastructure                 │
-             │   SifenPersistence (ADAPTADOR del puerto)      │
-             │   → usa funciones utilitarias (XML, forge)     │
-             └──────────────────────────────────────────────┘
-```
-
-**Flujo de una llamada** (ej. `consultRuc`):
-
-1. La app llama a `SifenService.consultRuc(dto)` — capa **applications**.
-2. El servicio delega en `ConsultRucUseCase.execute(dto)` — capa **domain**.
-3. El caso de uso invoca la interfaz `SifenRepository` (**puerto**), sin conocer la implementación.
-4. En runtime el puerto lo resuelve `SifenPersistence` (**adaptador**) — capa **infrastructure**.
-5. La persistencia usa las funciones utilitarias para generar y normalizar el XML.
-
-**Por qué esta separación:**
-
-- **`domain`** no depende de nada externo: define _qué_ se hace (casos de uso) y el
-  contrato `SifenRepository`. Es el núcleo estable.
-- **`infrastructure`** contiene los detalles concretos (armado de XML, `node-forge`, `fs`).
-  Se puede reemplazar sin tocar el dominio.
-- **`applications`** expone la fachada y los DTOs que consume el mundo exterior.
-- **`shared`** agrupa utilidades y DTOs de respuesta transversales a los módulos.
-
-La inversión de dependencias es clave: `SifenPersistence implements SifenRepository`, de
-modo que el dominio depende de la **abstracción**, no de la implementación.
-
----
-
-## Estructura de carpetas
-
-```
-consultame-sdk/
-├── src/
-│   ├── index.ts                          # Punto de entrada público → exporta SifenService
-│   │
-│   ├── shared/                           # Código transversal
-│   │   ├── dto/
-│   │   │   └── responseDigitalSign.dto.ts # ResponseDigitalSign { certificado, llavePrivada }
-│   │   ├── functions/
-│   │   │   └── functions.utils.ts        # XML, normalizeXML, readDigitalSign, generateQr, DV
-│   │   └── utils/
-│   │       └── dictionary.utils.ts       # Enums SIFEN_ENVIRONMENT y LINK_SIFEN
-│   │
-│   └── sifen/                            # Módulo de negocio SIFEN
-│       ├── applications/                 # Capa de aplicación (fachada + contratos)
-│       │   ├── dtos/
-│       │   │   ├── index.ts              # Barrel de DTOs
-│       │   │   ├── generateId.dto.ts     # GenerateIdDto (base)
-│       │   │   ├── consultRuc.dto.ts
-│       │   │   ├── consultDocument.dto.ts
-│       │   │   ├── consultBatch.dto.ts
-│       │   │   ├── digitalSign.dto.ts
-│       │   │   ├── generationQr.dto.ts
-│       │   │   ├── cancelDocument.dto.ts
-│       │   │   └── invalidationInvoice.dto.ts
-│       │   └── services/
-│       │       └── sifen.service.ts      # SifenService (fachada pública)
-│       │
-│       ├── domain/                       # Núcleo de negocio
-│       │   ├── repository/
-│       │   │   └── sifen.repository.ts   # SifenRepository (PUERTO / interfaz)
-│       │   └── useCases/
-│       │       ├── index.ts              # Barrel de casos de uso
-│       │       ├── consultRuc.useCase.ts
-│       │       ├── consultDocument.useCase.ts
-│       │       ├── consultBatch.useCase.ts
-│       │       ├── obtainDigitalSign.useCase.ts
-│       │       └── generateQr.useCase.ts
-│       │
-│       └── infrastructure/               # Detalles concretos (ADAPTADORES)
-│           └── persistence/
-│               └── sifen.persistence.ts  # SifenPersistence implements SifenRepository
-│
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts                        # Build dual CJS + ESM (target node22)
-├── pnpm-workspace.yaml
-└── README.md
-```
-
----
-
-## Scripts de desarrollo
-
-| Script             | Comando                     | Descripción                                         |
-| ------------------ | --------------------------- | --------------------------------------------------- |
-| `pnpm build`       | `tsup && build:types`       | Compila a `dist/` (CJS + ESM) y genera los `.d.ts`. |
-| `pnpm build:types` | `tsc --emitDeclarationOnly` | Solo emite las declaraciones de tipos.              |
-| `pnpm dev`         | `tsup --watch`              | Build en modo watch.                                |
-| `pnpm typecheck`   | `tsc --noEmit`              | Verifica tipos sin emitir archivos.                 |
-| `pnpm play`        | `tsx src/index.ts`          | Ejecuta `src/index.ts` para pruebas manuales.       |
-| `pnpm play:watch`  | `tsx watch src/index.ts`    | Igual que `play` pero en modo watch.                |
-
----
-
-## Estado / roadmap
-
-Funcionalidades **implementadas**:
-
-- ✅ Consulta de RUC (`consultRuc`)
-- ✅ Consulta de documento por CDC (`consultDocument`)
-- ✅ Consulta de lote (`consultBatch`)
-- ✅ Lectura de firma digital `.p12` → PEM (`obtainDigitalSign`)
-- ✅ Generación e incrustación del código QR (`generateQr`)
-
-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 y el QR) para SIFEN, pero no
-> realiza el envío HTTP ni la firma XMLDSig de los documentos. Esa parte queda a cargo de
-> la aplicación consumidora — de hecho, `generateQr` **requiere** que el XML ya venga
-> firmado, porque toma el `DigestValue` de la firma para calcular el hash del QR.
+# consultame-sdk
+
+Librería en **TypeScript** para generar los mensajes XML (SOAP) e insumos criptográficos
+que se necesitan para interactuar con **SIFEN** (Sistema Integrado de Facturación Electrónica
+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),
+**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.
+Con esa salida, la aplicación consumidora envía los mensajes por su cuenta.
+
+---
+
+## Tabla de contenido
+
+- [Instalación](#instalación)
+- [Uso rápido](#uso-rápido)
+- [API pública](#api-pública)
+  - [`consultRuc`](#consultrucconsultrucdto)
+  - [`consultDocument`](#consultdocumentconsultdocumentdto)
+  - [`consultBatch`](#consultbatchconsultbatchdto)
+  - [`obtainDigitalSign`](#obtaindigitalsigndigitalsigndto)
+  - [`generateQr`](#generateqrgenerationqrdto)
+  - [`generateDocument`](#generatedocumentgeneratedocumentoelectronicodto)
+  - [`signedXml`](#signedxmlxml-tag-responsedigitalsign)
+- [DTOs (contratos de entrada)](#dtos-contratos-de-entrada)
+- [Funciones utilitarias internas](#funciones-utilitarias-internas)
+- [Arquitectura del proyecto](#arquitectura-del-proyecto)
+- [Estructura de carpetas](#estructura-de-carpetas)
+- [Scripts de desarrollo](#scripts-de-desarrollo)
+- [Estado / roadmap](#estado--roadmap)
+
+---
+
+## Instalación
+
+```bash
+pnpm add consultame-sdk
+# o
+npm install consultame-sdk
+```
+
+Dependencias en tiempo de ejecución:
+
+| Paquete                                                  | Para qué se usa                                              |
+| -------------------------------------------------------- | ------------------------------------------------------------ |
+| [`node-forge`](https://www.npmjs.com/package/node-forge) | Leer los certificados `.p12`/`.pfx` y exportarlos a PEM.     |
+| [`xml2js`](https://www.npmjs.com/package/xml2js)         | Parsear el XML firmado al generar el QR.                     |
+| [`xml-crypto`](https://www.npmjs.com/package/xml-crypto) | Firmar digitalmente (XMLDSig) el Documento Electrónico generado. |
+| [`crypto-js`](https://www.npmjs.com/package/crypto-js)   | Calcular el hash SHA-256 (`cHashQR`) del código QR.          |
+
+La librería se publica en formato dual **CommonJS + ESM** con tipos incluidos:
+
+```ts
+// ESM
+import { SifenService } from "consultame-sdk";
+
+// CommonJS
+const { SifenService } = require("consultame-sdk");
+```
+
+---
+
+## Uso rápido
+
+Todo el punto de entrada público es la clase **`SifenService`**. Se instancia sin
+argumentos y ya arma internamente sus casos de uso y dependencias.
+
+```ts
+import { SifenService } from "consultame-skd";
+
+const sifen = new SifenService();
+
+// 1) Consultar un RUC → devuelve el XML SOAP listo, normalizado en una sola línea
+const xmlRuc = sifen.consultRuc({
+  id: 1,
+  ruc: "80012345-6",
+});
+
+// 2) Consultar un documento electrónico por su CDC
+const xmlDocumento = sifen.consultDocument({
+  id: 2,
+  cdc: "01800123456001001000000012023052212345678901",
+});
+
+// 3) Consultar el estado de un lote enviado
+const xmlLote = sifen.consultBatch({
+  id: 3,
+  codigoLote: "1234567890",
+});
+
+// 4) Extraer certificado + llave privada desde la firma digital (.p12)
+const firma = sifen.obtainDigitalSign({
+  camino: "./certificados/firma.p12",
+  contraseña: "mi-clave-secreta",
+});
+
+console.log(firma.certificado); // PEM del certificado
+console.log(firma.llavePrivada); // PEM de la llave privada
+
+// 5) Generar el XML completo de un Documento Electrónico (Factura Electrónica) sin firmar
+const xmlFactura = sifen.generateDocument({
+  emisor: {
+    rucEmisor: "80012345",
+    digitoVerificadorEmisor: "6",
+    idTipoContribuyente: 2,
+    razonSocial: "Consultame S.A.",
+    direccion: "Avda. Mariscal López 1234",
+    idDepartamento: 1,
+    idDistrito: 1,
+    idCiudad: 1,
+    telefono: "021123456",
+  },
+  cliente: {
+    idTipoReceptor: 1,
+    idTipoOperacion: 1,
+    idPais: "PRY",
+    esContribuyente: true,
+    idTipoContribuyente: 2,
+    ruc: "80099999",
+    digitoVerificado: "1",
+    razonSocial: "Cliente Ejemplo S.R.L.",
+    direccion: "Calle Falsa 123",
+  },
+  timbrado: {
+    timbrado: "12558651",
+    establecimiento: 1,
+    puntoExpedicion: 1,
+    numeroDocumento: 1,
+    fechaTimbrado: "2024-01-01",
+  },
+  idTipoEmision: 1,
+  datosOperacion: {
+    idTipoDocumento: 1, // 1 = Factura Electrónica
+    idMoneda: "PYG",
+    idTipoTransaccion: 1,
+    idTipoImpuesto: 1,
+  },
+  fechaEmision: "2024-05-20T10:00:00",
+  datosFactura: {
+    idPresencia: 1,
+    condicion: {
+      idCondicion: 1, // Contado
+      formasPagos: [{ idFormaPago: 1, idMoneda: "PYG", monto: 110000 }],
+    },
+  },
+  detalleFactura: [
+    {
+      codigo: "0001",
+      descripcion: "Servicio de consultoría",
+      idUnidadMedida: 77, // Unidad
+      cantidad: 1,
+      precioUnitario: 110000,
+      idIva: 1, // Gravado IVA
+      ivaBase: 100,
+      tasaIva: 10,
+    },
+  ],
+});
+
+// 6) Firmar digitalmente (XMLDSig) el Documento Electrónico generado (asíncrono)
+const xmlFirmado = await sifen.signedXml(xmlFactura, "DE", firma);
+
+// 7) Generar el QR e incrustarlo en el documento electrónico ya firmado (asíncrono)
+const xmlConQr = await sifen.generateQr({
+  xml: xmlFirmado, // XML del rDE ya firmado digitalmente
+  csc: "ABCD0000000000000000000000000000",
+  idCsc: "0001",
+  ambiente: "test", // "test" | "produccion"
+});
+```
+
+---
+
+## API pública
+
+Todos los métodos viven en la clase `SifenService`. Son **síncronos**, salvo
+[`signedXml`](#signedxmlxml-tag-responsedigitalsign) y
+[`generateQr`](#generateqrgenerationqrdto), que son **asíncronos** y devuelven una `Promise`.
+
+### `consultRuc(consultRucDto)`
+
+Genera el sobre SOAP `rEnviConsRUC` para consultar los datos de un contribuyente por RUC.
+
+| Parámetro | Tipo     | Descripción                           |
+| --------- | -------- | ------------------------------------- |
+| `id`      | `number` | Identificador de la petición (`dId`). |
+| `ruc`     | `string` | RUC del contribuyente a consultar.    |
+
+**Retorna:** `string` — XML SOAP normalizado (sin saltos de línea ni tabulaciones).
+
+```ts
+const xml = sifen.consultRuc({ id: 1, ruc: "80012345-6" });
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</summary>
+
+```xml
+<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+  <env:Header/>
+  <env:Body>
+    <rEnviConsRUC xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>1</dId>
+      <dRUCCons>80012345-6</dRUCCons>
+    </rEnviConsRUC>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `consultDocument(consultDocumentDto)`
+
+Genera el sobre SOAP `rEnviConsDeRequest` para consultar un documento electrónico
+(factura, nota, etc.) mediante su **CDC** (Código de Control).
+
+| Parámetro | Tipo     | Descripción                           |
+| --------- | -------- | ------------------------------------- |
+| `id`      | `number` | Identificador de la petición (`dId`). |
+| `cdc`     | `string` | CDC de 44 dígitos del documento.      |
+
+**Retorna:** `string` — XML SOAP normalizado.
+
+```ts
+const xml = sifen.consultDocument({
+  id: 2,
+  cdc: "01800123456001001000000012023052212345678901",
+});
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</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>
+    <rEnviConsDeRequest xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>2</dId>
+      <dCDC>01800123456001001000000012023052212345678901</dCDC>
+    </rEnviConsDeRequest>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `consultBatch(consultBatchDto)`
+
+Genera el sobre SOAP `rEnviConsLoteDe` para consultar el estado de un **lote**
+previamente enviado a SIFEN.
+
+| Parámetro    | Tipo     | Descripción                                     |
+| ------------ | -------- | ----------------------------------------------- |
+| `id`         | `number` | Identificador de la petición (`dId`).           |
+| `codigoLote` | `string` | Número de protocolo del lote (`dProtConsLote`). |
+
+**Retorna:** `string` — XML SOAP normalizado.
+
+```ts
+const xml = sifen.consultBatch({ id: 3, codigoLote: "1234567890" });
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</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>
+    <rEnviConsLoteDe xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>3</dId>
+      <dProtConsLote>1234567890</dProtConsLote>
+    </rEnviConsLoteDe>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `obtainDigitalSign(digitalSignDto)`
+
+Lee un archivo de firma digital `.p12`/`.pfx`, valida que contenga llave privada y
+certificado, y los devuelve en formato **PEM**.
+
+Un `.p12`/`.pfx` puede traer más de un certificado (por ejemplo la cadena completa emisor +
+intermedia). Cuando hay varios, se selecciona el certificado cuya llave pública corresponde
+efectivamente a la llave privada firmante (comparando el módulo RSA), no simplemente el
+primero encontrado — usar el certificado equivocado en el `KeyInfo` hace que SIFEN rechace el
+documento firmado con *"Valor de la firma (SignatureValue) diferente del calculado por el
+PKI"*.
+
+| Parámetro    | Tipo     | Descripción                              |
+| ------------ | -------- | ---------------------------------------- |
+| `camino`     | `string` | Ruta al archivo `.p12`/`.pfx`.           |
+| `contraseña` | `string` | Contraseña que protege la firma digital. |
+
+**Retorna:** `ResponseDigitalSign`
+
+```ts
+interface ResponseDigitalSign {
+  certificado: string; // certificado en formato PEM
+  llavePrivada: string; // llave privada en formato PEM
+}
+```
+
+**Errores que puede lanzar:**
+
+- `"La firma digital no contiene una llave privada"` — el `.p12` no tiene llave.
+- `"La firma digital no contiene un certificado"` — el `.p12` no tiene ningún certificado.
+- `"Ningún certificado de la firma digital corresponde a la llave privada"` — el `.p12` trae
+  certificados, pero ninguno hace pareja con la llave privada encontrada.
+- Errores de `node-forge` si la contraseña es incorrecta o el archivo está corrupto.
+
+```ts
+try {
+  const { certificado, llavePrivada } = sifen.obtainDigitalSign({
+    camino: "./certificados/firma.p12",
+    contraseña: "clave",
+  });
+} catch (error) {
+  // contraseña incorrecta, archivo inválido o sin llave/certificado
+}
+```
+
+---
+
+### `generateQr(generationQrDto)`
+
+Toma un documento electrónico (`rDE`) **ya firmado digitalmente**, calcula el enlace del
+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>`.
+
+| Parámetro  | Tipo     | Descripción                                                            |
+| ---------- | -------- | ---------------------------------------------------------------------- |
+| `xml`      | `string` | XML del `rDE` **firmado** (debe contener el nodo `Signature`).         |
+| `csc`      | `string` | Código de Seguridad del Contribuyente (secreto, entregado por la SET). |
+| `idCsc`    | `string` | Identificador del CSC (ej. `"0001"`).                                  |
+| `ambiente` | `string` | `"test"` o `"produccion"`. Define el dominio base del enlace del QR.   |
+
+**Retorna:** `Promise<string>` — el XML reconstruido con el nodo `dCarQR`.
+
+```ts
+const xmlConQr = await sifen.generateQr({
+  xml: xmlFirmado,
+  csc: "ABCD0000000000000000000000000000",
+  idCsc: "0001",
+  ambiente: "test",
+});
+```
+
+#### Cómo se construye el QR
+
+1. Se parsea el XML y se **valida que exista el nodo `Signature`**; si no está, lanza error.
+2. Se elige el dominio base según el ambiente:
+   - `test` → `https://ekuatia.set.gov.py/consultas-test`
+   - `produccion` → `https://ekuatia.set.gov.py/consultas`
+3. Se le concatena `/qr?` y los parámetros extraídos del documento, **en este orden**:
+
+   | Parámetro                 | Origen en el XML                                         | Notas                                           |
+   | ------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
+   | `nVersion`                | `rDE > dVerFor`                                          | Versión del formato.                            |
+   | `Id`                      | `rDE > DE[@Id]`                                          | El CDC del documento.                           |
+   | `dFeEmiDE`                | `rDE > DE > gDatGralOpe > dFeEmiDE`                      | Convertido a **hexadecimal**.                   |
+   | `dRucRec` _o_ `dNumIDRec` | `... > gDatRec`                                          | `dRucRec` si `iNatRec == 1`, si no `dNumIDRec`. |
+   | `dTotGralOpe`             | `rDE > DE > gTotSub > dTotGralOpe`                       | `0` si no existe.                               |
+   | `dTotIVA`                 | `rDE > DE > gTotSub > dTotIVA`                           | `0` si no existe.                               |
+   | `cItems`                  | Cantidad de `gDtipDE > gCamItem`                         | `0` si no hay ítems.                            |
+   | `DigestValue`             | `rDE > Signature > SignedInfo > Reference > DigestValue` | Convertido a **hexadecimal**.                   |
+   | `IdCSC`                   | Parámetro `idCsc`                                        | Último antes del hash.                          |
+   | `cHashQR`                 | `SHA256(cadena_de_parámetros + csc)`                     | Se agrega al final.                             |
+
+4. El enlace resultante (con `&`, `<` y `>` escapados como entidades XML) se inserta como texto
+   plano en un nodo `<gCamFuFD><dCarQR>` justo antes del cierre `</rDE>`.
+
+   > No se reconstruye el XML completo con `xml2js.Builder`: eso obligaría a reserializar el
+   > bloque `DE`/`Signature` ya firmado y, aunque el resultado sea lógicamente equivalente,
+   > puede canonizar distinto al validador de SIFEN y producir el mismo error de
+   > *"Valor de la firma (SignatureValue) diferente del calculado por el PKI"* que se evita en
+   > [`obtainDigitalSign`](#obtaindigitalsigndigitalsigndto). Por eso se hace un slice de texto
+   > sobre el XML firmado en vez de volver a parsearlo y serializarlo, dejando intactos los
+   > bytes que fueron firmados.
+
+   El XML final que devuelve `SifenService.generateQr` (vía `SifenPersistence`) pasa además por
+   `normalizeXML`, quedando en una sola línea igual que el resto de los XML que genera la
+   librería.
+
+<details>
+<summary>Ejemplo del enlace generado dentro de <code>dCarQR</code></summary>
+
+```
+https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&Id=01800123456001001000000012023052212345678901&dFeEmiDE=323032332d30352d32325431303a30303a3030&dRucRec=80012345&dTotGralOpe=550000&dTotIVA=50000&cItems=3&DigestValue=6a4b2c...&IdCSC=0001&cHashQR=9f2a7c1e4b8d...
+```
+
+Y así queda incrustado en el XML de salida:
+
+```xml
+<rDE>
+  <dVerFor>150</dVerFor>
+  <DE Id="01800123456001001000000012023052212345678901">
+    ...
+  </DE>
+  <Signature>...</Signature>
+  <gCamFuFD>
+    <dCarQR>https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&amp;Id=...&amp;cHashQR=...</dCarQR>
+  </gCamFuFD>
+</rDE>
+```
+
+</details>
+
+**Errores que puede lanzar:**
+
+- `"XML debe estar firmado digitalmente para generar el QR"` — el XML no tiene nodo `Signature`.
+- Errores de parseo de `xml2js` si el XML está malformado.
+- `TypeError` si el documento no respeta la estructura esperada del `rDE` (por ejemplo,
+  falta `gDatRec` o `gDtipDE`).
+
+```ts
+try {
+  const xmlConQr = await sifen.generateQr({
+    xml: xmlFirmado,
+    csc: process.env.SIFEN_CSC!,
+    idCsc: "0001",
+    ambiente: "produccion",
+  });
+} catch (error) {
+  // XML sin firmar, malformado o con estructura inesperada
+}
+```
+
+> **Nota sobre el `ambiente`:** internamente se compara contra el enum `SIFEN_ENVIRONMENT`
+> (`"test"` / `"produccion"`). Cualquier valor distinto de `"test"` cae en el enlace de
+> **producción**, así que conviene pasar el valor exacto.
+
+---
+
+### `generateDocument(generateDocumentoElectronicoDto)`
+
+Genera el XML completo del **Documento Electrónico** (`rDE`) — Factura Electrónica, Autofactura,
+Nota de Crédito/Débito o Remisión — según el Manual Técnico de SIFEN: arma el CDC, la cabecera,
+los datos generales de emisor/receptor, el detalle de ítems (con sus cálculos de precio,
+descuentos, anticipos e IVA) y los totales del documento.
+
+> ⚠️ El XML devuelto **no está firmado**. Es el paso previo a `generateQr`: primero se genera
+> este XML, la aplicación consumidora lo firma digitalmente (XMLDSig), y recién ese XML firmado
+> se le pasa a `generateQr` para incrustar el código QR.
+
+`generateDocumentoElectronicoDto` recibe todos los datos del documento directamente (ver
+estructura abajo).
+
+**Retorna:** `string` — XML del `rDE` normalizado (sin saltos de línea ni tabulaciones), listo
+para firmar.
+
+#### Estructura de `generateDocumentoElectronicoDto`
+
+```ts
+interface GenerateDocumentoElectronicoDto {
+  emisor: EmisorDto; // datos del emisor (RUC, razón social, dirección, ubicación...)
+  cliente: ClienteDto; // datos del receptor
+  timbrado: TimbradoDto; // timbrado, establecimiento, punto de expedición, número
+  idTipoEmision: number; // 1 = Normal, 2 = Contingencia
+  datosOperacion: DatosOperacionDto; // idTipoDocumento, idMoneda, idTipoTransaccion, idTipoImpuesto...
+  fechaEmision: string; // fecha/hora de emisión (dFeEmiDE)
+  datosFactura: DatosEspecificosFacturaDto; // campos específicos según idTipoDocumento (ver abajo)
+  detalleFactura: DetalleFacturaItemDto[]; // ítems de la operación
+  documentosAsociados?: DocumentosAsociadosDto;
+  transporte?: TransporteDto; // solo Factura (1) y Remisión (7)
+}
+```
+
+`datosOperacion.idTipoDocumento` determina qué documento se genera y qué otros campos son
+obligatorios:
+
+| `idTipoDocumento` | Documento              | Campo específico requerido en `datosFactura` |
+| ------------------ | ----------------------- | ----------------------------------------------------------- |
+| `1`                 | Factura Electrónica     | `condicion` (y opcionalmente `comprasPublicas` si `idTipoOperacion === 3`) |
+| `4`                 | Autofactura             | `autoFactura`                                                |
+| `5` / `6`           | Nota de Crédito/Débito  | `notaDebitoCredito`                                          |
+| `7`                 | Remisión                | `remision`                                                    |
+
+Todos los códigos (`idDepartamento`, `idDistrito`, `idCiudad`, `idPais`, `idUnidadMedida`,
+`idTipoContribuyente`, `idIva`, `idFormaPago`, etc.) deben existir en los catálogos de
+[`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts); un código
+inexistente hace que la librería lance un error al no encontrar la descripción asociada.
+
+<details>
+<summary>Ejemplo completo — Factura Electrónica al contado, un ítem gravado a 10% de IVA</summary>
+
+```ts
+const xml = sifen.generateDocument({
+  emisor: {
+    rucEmisor: "80012345",
+    digitoVerificadorEmisor: "6",
+    idTipoContribuyente: 2,
+    razonSocial: "Consultame S.A.",
+    direccion: "Avda. Mariscal López 1234",
+    idDepartamento: 1, // CAPITAL
+    idDistrito: 1, // ASUNCION (DISTRITO)
+    idCiudad: 1, // ASUNCION (DISTRITO)
+    telefono: "021123456",
+  },
+  cliente: {
+    idTipoReceptor: 1,
+    idTipoOperacion: 1,
+    idPais: "PRY",
+    esContribuyente: true,
+    idTipoContribuyente: 2,
+    ruc: "80099999",
+    digitoVerificado: "1",
+    razonSocial: "Cliente Ejemplo S.R.L.",
+    direccion: "Calle Falsa 123",
+  },
+  timbrado: {
+    timbrado: "12558651",
+    establecimiento: 1,
+    puntoExpedicion: 1,
+    numeroDocumento: 1,
+    fechaTimbrado: "2024-01-01",
+  },
+  idTipoEmision: 1,
+  datosOperacion: {
+    idTipoDocumento: 1, // Factura Electrónica
+    idMoneda: "PYG",
+    idTipoTransaccion: 1, // Venta de mercadería
+    idTipoImpuesto: 1, // IVA
+  },
+  fechaEmision: "2024-05-20T10:00:00",
+  datosFactura: {
+    idPresencia: 1, // Operación presencial
+    condicion: {
+      idCondicion: 1, // Contado
+      formasPagos: [{ idFormaPago: 1, idMoneda: "PYG", monto: 110000 }], // Efectivo
+    },
+  },
+  detalleFactura: [
+    {
+      codigo: "0001",
+      descripcion: "Servicio de consultoría",
+      idUnidadMedida: 77, // Unidad
+      cantidad: 1,
+      precioUnitario: 110000,
+      idIva: 1, // Gravado IVA
+      ivaBase: 100, // proporción gravada (100%)
+      tasaIva: 10, // tasa de IVA 10%
+    },
+  ],
+});
+```
+
+</details>
+
+**Errores que puede lanzar:**
+
+- `TypeError` (`Cannot read properties of undefined`) si falta el campo específico requerido
+  para el `idTipoDocumento` indicado (ej. `condicion` en una Factura).
+- Error implícito de `.find(...)!` si algún código (`idDepartamento`, `idIva`, `idUnidadMedida`,
+  etc.) no existe en el diccionario correspondiente.
+
+```ts
+try {
+  const xml = sifen.generateDocument({ ... });
+} catch (error) {
+  // datos faltantes según el tipo de documento, o código inexistente en el diccionario
+}
+```
+
+---
+
+### `signedXml(xml, tag, responseDigitalSign)`
+
+Firma digitalmente (**XMLDSig**) un XML usando `xml-crypto`. Es el paso que conecta
+`generateDocument` con `generateQr`: primero se genera el XML del `rDE` sin firmar, luego se
+firma con este método, y recién ese XML firmado se le pasa a `generateQr`.
+
+> ⚠️ Método **asíncrono**: devuelve `Promise<string>`.
+
+| Parámetro             | Tipo                  | Descripción                                                                 |
+| ---------------------- | ---------------------- | ----------------------------------------------------------------------------- |
+| `xml`                  | `string`               | XML sin firmar (ej. el `rDE` devuelto por `generateDocument`).               |
+| `tag`                  | `string`               | Nombre local del nodo a firmar (ej. `"DE"` para firmar el nodo `DE` del `rDE`). |
+| `responseDigitalSign`  | `ResponseDigitalSign`  | `{ certificado, llavePrivada }` en PEM, obtenido de `obtainDigitalSign`.      |
+
+**Retorna:** `Promise<string>` — el XML original con el nodo `<Signature>` insertado.
+
+```ts
+const firma = sifen.obtainDigitalSign({
+  camino: "./certificados/firma.p12",
+  contraseña: "mi-clave-secreta",
+});
+
+const xmlFirmado = await sifen.signedXml(xmlFactura, "DE", firma);
+```
+
+#### Cómo firma
+
+1. Ubica el nodo a firmar por su nombre local (`xpath: //*[local-name()='<tag>']`), sin importar
+   el namespace en el que esté declarado.
+2. Aplica las transformaciones `enveloped-signature` y **Exclusive Canonicalization** (`exc-c14n`)
+   sobre ese nodo, y calcula el `DigestValue` con **SHA-256**.
+3. Firma con **RSA-SHA256** (`rsa-sha256`) usando la llave privada provista.
+4. Arma el `<KeyInfo>` incrustando el certificado como `<X509Data><X509Certificate>` (el PEM
+   se limpia de cabeceras/pies y saltos de línea antes de incrustarlo).
+5. Inserta el `<Signature>` resultante **inmediatamente después** del nodo referenciado por
+   `tag` (`location: { reference: "//*[local-name()='<tag>']", action: "after" }`), tal como
+   exige el Manual Técnico de SIFEN para el `rDE` (la firma va como hermana del `DE`, dentro
+   de `rDE`).
+
+**Errores que puede lanzar:**
+
+- Cualquier error de `xml-crypto` si el `xml` no contiene un nodo que coincida con `tag`, o si
+  `certificado`/`llavePrivada` no son un par PEM válido.
+
+```ts
+try {
+  const xmlFirmado = await sifen.signedXml(xmlFactura, "DE", firma);
+} catch (error) {
+  // tag inexistente en el xml, o certificado/llave privada inválidos
+}
+```
+
+---
+
+## DTOs (contratos de entrada)
+
+Todos los DTOs de consulta extienden `GenerateIdDto`, que aporta el campo `id`.
+
+```ts
+interface GenerateIdDto {
+  id: number;
+}
+
+interface ConsultRucDto extends GenerateIdDto {
+  ruc: string;
+}
+
+interface ConsultDocumentDto extends GenerateIdDto {
+  cdc: string;
+}
+
+interface ConsultBatchDto extends GenerateIdDto {
+  codigoLote: string;
+}
+
+interface DigitalSignDto {
+  camino: string; // ruta al .p12
+  contraseña: string; // clave del .p12
+}
+
+interface GenerationQrDto {
+  xml: string; // XML del rDE ya firmado
+  csc: string; // Código de Seguridad del Contribuyente
+  idCsc: string; // Identificador del CSC
+  ambiente: string; // "test" | "produccion"
+}
+```
+
+Enums disponibles en [`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts):
+
+```ts
+enum SIFEN_ENVIRONMENT {
+  TEST = "test",
+  PRODUCCION = "produccion",
+}
+
+enum LINK_SIFEN {
+  TEST = "https://ekuatia.set.gov.py/consultas-test",
+  PRODUCCION = "https://ekuatia.set.gov.py/consultas",
+}
+```
+
+DTOs ya definidos pero **aún sin implementación** en la persistencia (ver
+[roadmap](#estado--roadmap)):
+
+```ts
+interface CancelInvoiceDto extends GenerateIdDto {
+  cdc: string;
+  motivo: string;
+}
+
+interface InvalidationInvoiceDto extends GenerateIdDto {
+  timbrado: string;
+  establecimiento: number;
+  puntoExpedicion: number;
+  desde: number;
+  hasta: number;
+  tipoDocumento: number;
+  motivo: string;
+}
+```
+
+### DTOs de `generateDocument`
+
+`generateDocument` no extiende `GenerateIdDto` — usa su propia familia de DTOs, definida en
+[`src/shared/clases/documento.dto.ts`](src/shared/clases/documento.dto.ts) en vez del barrel
+`src/sifen/applications/dtos`. El contrato de entrada es `GenerateDocumentoElectronicoDto`
+(ver [estructura de `generateDocumentoElectronicoDto`](#estructura-de-generatedocumentoelectronicodto)
+más arriba); ahí también viven
+`EmisorDto`, `ClienteDto`, `TimbradoDto`, `DetalleFacturaItemDto` y el resto de los tipos
+específicos por sección del Manual Técnico (autofactura, nota de crédito/débito, remisión,
+transporte, condición de pago, etc.).
+
+---
+
+## Funciones utilitarias internas
+
+Viven en [`src/shared/functions/functions.utils.ts`](src/shared/functions/functions.utils.ts).
+No forman parte de la API pública, pero es útil conocerlas:
+
+| Función                      | Qué hace                                                                                      |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `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.                                                       |
+| `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)_ |
+| `generateQr`                 | Arma el enlace del QR (params + hash SHA-256) y lo incrusta como texto en `gCamFuFD > dCarQR` sin reserializar el XML firmado. _(async)_ |
+| `calculateDigitVerification` / `calcularDigitoVerificador` | Dos implementaciones (histórica y actual) del dígito verificador módulo 11, usadas por el CDC. |
+
+Además, la generación del Documento Electrónico completo vive en dos clases dedicadas dentro de
+[`src/shared/clases/`](src/shared/clases/), usadas por `SifenPersistence.generateDocument`:
+
+| Clase             | Archivo                | Qué hace                                                                                                    |
+| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `Documento`         | `documento.ts`          | Arma el objeto `rDE` sección por sección (CDC, cabecera, timbrado, datos generales, ítems, totales, documentos asociados, transporte) y lo serializa a XML con `xml2js.Builder`. |
+| `DetalleDocumento`  | `detalleDocumento.ts`   | Cálculos por ítem (precio, tipo de cambio, descuentos, anticipos e IVA) que consume `Documento` al armar el detalle. Métodos estáticos. |
+
+---
+
+## Arquitectura del proyecto
+
+El proyecto sigue una **arquitectura hexagonal (puertos y adaptadores)** combinada con
+principios de **Clean Architecture**, organizada por el módulo de negocio `sifen`.
+
+```
+             ┌──────────────────────────────────────────────┐
+             │                 applications                 │
+             │   SifenService  (punto de entrada / fachada)  │
+             │   DTOs (contratos de entrada)                 │
+             └───────────────────────┬──────────────────────┘
+                                     │ orquesta
+                                     ▼
+             ┌──────────────────────────────────────────────┐
+             │                    domain                     │
+             │   useCases  (ConsultRuc, ConsultBatch, ...)   │
+             │   repository (SifenRepository = PUERTO)        │
+             └───────────────────────┬──────────────────────┘
+                                     │ implementado por
+                                     ▼
+             ┌──────────────────────────────────────────────┐
+             │                infrastructure                 │
+             │   SifenPersistence (ADAPTADOR del puerto)      │
+             │   → funciones utilitarias (XML, forge)         │
+             │   → clases Documento / DetalleDocumento        │
+             └──────────────────────────────────────────────┘
+```
+
+**Flujo de una llamada** (ej. `consultRuc`):
+
+1. La app llama a `SifenService.consultRuc(dto)` — capa **applications**.
+2. El servicio delega en `ConsultRucUseCase.execute(dto)` — capa **domain**.
+3. El caso de uso invoca la interfaz `SifenRepository` (**puerto**), sin conocer la implementación.
+4. En runtime el puerto lo resuelve `SifenPersistence` (**adaptador**) — capa **infrastructure**.
+5. La persistencia usa las funciones utilitarias para generar y normalizar el XML.
+
+`generateDocument` sigue el mismo flujo (`SifenService.generateDocument` →
+`GenerateDocumentUseCase` → `SifenRepository` → `SifenPersistence.generateDocument`), pero en el
+paso 5 la persistencia delega en la clase `Documento` (`src/shared/clases/documento.ts`) en vez
+de en una función utilitaria simple, ya que el armado del Documento Electrónico completo requiere
+mantener estado intermedio (`jsonFactura`) mientras se arma cada sección del XML.
+
+`signedXml` también sigue el mismo flujo (`SifenService.signedXml` → `SignedXmlUseCase` →
+`SifenRepository` → `SifenPersistence.signedXml`), delegando en la función utilitaria `signXml`
+(`src/shared/functions/functions.utils.ts`), que envuelve `xml-crypto`.
+
+**Por qué esta separación:**
+
+- **`domain`** no depende de nada externo: define _qué_ se hace (casos de uso) y el
+  contrato `SifenRepository`. Es el núcleo estable.
+- **`infrastructure`** contiene los detalles concretos (armado de XML, `node-forge`, `fs`).
+  Se puede reemplazar sin tocar el dominio.
+- **`applications`** expone la fachada y los DTOs que consume el mundo exterior.
+- **`shared`** agrupa utilidades y DTOs de respuesta transversales a los módulos.
+
+La inversión de dependencias es clave: `SifenPersistence implements SifenRepository`, de
+modo que el dominio depende de la **abstracción**, no de la implementación.
+
+---
+
+## Estructura de carpetas
+
+```
+consultame-sdk/
+├── src/
+│   ├── index.ts                          # Punto de entrada público → exporta SifenService
+│   │
+│   ├── shared/                           # Código transversal
+│   │   ├── clases/
+│   │   │   ├── documento.ts              # Documento: arma el rDE completo (Factura, Nota, Remisión...)
+│   │   │   ├── documento.dto.ts          # DTOs de generateDocument (EmisorDto, ClienteDto, DetalleFacturaItemDto...)
+│   │   │   └── detalleDocumento.ts       # DetalleDocumento: cálculos por ítem (precio, IVA, descuentos)
+│   │   ├── dto/
+│   │   │   └── responseDigitalSign.dto.ts # ResponseDigitalSign { certificado, llavePrivada }
+│   │   ├── functions/
+│   │   │   └── functions.utils.ts        # XML, normalizeXML, readDigitalSign, generateQr, DV
+│   │   └── utils/
+│   │       └── dictionary.utils.ts       # Catálogos SIFEN (departamentos, monedas, tipos...) y enums SIFEN_ENVIRONMENT / LINK_SIFEN
+│   │
+│   └── sifen/                            # Módulo de negocio SIFEN
+│       ├── applications/                 # Capa de aplicación (fachada + contratos)
+│       │   ├── dtos/
+│       │   │   ├── index.ts              # Barrel de DTOs
+│       │   │   ├── generateId.dto.ts     # GenerateIdDto (base)
+│       │   │   ├── consultRuc.dto.ts
+│       │   │   ├── consultDocument.dto.ts
+│       │   │   ├── consultBatch.dto.ts
+│       │   │   ├── digitalSign.dto.ts
+│       │   │   ├── generationQr.dto.ts
+│       │   │   ├── cancelDocument.dto.ts
+│       │   │   └── invalidationInvoice.dto.ts
+│       │   └── services/
+│       │       └── sifen.service.ts      # SifenService (fachada pública)
+│       │
+│       ├── domain/                       # Núcleo de negocio
+│       │   ├── repository/
+│       │   │   └── sifen.repository.ts   # SifenRepository (PUERTO / interfaz)
+│       │   └── useCases/
+│       │       ├── index.ts              # Barrel de casos de uso
+│       │       ├── consultRuc.useCase.ts
+│       │       ├── consultDocument.useCase.ts
+│       │       ├── consultBatch.useCase.ts
+│       │       ├── obtainDigitalSign.useCase.ts
+│       │       ├── generateQr.useCase.ts
+│       │       ├── generateDocument.useCase.ts
+│       │       └── signedXml.useCase.ts
+│       │
+│       └── infrastructure/               # Detalles concretos (ADAPTADORES)
+│           └── persistence/
+│               └── sifen.persistence.ts  # SifenPersistence implements SifenRepository
+│
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts                        # Build dual CJS + ESM (target node22)
+├── pnpm-workspace.yaml
+└── README.md
+```
+
+---
+
+## Scripts de desarrollo
+
+| Script             | Comando                     | Descripción                                         |
+| ------------------ | --------------------------- | --------------------------------------------------- |
+| `pnpm build`       | `tsup && build:types`       | Compila a `dist/` (CJS + ESM) y genera los `.d.ts`. |
+| `pnpm build:types` | `tsc --emitDeclarationOnly` | Solo emite las declaraciones de tipos.              |
+| `pnpm dev`         | `tsup --watch`              | Build en modo watch.                                |
+| `pnpm typecheck`   | `tsc --noEmit`              | Verifica tipos sin emitir archivos.                 |
+| `pnpm play`        | `tsx src/index.ts`          | Ejecuta `src/index.ts` para pruebas manuales.       |
+| `pnpm play:watch`  | `tsx watch src/index.ts`    | Igual que `play` pero en modo watch.                |
+
+---
+
+## Estado / roadmap
+
+Funcionalidades **implementadas**:
+
+- ✅ Consulta de RUC (`consultRuc`)
+- ✅ Consulta de documento por CDC (`consultDocument`)
+- ✅ Consulta de lote (`consultBatch`)
+- ✅ Lectura de firma digital `.p12` → PEM (`obtainDigitalSign`)
+- ✅ Generación e incrustación del código QR (`generateQr`)
+- ✅ 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`)
+
+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. `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.