arca-sdk 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ Todos los cambios notables de este proyecto se documentan en este archivo.
 
 ---
 
+## [1.1.0] — 2026-02-28
+
+### ✨ Nuevos Comprobantes (Vouchers)
+
+Se expandió la funcionalidad del servicio de facturación (`WsfeService`) para cubrir el espectro completo de comprobantes básicos:
+
+- **Notas de Crédito**: Agregados métodos `issueCreditNoteA()`, `issueCreditNoteB()` y `issueCreditNoteC()`.
+- **Notas de Débito**: Agregados métodos `issueDebitNoteA()`, `issueDebitNoteB()` y `issueDebitNoteC()`.
+- **Recibos**: Agregados métodos `issueReceiptA()`, `issueReceiptB()` y `issueReceiptC()`.
+- **Comprobantes Asociados**: El SDK ahora genera correctamente el nodo `<ar:CbtesAsoc>` de forma obligatoria para emitir NC/ND, asegurando que la operación de contingencia (anulación total o parcial de una factura) respete el estándar del ente recaudador. 
+
+---
+
+## [1.0.4] — 2026-02-27
+
+### 🐛 Bugfix — Timezone Handling
+
+- Se ajustó la generación de fechas para forzar la zona horaria UTC-3 (Argentina) independientemente de la zona horaria del servidor (ej: AWS, Vercel).
+- Se restan 10 minutos al tiempo de generación en los TRA para evitar errores de desincronización con los servidores de ARCA.
+
+---
+
 ## [1.0.1] — 2026-02-23
 
 ### 🐛 Bugfix crítico — QR URL

package/README.md

@@ -46,6 +46,34 @@ pnpm add arca-sdk
 
 ---
 
+## 🔐 Security & Responsibility / Seguridad y Responsabilidad
+
+### 🇺🇸 English
+
+**arca-sdk** is designed to be **stateless and cloud-native**. It does **NOT** persist certificates or private keys to the filesystem.
+
+It is the responsibility of the implementing application to:
+1.  **Securely store** the Private Key (`.key`) and Certificate (`.crt`). (Recommended: Encrypted Database, AWS KMS, HashiCorp Vault).
+2.  **Decrypt** credentials only at runtime.
+3.  Pass the raw strings/buffers to the SDK constructors.
+
+> [!WARNING]
+> Never commit your `.key` files to Git or expose them in public folders. The SDK operates in-memory to ensure maximum security in Serverless environments (Vercel, AWS Lambda).
+
+### 🇦🇷 Español
+
+**arca-sdk** está diseñado para ser **stateless** (sin estado) y **cloud-native**. **NO** guarda certificados ni claves privadas en el sistema de archivos.
+
+Es responsabilidad de la aplicación que implementa el SDK:
+1.  **Almacenar de forma segura** la Clave Privada (`.key`) y el Certificado (`.crt`). (Recomendado: Base de Datos encriptada, AWS KMS, HashiCorp Vault).
+2.  **Desencriptar** las credenciales solo en tiempo de ejecución.
+3.  Pasar los strings o buffers crudos a los constructores del SDK.
+
+> [!CAUTION]
+> Nunca subas tus archivos `.key` a Git ni los expongas en carpetas públicas. El SDK opera en memoria para garantizar la máxima seguridad en entornos Serverless (Vercel, AWS Lambda).
+
+---
+
 ## Quick Start — 5 minutos y estás facturando
 
 ```typescript
@@ -99,9 +127,12 @@ console.log('QR:', result.qrUrl);             // 'https://www.afip.gob.ar/fe/qr/
 |--------|-------------|---------------|
 | `issueSimpleReceipt()` | Ticket C | Monto total, sin detalle. Ideal para POS simple |
 | `issueReceipt()` | Ticket C + items | Con detalle de productos guardado localmente |
-| `issueInvoiceC()` | Factura C | Monotributistas a consumidor final |
+| `issueInvoiceC()` | Factura C | Monotributistas a consumidor final / Empresas |
 | `issueInvoiceB()` | Factura B | Responsable Inscripto a consumidor final / Monotributo |
 | `issueInvoiceA()` | Factura A | Responsable Inscripto a Responsable Inscripto |
+| `issueCreditNoteA/B/C()` | Nota de Crédito | Anulación/Devolución (Requiere asociar la factura original) |
+| `issueDebitNoteA/B/C()` | Nota de Débito | Cobro extra/Penalidad (Requiere asociar la factura original) |
+| `issueReceiptA/B/C()` | Recibo | Comprobante de pago (misma emisión que una factura) |
 
 ### ✅ Consultas disponibles
 
@@ -152,6 +183,26 @@ result.vat?.forEach(v => {
 });
 ```
 
