arca-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,326 @@
+/**
+ * Tipos comunes compartidos en toda la SDK
+ */
+/**
+ * Ambiente de ejecución ARCA
+ */
+type Environment = 'homologacion' | 'produccion';
+/**
+ * Configuración base para servicios ARCA
+ */
+interface ArcaConfig {
+    /** Ambiente (homologación o producción) */
+    environment: Environment;
+    /** CUIT del contribuyente (11 dígitos sin guiones) */
+    cuit: string;
+}
+/**
+ * Error personalizado de ARCA SDK
+ */
+declare class ArcaError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Error de autenticación WSAA
+ */
+declare class ArcaAuthError extends ArcaError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Error de validación de input
+ */
+declare class ArcaValidationError extends ArcaError {
+    constructor(message: string, details?: unknown);
+}
+
+/**
+ * Configuración para WSAA
+ */
+interface WsaaConfig extends ArcaConfig {
+    /** Certificado X.509 en formato PEM */
+    cert: string;
+    /** Clave privada en formato PEM */
+    key: string;
+    /** Servicio ARCA a autenticar (ej: 'wsfe', 'wsmtxca') */
+    service: string;
+}
+/**
+ * Ticket de acceso obtenido de WSAA
+ */
+interface LoginTicket {
+    /** Token de autenticación */
+    token: string;
+    /** Firma del token */
+    sign: string;
+    /** Fecha de generación (ISO 8601) */
+    generationTime: Date;
+    /** Fecha de expiración (ISO 8601) */
+    expirationTime: Date;
+}
+
+/**
+ * Servicio de autenticación WSAA (Web Service de Autenticación y Autorización)
+ *
+ * @example
+ * ```typescript
+ * const wsaa = new WsaaService({
+ *   environment: 'homologacion',
+ *   cuit: '20123456789',
+ *   cert: fs.readFileSync('cert.pem', 'utf-8'),
+ *   key: fs.readFileSync('key.pem', 'utf-8'),
+ *   service: 'wsfe',
+ * });
+ *
+ * const ticket = await wsaa.login();
+ * console.log('Token:', ticket.token);
+ * ```
+ */
+declare class WsaaService {
+    private config;
+    private ticketManager;
+    constructor(config: WsaaConfig);
+    /**
+     * Valida la configuración
+     */
+    private validateConfig;
+    /**
+     * Obtiene un ticket de acceso válido
+     * Usa cache si el ticket actual es válido
+     *
+     * @returns Ticket de acceso
+     */
+    login(): Promise<LoginTicket>;
+    /**
+     * Solicita un nuevo ticket a WSAA
+     */
+    private requestNewTicket;
+    /**
+     * Construye el SOAP request para WSAA
+     */
+    private buildSoapRequest;
+    /**
+     * Limpia el ticket en cache (forzar renovación)
+     */
+    clearCache(): void;
+}
+
+/**
+ * Configuración para WSFE
+ */
+interface WsfeConfig extends ArcaConfig {
+    /** Ticket de autenticación WSAA */
+    ticket: LoginTicket;
+    /** Punto de venta (4 dígitos) */
+    puntoVenta: number;
+}
+/**
+ * Tipo de comprobante
+ */
+declare enum TipoComprobante {
+    FACTURA_A = 1,
+    FACTURA_B = 6,
+    FACTURA_C = 11,
+    TICKET_A = 81,
+    TICKET_B = 82,
+    TICKET_C = 83
+}
+/**
+ * Concepto de facturación
+ */
+declare enum Concepto {
+    PRODUCTOS = 1,// Productos
+    SERVICIOS = 2,// Servicios
+    PRODUCTOS_Y_SERVICIOS = 3
+}
+/**
+ * Tipo de documento del cliente
+ */
+declare enum TipoDocumento {
+    CUIT = 80,
+    CUIL = 86,
+    CDI = 87,
+    LE = 89,
+    LC = 90,
+    CI_EXTRANJERA = 91,
+    PASAPORTE = 94,
+    CI_BUENOS_AIRES = 95,
+    CI_POLICIA_FEDERAL = 96,
+    DNI = 96,
+    CONSUMIDOR_FINAL = 99
+}
+/**
+ * Item de factura
+ */
+interface FacturaItem {
+    /** Descripción del producto/servicio */
+    descripcion: string;
+    /** Cantidad */
+    cantidad: number;
+    /** Precio unitario */
+    precioUnitario: number;
+    /** IVA % (0, 10.5, 21, 27) */
+    alicuotaIva?: number;
+}
+/**
+ * Datos del comprador
+ */
+interface Comprador {
+    /** Tipo de documento */
+    tipoDocumento: TipoDocumento;
+    /** Número de documento (sin guiones) */
+    nroDocumento: string;
+}
+/**
+ * Request para emitir factura
+ */
+interface EmitirFacturaRequest {
+    /** Tipo de comprobante */
+    tipo: TipoComprobante;
+    /** Concepto */
+    concepto: Concepto;
+    /** Comprador (opcional para Factura C consumidor final) */
+    comprador?: Comprador;
+    /** Items de la factura (calculan el total si se proveen) */
+    items?: FacturaItem[];
+    /** Monto total (requerido si no hay items) */
+    total?: number;
+    /** Desglose de IVA (requerido para Factura B/A) */
+    ivaData?: {
+        alicuota: number;
+        baseImponible: number;
+        importe: number;
+    }[];
+    /** Fecha del comprobante (default: hoy) */
+    fecha?: Date;
+}
+/**
+ * Respuesta CAE (Código de Autorización Electrónico)
+ */
+interface CAEResponse {
+    /** Tipo de comprobante */
+    tipoComprobante: number;
+    /** Punto de venta */
+    puntoVenta: number;
+    /** Número de comprobante */
+    nroComprobante: number;
+    /** Fecha de emisión */
+    fecha: string;
+    /** CAE asignado */
+    cae: string;
+    /** Fecha de vencimiento del CAE */
+    vencimientoCae: string;
+    /** Resultado (A = Aprobado, R = Rechazado) */
+    resultado: 'A' | 'R';
+    /** Observaciones de ARCA (si hay) */
+    observaciones?: string[];
+    /** Items (se retornan si fueron proveídos en el request) */
+    items?: FacturaItem[];
+    /** Desglose IVA (solo para Factura B/A) */
+    iva?: {
+        alicuota: number;
+        baseImponible: number;
+        importe: number;
+    }[];
+}
+
+/**
+ * Servicio de Facturación Electrónica (WSFE v1)
+ *
+ * @example
+ * ```typescript
+ * const wsfe = new WsfeService({
+ *   environment: 'homologacion',
+ *   cuit: '20123456789',
+ *   ticket: await wsaa.login(),
+ *   puntoVenta: 4,
+ * });
+ *
+ * const cae = await wsfe.emitirFacturaC({
+ *   items: [
+ *     { descripcion: 'Producto 1', cantidad: 2, precioUnitario: 100 }
+ *   ]
+ * });
+ *
+ * console.log('CAE:', cae.cae);
+ * ```
+ */
+declare class WsfeService {
+    private config;
+    constructor(config: WsfeConfig);
+    private validateConfig;
+    /**
+     * Emite un Ticket C de forma simple (solo total)
+     * Tipo de comprobante: 83
+     */
+    emitirTicketCSimple(params: {
+        total: number;
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite un Ticket C completo (con detalle de items)
+     * Los items no se envían a ARCA, pero se retornan en la respuesta.
+     */
+    emitirTicketC(params: {
+        items: FacturaItem[];
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite una Factura B (monotributo a responsable inscripto)
+     * REQUIERE detalle de items con IVA discriminado
+     */
+    emitirFacturaB(params: {
+        items: FacturaItem[];
+        comprador: Comprador;
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite una Factura A (RI a RI)
+     * REQUIERE detalle de items con IVA discriminado
+     */
+    emitirFacturaA(params: {
+        items: FacturaItem[];
+        comprador: Comprador;
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Valida que todos los items tengan alícuota IVA definida
+     */
+    private validateItemsWithIVA;
+    /**
+     * Calcula IVA agrupado por alícuota
+     * ARCA requiere esto para Factura B/A
+     */
+    private calcularIVAPorAlicuota;
+    /**
+     * Emite una Factura C (consumidor final)
+     * Forma simplificada sin especificar comprador
+     */
+    emitirFacturaC(params: {
+        items: FacturaItem[];
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite un comprobante (método genérico interno)
+     */
+    emitirComprobante(request: EmitirFacturaRequest): Promise<CAEResponse>;
+    /**
+     * Obtiene el próximo número de comprobante disponible
+     */
+    private obtenerProximoNumero;
+    private buildCAESolicitarRequest;
+    /**
+     * Mapea alícuota % a código ARCA
+     */
+    private getCodigoAlicuota;
+    private buildProximoNumeroRequest;
+    private parseCAEResponse;
+}
+
+export { ArcaAuthError, type ArcaConfig, ArcaError, ArcaValidationError, type CAEResponse, type Comprador, Concepto, type EmitirFacturaRequest, type Environment, type FacturaItem, type LoginTicket, TipoComprobante, TipoDocumento, type WsaaConfig, WsaaService, type WsfeConfig, WsfeService };

package/dist/index.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Tipos comunes compartidos en toda la SDK
+ */
+/**
+ * Ambiente de ejecución ARCA
+ */
+type Environment = 'homologacion' | 'produccion';
+/**
+ * Configuración base para servicios ARCA
+ */
+interface ArcaConfig {
+    /** Ambiente (homologación o producción) */
+    environment: Environment;
+    /** CUIT del contribuyente (11 dígitos sin guiones) */
+    cuit: string;
+}
+/**
+ * Error personalizado de ARCA SDK
+ */
+declare class ArcaError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Error de autenticación WSAA
+ */
+declare class ArcaAuthError extends ArcaError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Error de validación de input
+ */
+declare class ArcaValidationError extends ArcaError {
+    constructor(message: string, details?: unknown);
+}
+
+/**
+ * Configuración para WSAA
+ */
+interface WsaaConfig extends ArcaConfig {
+    /** Certificado X.509 en formato PEM */
+    cert: string;
+    /** Clave privada en formato PEM */
+    key: string;
+    /** Servicio ARCA a autenticar (ej: 'wsfe', 'wsmtxca') */
+    service: string;
+}
+/**
+ * Ticket de acceso obtenido de WSAA
+ */
+interface LoginTicket {
+    /** Token de autenticación */
+    token: string;
+    /** Firma del token */
+    sign: string;
+    /** Fecha de generación (ISO 8601) */
+    generationTime: Date;
+    /** Fecha de expiración (ISO 8601) */
+    expirationTime: Date;
+}
+
+/**
+ * Servicio de autenticación WSAA (Web Service de Autenticación y Autorización)
+ *
+ * @example
+ * ```typescript
+ * const wsaa = new WsaaService({
+ *   environment: 'homologacion',
+ *   cuit: '20123456789',
+ *   cert: fs.readFileSync('cert.pem', 'utf-8'),
+ *   key: fs.readFileSync('key.pem', 'utf-8'),
+ *   service: 'wsfe',
+ * });
+ *
+ * const ticket = await wsaa.login();
+ * console.log('Token:', ticket.token);
+ * ```
+ */
+declare class WsaaService {
+    private config;
+    private ticketManager;
+    constructor(config: WsaaConfig);
+    /**
+     * Valida la configuración
+     */
+    private validateConfig;
+    /**
+     * Obtiene un ticket de acceso válido
+     * Usa cache si el ticket actual es válido
+     *
+     * @returns Ticket de acceso
+     */
+    login(): Promise<LoginTicket>;
+    /**
+     * Solicita un nuevo ticket a WSAA
+     */
+    private requestNewTicket;
+    /**
+     * Construye el SOAP request para WSAA
+     */
+    private buildSoapRequest;
+    /**
+     * Limpia el ticket en cache (forzar renovación)
+     */
+    clearCache(): void;
+}
+
+/**
+ * Configuración para WSFE
+ */
+interface WsfeConfig extends ArcaConfig {
+    /** Ticket de autenticación WSAA */
+    ticket: LoginTicket;
+    /** Punto de venta (4 dígitos) */
+    puntoVenta: number;
+}
+/**
+ * Tipo de comprobante
+ */
+declare enum TipoComprobante {
+    FACTURA_A = 1,
+    FACTURA_B = 6,
+    FACTURA_C = 11,
+    TICKET_A = 81,
+    TICKET_B = 82,
+    TICKET_C = 83
+}
+/**
+ * Concepto de facturación
+ */
+declare enum Concepto {
+    PRODUCTOS = 1,// Productos
+    SERVICIOS = 2,// Servicios
+    PRODUCTOS_Y_SERVICIOS = 3
+}
+/**
+ * Tipo de documento del cliente
+ */
+declare enum TipoDocumento {
+    CUIT = 80,
+    CUIL = 86,
+    CDI = 87,
+    LE = 89,
+    LC = 90,
+    CI_EXTRANJERA = 91,
+    PASAPORTE = 94,
+    CI_BUENOS_AIRES = 95,
+    CI_POLICIA_FEDERAL = 96,
+    DNI = 96,
+    CONSUMIDOR_FINAL = 99
+}
+/**
+ * Item de factura
+ */
+interface FacturaItem {
+    /** Descripción del producto/servicio */
+    descripcion: string;
+    /** Cantidad */
+    cantidad: number;
+    /** Precio unitario */
+    precioUnitario: number;
+    /** IVA % (0, 10.5, 21, 27) */
+    alicuotaIva?: number;
+}
+/**
+ * Datos del comprador
+ */
+interface Comprador {
+    /** Tipo de documento */
+    tipoDocumento: TipoDocumento;
+    /** Número de documento (sin guiones) */
+    nroDocumento: string;
+}
+/**
+ * Request para emitir factura
+ */
+interface EmitirFacturaRequest {
+    /** Tipo de comprobante */
+    tipo: TipoComprobante;
+    /** Concepto */
+    concepto: Concepto;
+    /** Comprador (opcional para Factura C consumidor final) */
+    comprador?: Comprador;
+    /** Items de la factura (calculan el total si se proveen) */
+    items?: FacturaItem[];
+    /** Monto total (requerido si no hay items) */
+    total?: number;
+    /** Desglose de IVA (requerido para Factura B/A) */
+    ivaData?: {
+        alicuota: number;
+        baseImponible: number;
+        importe: number;
+    }[];
+    /** Fecha del comprobante (default: hoy) */
+    fecha?: Date;
+}
+/**
+ * Respuesta CAE (Código de Autorización Electrónico)
+ */
+interface CAEResponse {
+    /** Tipo de comprobante */
+    tipoComprobante: number;
+    /** Punto de venta */
+    puntoVenta: number;
+    /** Número de comprobante */
+    nroComprobante: number;
+    /** Fecha de emisión */
+    fecha: string;
+    /** CAE asignado */
+    cae: string;
+    /** Fecha de vencimiento del CAE */
+    vencimientoCae: string;
+    /** Resultado (A = Aprobado, R = Rechazado) */
+    resultado: 'A' | 'R';
+    /** Observaciones de ARCA (si hay) */
+    observaciones?: string[];
+    /** Items (se retornan si fueron proveídos en el request) */
+    items?: FacturaItem[];
+    /** Desglose IVA (solo para Factura B/A) */
+    iva?: {
+        alicuota: number;
+        baseImponible: number;
+        importe: number;
+    }[];
+}
+
+/**
+ * Servicio de Facturación Electrónica (WSFE v1)
+ *
+ * @example
+ * ```typescript
+ * const wsfe = new WsfeService({
+ *   environment: 'homologacion',
+ *   cuit: '20123456789',
+ *   ticket: await wsaa.login(),
+ *   puntoVenta: 4,
+ * });
+ *
+ * const cae = await wsfe.emitirFacturaC({
+ *   items: [
+ *     { descripcion: 'Producto 1', cantidad: 2, precioUnitario: 100 }
+ *   ]
+ * });
+ *
+ * console.log('CAE:', cae.cae);
+ * ```
+ */
+declare class WsfeService {
+    private config;
+    constructor(config: WsfeConfig);
+    private validateConfig;
+    /**
+     * Emite un Ticket C de forma simple (solo total)
+     * Tipo de comprobante: 83
+     */
+    emitirTicketCSimple(params: {
+        total: number;
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite un Ticket C completo (con detalle de items)
+     * Los items no se envían a ARCA, pero se retornan en la respuesta.
+     */
+    emitirTicketC(params: {
+        items: FacturaItem[];
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite una Factura B (monotributo a responsable inscripto)
+     * REQUIERE detalle de items con IVA discriminado
+     */
+    emitirFacturaB(params: {
+        items: FacturaItem[];
+        comprador: Comprador;
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite una Factura A (RI a RI)
+     * REQUIERE detalle de items con IVA discriminado
+     */
+    emitirFacturaA(params: {
+        items: FacturaItem[];
+        comprador: Comprador;
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Valida que todos los items tengan alícuota IVA definida
+     */
+    private validateItemsWithIVA;
+    /**
+     * Calcula IVA agrupado por alícuota
+     * ARCA requiere esto para Factura B/A
+     */
+    private calcularIVAPorAlicuota;
+    /**
+     * Emite una Factura C (consumidor final)
+     * Forma simplificada sin especificar comprador
+     */
+    emitirFacturaC(params: {
+        items: FacturaItem[];
+        concepto?: Concepto;
+        fecha?: Date;
+    }): Promise<CAEResponse>;
+    /**
+     * Emite un comprobante (método genérico interno)
+     */
+    emitirComprobante(request: EmitirFacturaRequest): Promise<CAEResponse>;
+    /**
+     * Obtiene el próximo número de comprobante disponible
+     */
+    private obtenerProximoNumero;
+    private buildCAESolicitarRequest;
+    /**
+     * Mapea alícuota % a código ARCA
+     */
+    private getCodigoAlicuota;
+    private buildProximoNumeroRequest;
+    private parseCAEResponse;
+}
+
+export { ArcaAuthError, type ArcaConfig, ArcaError, ArcaValidationError, type CAEResponse, type Comprador, Concepto, type EmitirFacturaRequest, type Environment, type FacturaItem, type LoginTicket, TipoComprobante, TipoDocumento, type WsaaConfig, WsaaService, type WsfeConfig, WsfeService };