+### Nota de Crédito (Anulando factura previa)
+
+```typescript
+import { InvoiceType } from 'arca-sdk';
+
+const result = await wsfe.issueCreditNoteC({
+  items: [
+    { description: 'Anulación de equipo defectuoso', quantity: 1, unitPrice: 45000 },
+  ],
+  // ⚠️ Obligatorio en NC/ND: especificar el comprobante original afectado
+  associatedInvoices: [{
+    type: InvoiceType.FACTURA_C, // La factura que estoy anulando
+    pointOfSale: 4,
+    invoiceNumber: 15302,
+  }],
+});
+
+console.log('CAE de anulación:', result.cae);
+```
+
 ### Consulta de Padrón A13
 
 ```typescript
@@ -242,6 +293,9 @@ try {
 }
 ```
 
+### 🚚 Acerca de los Remitos
+> **¡Atención!** Este SDK implementa nativamente el servicio `WSFE` (Facturación Electrónica). Si tu negocio necesita emitir **Remitos Electrónicos Oficiales** para el traslado físico de mercaderías (Remitos Cárnicos, Azucareros, Harineros, etc.), tené en cuenta que la AFIP exige usar un webservice totalmente distinto llamado `WSREM` o similares. Estos servicios aún no están cubiertos por esta versión del SDK.
+
 ---
 
 ## Compatibilidad

package/dist/index.cjs

@@ -98,16 +98,33 @@ var ArcaNetworkError = class extends ArcaError {
 
 // src/utils/xml.ts
 var import_fast_xml_parser = require("fast-xml-parser");
+
+// src/utils/formatArcaDate.ts
+function formatArcaDate(date) {
+  const pad = (n) => n.toString().padStart(2, "0");
+  const tzOffset = 3 * 60 * 60 * 1e3;
+  const baTime = new Date(date.getTime() - tzOffset);
+  const yyyy = baTime.getUTCFullYear();
+  const mm = pad(baTime.getUTCMonth() + 1);
+  const dd = pad(baTime.getUTCDate());
+  const hh = pad(baTime.getUTCHours());
+  const min = pad(baTime.getUTCMinutes());
+  const ss = pad(baTime.getUTCSeconds());
+  return `${yyyy}-${mm}-${dd}T${hh}:${min}:${ss}-03:00`;
+}
+
+// src/utils/xml.ts
 function buildTRA(service, cuit) {
   const now = /* @__PURE__ */ new Date();
-  const expirationTime = new Date(now.getTime() + 12 * 60 * 60 * 1e3);
+  const genTime = new Date(now.getTime() - 10 * 60 * 1e3);
+  const expTime = new Date(now.getTime() + 12 * 60 * 60 * 1e3);
   const tra = {
     loginTicketRequest: {
       "@_version": "1.0",
       header: {
         uniqueId: Math.floor(now.getTime() / 1e3),
-        generationTime: now.toISOString(),
-        expirationTime: expirationTime.toISOString()
+        generationTime: formatArcaDate(genTime),
+        expirationTime: formatArcaDate(expTime)
       },
       service
     }
@@ -490,8 +507,17 @@ var WsaaService = class {
 // src/types/wsfe.ts
 var InvoiceType = /* @__PURE__ */ ((InvoiceType2) => {
   InvoiceType2[InvoiceType2["FACTURA_A"] = 1] = "FACTURA_A";
+  InvoiceType2[InvoiceType2["NOTA_DEBITO_A"] = 2] = "NOTA_DEBITO_A";
+  InvoiceType2[InvoiceType2["NOTA_CREDITO_A"] = 3] = "NOTA_CREDITO_A";
+  InvoiceType2[InvoiceType2["RECIBO_A"] = 4] = "RECIBO_A";
   InvoiceType2[InvoiceType2["FACTURA_B"] = 6] = "FACTURA_B";
+  InvoiceType2[InvoiceType2["NOTA_DEBITO_B"] = 7] = "NOTA_DEBITO_B";
+  InvoiceType2[InvoiceType2["NOTA_CREDITO_B"] = 8] = "NOTA_CREDITO_B";
+  InvoiceType2[InvoiceType2["RECIBO_B"] = 9] = "RECIBO_B";
   InvoiceType2[InvoiceType2["FACTURA_C"] = 11] = "FACTURA_C";
+  InvoiceType2[InvoiceType2["NOTA_DEBITO_C"] = 12] = "NOTA_DEBITO_C";
+  InvoiceType2[InvoiceType2["NOTA_CREDITO_C"] = 13] = "NOTA_CREDITO_C";
+  InvoiceType2[InvoiceType2["RECIBO_C"] = 15] = "RECIBO_C";
   InvoiceType2[InvoiceType2["TICKET_A"] = 81] = "TICKET_A";
   InvoiceType2[InvoiceType2["TICKET_B"] = 82] = "TICKET_B";
   InvoiceType2[InvoiceType2["TICKET_C"] = 83] = "TICKET_C";
@@ -720,57 +746,93 @@ var WsfeService = class _WsfeService {
     return { ...cae, items: params.items };
   }
   /**
-   * Emite una Factura C (consumidor final, sin discriminación de IVA).
+   * Emite una Factura A (Responsable Inscripto a Responsable Inscripto, con IVA discriminado).
+   * REQUIERE `vatRate` en todos los items.
    */
-  async issueInvoiceC(params) {
-    const total = round(calculateTotal(params.items));
-    return this.issueDocument({
-      type: 11 /* FACTURA_C */,
-      concept: params.concept || 1 /* PRODUCTS */,
-      total,
-      date: params.date,
-      buyer: {
-        docType: 99 /* FINAL_CONSUMER */,
-        docNumber: "0"
-      },
-      items: params.items
-    });
+  async issueInvoiceA(params) {
+    return this.issueInvoiceWithVAT(1 /* FACTURA_A */, params);
   }
   /**
    * Emite una Factura B (con IVA discriminado).
    * REQUIERE `vatRate` en todos los items.
    */
   async issueInvoiceB(params) {
-    this.validateItemsWithVAT(params.items);
-    const includesVAT = params.includesVAT || false;
-    const vatData = this.calculateVATByRate(params.items, includesVAT);
-    return this.issueDocument({
-      type: 6 /* FACTURA_B */,
-      concept: params.concept || 1 /* PRODUCTS */,
-      items: params.items,
-      buyer: params.buyer,
-      date: params.date,
-      vatData,
-      includesVAT
-    });
+    return this.issueInvoiceWithVAT(6 /* FACTURA_B */, params);
   }
   /**
-   * Emite una Factura A (Responsable Inscripto a Responsable Inscripto, con IVA discriminado).
-   * REQUIERE `vatRate` en todos los items.
+   * Emite una Factura C (consumidor final, sin discriminación de IVA).
    */
-  async issueInvoiceA(params) {
-    this.validateItemsWithVAT(params.items);
-    const includesVAT = params.includesVAT || false;
-    const vatData = this.calculateVATByRate(params.items, includesVAT);
-    return this.issueDocument({
-      type: 1 /* FACTURA_A */,
-      concept: params.concept || 1 /* PRODUCTS */,
-      items: params.items,
-      buyer: params.buyer,
-      date: params.date,
-      vatData,
-      includesVAT
-    });
+  async issueInvoiceC(params) {
+    return this.issueInvoiceWithoutVAT(11 /* FACTURA_C */, params);
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Recibos
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /**
+   * Emite un Recibo A (con IVA discriminado).
+   */
+  async issueReceiptA(params) {
+    return this.issueInvoiceWithVAT(4 /* RECIBO_A */, params);
+  }
+  /**
+   * Emite un Recibo B (con IVA discriminado).
+   */
+  async issueReceiptB(params) {
+    return this.issueInvoiceWithVAT(9 /* RECIBO_B */, params);
+  }
+  /**
+   * Emite un Recibo C (sin discriminación de IVA).
+   */
+  async issueReceiptC(params) {
+    return this.issueInvoiceWithoutVAT(15 /* RECIBO_C */, params);
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Notas de Crédito
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /**
+   * Emite una Nota de Crédito A.
+   * REQUIERE especificar la Factura A original en `associatedInvoices`.
+   */
+  async issueCreditNoteA(params) {
+    return this.issueInvoiceWithVAT(3 /* NOTA_CREDITO_A */, params);
+  }
+  /**
+   * Emite una Nota de Crédito B.
+   * REQUIERE especificar la Factura B original en `associatedInvoices`.
+   */
+  async issueCreditNoteB(params) {
+    return this.issueInvoiceWithVAT(8 /* NOTA_CREDITO_B */, params);
+  }
+  /**
+   * Emite una Nota de Crédito C.
+   * REQUIERE especificar la Factura C original en `associatedInvoices`.
+   */
+  async issueCreditNoteC(params) {
+    return this.issueInvoiceWithoutVAT(13 /* NOTA_CREDITO_C */, params);
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Notas de Débito
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /**
+   * Emite una Nota de Débito A.
+   * REQUIERE especificar la Factura A original en `associatedInvoices`.
+   */
+  async issueDebitNoteA(params) {
+    return this.issueInvoiceWithVAT(2 /* NOTA_DEBITO_A */, params);
+  }
+  /**
+   * Emite una Nota de Débito B.
+   * REQUIERE especificar la Factura B original en `associatedInvoices`.
+   */
+  async issueDebitNoteB(params) {
+    return this.issueInvoiceWithVAT(7 /* NOTA_DEBITO_B */, params);
+  }
+  /**
+   * Emite una Nota de Débito C.
+   * REQUIERE especificar la Factura C original en `associatedInvoices`.
+   */
+  async issueDebitNoteC(params) {
+    return this.issueInvoiceWithoutVAT(12 /* NOTA_DEBITO_C */, params);
   }
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // Consultas
@@ -901,6 +963,63 @@ var WsfeService = class _WsfeService {
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // Métodos internos
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /**
+   * Helper para emitir comprobantes tipo A/B que requieren IVA
+   */
+  async issueInvoiceWithVAT(type, params) {
+    this.validateItemsWithVAT(params.items);
+    this.validateAssociatedInvoices(type, params.associatedInvoices);
+    const includesVAT = params.includesVAT || false;
+    const vatData = this.calculateVATByRate(params.items, includesVAT);
+    return this.issueDocument({
+      type,
+      concept: params.concept || 1 /* PRODUCTS */,
+      items: params.items,
+      buyer: params.buyer,
+      associatedInvoices: params.associatedInvoices,
+      date: params.date,
+      vatData,
+      includesVAT
+    });
+  }
+  /**
+   * Helper para emitir comprobantes tipo C que no discriminan IVA
+   */
+  async issueInvoiceWithoutVAT(type, params) {
+    this.validateAssociatedInvoices(type, params.associatedInvoices);
+    const total = round(calculateTotal(params.items));
+    return this.issueDocument({
+      type,
+      concept: params.concept || 1 /* PRODUCTS */,
+      total,
+      date: params.date,
+      buyer: params.buyer || {
+        docType: 99 /* FINAL_CONSUMER */,
+        docNumber: "0"
+      },
+      items: params.items,
+      associatedInvoices: params.associatedInvoices
+    });
+  }
+  /**
+   * Validación obligatoria para NC/ND
+   */
+  validateAssociatedInvoices(type, associatedInvoices) {
+    const needsAssociation = [
+      3 /* NOTA_CREDITO_A */,
+      2 /* NOTA_DEBITO_A */,
+      8 /* NOTA_CREDITO_B */,
+      7 /* NOTA_DEBITO_B */,
+      13 /* NOTA_CREDITO_C */,
+      12 /* NOTA_DEBITO_C */
+    ].includes(type);
+    if (needsAssociation && (!associatedInvoices || associatedInvoices.length === 0)) {
+      throw new ArcaValidationError(
+        "Las Notas de Cr\xE9dito y D\xE9bito requieren al menos un comprobante asociado.",
+        { hint: "Debes enviar el arreglo `associatedInvoices` con la factura original a la cual haces referencia" }
+      );
+    }
+  }
   /**
    * Método genérico interno para emitir cualquier tipo de comprobante.
    */
@@ -925,6 +1044,7 @@ var WsfeService = class _WsfeService {
       concept: request.concept,
       date: request.date || /* @__PURE__ */ new Date(),
       buyer: request.buyer,
+      associatedInvoices: request.associatedInvoices,
       net,
       vat,
       total,
@@ -1070,6 +1190,21 @@ var WsfeService = class _WsfeService {
       });
       vatXml += "\n      </ar:Iva>";
     }
+    let asocXml = "";
+    if (params.associatedInvoices && params.associatedInvoices.length > 0) {
+      asocXml = "<ar:CbtesAsoc>";
+      params.associatedInvoices.forEach((asoc) => {
+        asocXml += `
+        <ar:CbteAsoc>
+          <ar:Tipo>${asoc.type}</ar:Tipo>
+          <ar:PtoVta>${asoc.pointOfSale}</ar:PtoVta>
+          <ar:Nro>${asoc.invoiceNumber}</ar:Nro>
+          ${asoc.cuit ? `<ar:Cuit>${asoc.cuit}</ar:Cuit>` : ""}
+          ${asoc.date ? `<ar:CbteFch>${asoc.date.toISOString().split("T")[0].replace(/-/g, "")}</ar:CbteFch>` : ""}
+        </ar:CbteAsoc>`;
+      });
+      asocXml += "\n      </ar:CbtesAsoc>";
+    }
     return `<?xml version="1.0" encoding="UTF-8"?>
 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:ar="http://ar.gov.afip.dif.FEV1/">
@@ -1103,6 +1238,7 @@ var WsfeService = class _WsfeService {
             <ar:ImpTrib>0.00</ar:ImpTrib>
             <ar:MonId>PES</ar:MonId>
             <ar:MonCotiz>1</ar:MonCotiz>
+            ${asocXml}
             ${vatXml}
           </ar:FECAEDetRequest>
         </ar:FeDetReq>