arca-sdk 0.5.0 → 1.0.0

package/dist/index.d.cts

@@ -37,6 +37,12 @@ declare class ArcaAuthError extends ArcaError {
 declare class ArcaValidationError extends ArcaError {
     constructor(message: string, details?: unknown);
 }
+/**
+ * Error de comunicación/red
+ */
+declare class ArcaNetworkError extends ArcaError {
+    constructor(message: string, details?: unknown);
+}
 
 /**
  * Interface for token persistence.
@@ -56,7 +62,7 @@ interface TokenStorage {
 }
 
 /**
- * Configuración para WSAA
+ * Configuración para WsaaService
  */
 interface WsaaConfig extends ArcaConfig {
     /** Certificado X.509 en formato PEM */
@@ -76,9 +82,9 @@ interface LoginTicket {
     token: string;
     /** Firma del token */
     sign: string;
-    /** Fecha de generación (ISO 8601) */
+    /** Fecha de generación */
     generationTime: Date;
-    /** Fecha de expiración (ISO 8601) */
+    /** Fecha de expiración */
     expirationTime: Date;
 }
 
@@ -133,18 +139,18 @@ declare class WsaaService {
 }
 
 /**
- * Configuración para WSFE
+ * Configuración para WsfeService
  */
 interface WsfeConfig extends ArcaConfig {
     /** Ticket de autenticación WSAA */
     ticket: LoginTicket;
-    /** Punto de venta (4 dígitos) */
-    puntoVenta: number;
+    /** Punto de venta (1-9999) */
+    pointOfSale: number;
 }
 /**
- * Tipo de comprobante
+ * Tipo de comprobante ARCA
  */
-declare enum TipoComprobante {
+declare enum InvoiceType {
     FACTURA_A = 1,
     FACTURA_B = 6,
     FACTURA_C = 11,
@@ -155,119 +161,167 @@ declare enum TipoComprobante {
 /**
  * Concepto de facturación
  */
-declare enum Concepto {
-    PRODUCTOS = 1,// Productos
-    SERVICIOS = 2,// Servicios
-    PRODUCTOS_Y_SERVICIOS = 3
+declare enum BillingConcept {
+    PRODUCTS = 1,
+    SERVICES = 2,
+    PRODUCTS_AND_SERVICES = 3
 }
 /**
- * Tipo de documento del cliente
+ * Tipo de documento del receptor
  */
-declare enum TipoDocumento {
+declare enum TaxIdType {
     CUIT = 80,
     CUIL = 86,
     CDI = 87,
     LE = 89,
     LC = 90,
-    CI_EXTRANJERA = 91,
-    PASAPORTE = 94,
-    CI_BUENOS_AIRES = 95,
-    CI_POLICIA_FEDERAL = 96,
+    FOREIGN_ID = 91,
+    PASSPORT = 94,
+    BUENOS_AIRES_ID = 95,
+    /**
+     * @note AFIP usa el código 96 para ambos. En la práctica, DNI es el más utilizado.
+     * Fuente: Tabla 13 del catálogo ARCA — ambos valores son 96 en el catálogo oficial.
+     */
+    NATIONAL_POLICE_ID = 96,
     DNI = 96,
-    CONSUMIDOR_FINAL = 99
+    FINAL_CONSUMER = 99
 }
 /**
- * Item de factura
+ * Ítem de factura
  */
-interface FacturaItem {
+interface InvoiceItem {
     /** Descripción del producto/servicio */
-    descripcion: string;
+    description: string;
     /** Cantidad */
-    cantidad: number;
+    quantity: number;
     /** Precio unitario */
-    precioUnitario: number;
-    /** IVA % (0, 10.5, 21, 27) */
-    alicuotaIva?: number;
+    unitPrice: number;
+    /** Alícuota IVA % (0, 10.5, 21, 27) */
+    vatRate?: number;
 }
 /**
  * Datos del comprador
  */
-interface Comprador {
+interface Buyer {
     /** Tipo de documento */
-    tipoDocumento: TipoDocumento;
+    docType: TaxIdType;
     /** Número de documento (sin guiones) */
-    nroDocumento: string;
+    docNumber: string;
 }
 /**
- * Request para emitir factura
+ * Request para emitir comprobante
  */
-interface EmitirFacturaRequest {
+interface IssueInvoiceRequest {
     /** Tipo de comprobante */
-    tipo: TipoComprobante;
+    type: InvoiceType;
     /** Concepto */
-    concepto: Concepto;
+    concept: BillingConcept;
     /** Comprador (opcional para Factura C consumidor final) */
-    comprador?: Comprador;
-    /** Items de la factura (calculan el total si se proveen) */
-    items?: FacturaItem[];
+    buyer?: Buyer;
+    /** Items de la factura */
+    items?: InvoiceItem[];
     /** Monto total (requerido si no hay items) */
     total?: number;
-    /** Desglose de IVA (requerido para Factura B/A) */
-    ivaData?: {
-        alicuota: number;
-        baseImponible: number;
-        importe: number;
+    /** Desglose de IVA (requerido para Factura A/B) */
+    vatData?: {
+        rate: number;
+        taxBase: number;
+        amount: number;
     }[];
-    /** Indica si los preciosUnitarios de los items YA incluyen el IVA (Precio Final). Defecto: false */
-    incluyeIva?: boolean;
+    /** Indica si los precios unitarios YA incluyen el IVA. Defecto: false */
+    includesVAT?: boolean;
     /** Fecha del comprobante (default: hoy) */
-    fecha?: Date;
+    date?: Date;
 }
 /**
  * Respuesta CAE (Código de Autorización Electrónico)
  */
 interface CAEResponse {
     /** Tipo de comprobante */
-    tipoComprobante: number;
+    invoiceType: number;
     /** Punto de venta */
-    puntoVenta: number;
+    pointOfSale: number;
     /** Número de comprobante */
-    nroComprobante: number;
-    /** Fecha de emisión */
-    fecha: string;
+    invoiceNumber: number;
+    /** Fecha de emisión (YYYYMMDD) */
+    date: string;
     /** CAE asignado */
     cae: string;
-    /** Fecha de vencimiento del CAE */
-    vencimientoCae: string;
+    /** Fecha de vencimiento del CAE (YYYYMMDD) */
+    caeExpiry: string;
     /** Resultado (A = Aprobado, R = Rechazado) */
-    resultado: 'A' | 'R';
-    /** Observaciones de ARCA (si hay) */
-    observaciones?: string[];
+    result: 'A' | 'R';
+    /** Observaciones de ARCA */
+    observations?: 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;
+    items?: InvoiceItem[];
+    /** Desglose IVA (solo para Factura A/B) */
+    vat?: {
+        rate: number;
+        taxBase: number;
+        amount: number;
     }[];
     /** URL del código QR oficial de ARCA */
-    urlQr?: string;
+    qrUrl?: string;
+}
+/**
+ * Detalle de un comprobante consultado (FECompConsultar)
+ */
+interface InvoiceDetails {
+    /** Tipo de comprobante */
+    invoiceType: number;
+    /** Punto de venta */
+    pointOfSale: number;
+    /** Número de comprobante */
+    invoiceNumber: number;
+    /** Fecha de emisión (YYYYMMDD) */
+    date: string;
+    /** Concepto */
+    concept: number;
+    /** Tipo de documento del receptor */
+    docType: number;
+    /** Número de documento del receptor */
+    docNumber: number;
+    /** Importe total */
+    total: number;
+    /** Importe neto gravado */
+    net: number;
+    /** Importe IVA */
+    vat: number;
+    /** CAE */
+    cae: string;
+    /** Vencimiento CAE (YYYYMMDD) */
+    caeExpiry: string;
+    /** Resultado */
+    result: 'A' | 'R';
+}
+/**
+ * Punto de venta habilitado en ARCA
+ */
+interface PointOfSale {
+    /** Número de punto de venta */
+    number: number;
+    /** Tipo (CAI, CAE, CAEA, etc.) */
+    type: string;
+    /** Indica si está bloqueado */
+    isBlocked: boolean;
+    /** Fecha de bloqueo (si aplica) */
+    blockedSince?: string;
 }
 /**
  * Estado de los servidores de ARCA
  */
 interface ServiceStatus {
     /** Estado del servidor de aplicaciones */
-    AppServer: string;
+    appServer: string;
     /** Estado del servidor de base de datos */
-    DbServer: string;
+    dbServer: string;
     /** Estado del servidor de autenticación */
-    AuthServer: string;
+    authServer: string;
 }
 
 /**
- * Servicio de Facturación Electrónica (WSFE v1)
+ * Servicio de Facturación Electrónica WSFE v1
  *
  * @example
  * ```typescript
@@ -275,16 +329,19 @@ interface ServiceStatus {
  *   environment: 'homologacion',
  *   cuit: '20123456789',
  *   ticket: await wsaa.login(),
- *   puntoVenta: 4,
- * });
- *
- * const cae = await wsfe.emitirFacturaC({
- *   items: [
- *     { descripcion: 'Producto 1', cantidad: 2, precioUnitario: 100 }
- *   ]
+ *   pointOfSale: 4,
  * });
  *
+ * // Ticket C rápido
+ * const cae = await wsfe.issueSimpleReceipt({ total: 1500 });
  * console.log('CAE:', cae.cae);
+ * console.log('QR:', cae.qrUrl);
+ *
+ * // Factura A/B con IVA discriminado
+ * const cae = await wsfe.issueInvoiceB({
+ *   items: [{ description: 'Servicio', quantity: 1, unitPrice: 1000, vatRate: 21 }],
+ *   buyer: { docType: TaxIdType.CUIT, docNumber: '20987654321' },
+ * });
  * ```
  */
 declare class WsfeService {
@@ -292,94 +349,105 @@ declare class WsfeService {
     constructor(config: WsfeConfig);
     private validateConfig;
     /**
-     * Emite un Ticket C de forma simple (solo total)
-     * Tipo de comprobante: 83
+     * Verifica el estado de los servidores de ARCA (FEDummy).
+     * No requiere autenticación. Útil para health checks.
+     *
+     * @param environment Ambiente a consultar (default: 'homologacion')
      */
-    emitirTicketCSimple(params: {
+    static checkStatus(environment?: 'homologacion' | 'produccion'): Promise<ServiceStatus>;
+    /**
+     * Verifica el estado de los servidores de ARCA.
+     * Versión de instancia — usa el ambiente configurado.
+     */
+    checkStatus(): Promise<ServiceStatus>;
+    /**
+     * Emite un Ticket C simple (solo monto total, sin detalle de items).
+     * Ideal para registros mínimos, como una app móvil de punto de venta.
+     */
+    issueSimpleReceipt(params: {
         total: number;
-        concepto?: Concepto;
-        fecha?: Date;
+        concept?: BillingConcept;
+        date?: Date;
     }): Promise<CAEResponse>;
     /**
-     * Verifica el estado de los servidores de ARCA (FEDummy)
-     * No requiere autenticación ni instancia configurada.
+     * Emite un Ticket C con detalle de items.
+     * Los items se guardan en la respuesta pero no se envían a ARCA.
      */
-    static checkStatus(environment?: 'homologacion' | 'produccion'): Promise<ServiceStatus>;
+    issueReceipt(params: {
+        items: InvoiceItem[];
+        concept?: BillingConcept;
+        date?: Date;
+    }): Promise<CAEResponse>;
     /**
-     * Verifica el estado de los servidores de ARCA (FEDummy)
-     * No requiere autenticación.
+     * Emite una Factura C (consumidor final, sin discriminación de IVA).
      */
-    checkStatus(): Promise<ServiceStatus>;
+    issueInvoiceC(params: {
+        items: InvoiceItem[];
+        concept?: BillingConcept;
+        date?: 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.
+     * Emite una Factura B (con IVA discriminado).
+     * REQUIERE `vatRate` en todos los items.
      */
-    emitirTicketC(params: {
-        items: FacturaItem[];
-        concepto?: Concepto;
-        fecha?: Date;
+    issueInvoiceB(params: {
+        items: InvoiceItem[];
+        buyer: Buyer;
+        concept?: BillingConcept;
+        date?: Date;
+        includesVAT?: boolean;
     }): Promise<CAEResponse>;
     /**
-     * Emite una Factura B (monotributo a responsable inscripto)
-     * REQUIERE detalle de items con IVA discriminado
+     * Emite una Factura A (Responsable Inscripto a Responsable Inscripto, con IVA discriminado).
+     * REQUIERE `vatRate` en todos los items.
      */
-    emitirFacturaB(params: {
-        items: FacturaItem[];
-        comprador: Comprador;
-        concepto?: Concepto;
-        fecha?: Date;
-        incluyeIva?: boolean;
+    issueInvoiceA(params: {
+        items: InvoiceItem[];
+        buyer: Buyer;
+        concept?: BillingConcept;
+        date?: Date;
+        includesVAT?: boolean;
     }): Promise<CAEResponse>;
     /**
-     * Emite una Factura A (RI a RI)
-     * REQUIERE detalle de items con IVA discriminado
+     * Consulta un comprobante ya emitido (FECompConsultar).
+     *
+     * @param type Tipo de comprobante
+     * @param invoiceNumber Número de comprobante
      */
-    emitirFacturaA(params: {
-        items: FacturaItem[];
-        comprador: Comprador;
-        concepto?: Concepto;
-        fecha?: Date;
-        incluyeIva?: boolean;
-    }): Promise<CAEResponse>;
+    getInvoice(type: InvoiceType, invoiceNumber: number): Promise<InvoiceDetails>;
     /**
-     * Valida que todos los items tengan alícuota IVA definida
+     * Lista los puntos de venta habilitados para el CUIT autenticado (FEParamGetPtosVenta).
      */
-    private validateItemsWithIVA;
+    getPointsOfSale(): Promise<PointOfSale[]>;
     /**
-     * Calcula IVA agrupado por alícuota
-     * ARCA requiere esto para Factura B/A
+     * Método genérico interno para emitir cualquier tipo de comprobante.
      */
-    private calcularIVAPorAlicuota;
+    private issueDocument;
     /**
-     * Emite una Factura C (consumidor final)
-     * Forma simplificada sin especificar comprador
+     * Obtiene el próximo número de comprobante disponible (FECompUltimoAutorizado + 1)
      */
-    emitirFacturaC(params: {
-        items: FacturaItem[];
-        concepto?: Concepto;
-        fecha?: Date;
-    }): Promise<CAEResponse>;
+    private getNextInvoiceNumber;
     /**
-     * Emite un comprobante (método genérico interno)
+     * Valida que todos los items tengan alícuota IVA definida
      */
-    emitirComprobante(request: EmitirFacturaRequest): Promise<CAEResponse>;
+    private validateItemsWithVAT;
     /**
-     * Obtiene el próximo número de comprobante disponible
+     * Calcula el IVA agrupado por alícuota (requerido por ARCA para Factura A/B)
      */
-    private obtenerProximoNumero;
-    private buildCAESolicitarRequest;
+    private calculateVATByRate;
     /**
-     * Mapea alícuota % a código ARCA
+     * Mapea alícuota % al código interno de ARCA
      */
-    private getCodigoAlicuota;
-    private buildProximoNumeroRequest;
+    private getVATCode;
+    private buildCAERequest;
+    private buildLastInvoiceRequest;
     private parseCAEResponse;
 }
 
 /**
  * Configuración para PadronService
  */
-interface PadronConfig extends ArcaConfig {
+interface TaxpayerServiceConfig extends ArcaConfig {
     /** CUIT del emisor (quien consulta) */
     cuit: string;
     /** Certificado X.509 en formato PEM */
@@ -392,95 +460,119 @@ interface PadronConfig extends ArcaConfig {
 /**
  * Actividad económica según AFIP
  */
-interface Actividad {
-    idActividad: number;
-    descripcion: string;
-    orden: number;
-    periodo: number;
+interface Activity {
+    id: number;
+    description: string;
+    order: number;
+    period: number;
 }
 /**
  * Impuesto registrado en AFIP
  */
-interface Impuesto {
-    idImpuesto: number;
-    descripcion: string;
-    periodo: number;
+interface TaxRecord {
+    id: number;
+    description: string;
+    period: number;
 }
 /**
- * Representa una persona (física o jurídica) obtenida del Padrón A13
+ * Domicilio registrado en AFIP
  */
-interface Persona {
-    idPersona: number;
-    tipoPersona: 'FISICA' | 'JURIDICA';
-    nombre?: string;
-    apellido?: string;
-    razonSocial?: string;
-    estadoClave: string;
-    domicilio: Domicilio[];
-    actividad?: Actividad[];
-    impuesto?: Impuesto[];
-    descripcionActividadPrincipal?: string;
-    esInscriptoIVA: boolean;
-    esMonotributista: boolean;
-    esExento: boolean;
+interface Address {
+    street: string;
+    city?: string;
+    postalCode?: string;
+    provinceId: number;
+    province: string;
+    /** Tipo: FISCAL, LEGAL, etc. */
+    type: string;
 }
 /**
- * Domicilio registrado en ARCA
+ * Persona (física o jurídica) obtenida del Padrón A13
  */
-interface Domicilio {
-    direccion: string;
-    localidad?: string;
-    codPostal?: string;
-    idProvincia: number;
-    descripcionProvincia: string;
-    tipoDomicilio: string;
+interface Taxpayer {
+    taxId: number;
+    personType: 'FISICA' | 'JURIDICA';
+    /** Nombre (persona física) */
+    firstName?: string;
+    /** Apellido (persona física) */
+    lastName?: string;
+    /** Razón social (persona jurídica) */
+    companyName?: string;
+    /** Estado de la clave fiscal */
+    status: string;
+    addresses: Address[];
+    activities?: Activity[];
+    taxes?: TaxRecord[];
+    mainActivity?: string;
+    /** ¿Está inscripto en IVA? */
+    isVATRegistered: boolean;
+    /** ¿Es monotributista? */
+    isMonotax: boolean;
+    /** ¿Es exento de IVA? */
+    isVATExempt: boolean;
 }
 /**
  * Respuesta del servicio de Padrón
  */
-interface PadronResponse {
-    persona?: Persona;
+interface TaxpayerResponse {
+    taxpayer?: Taxpayer;
     error?: string;
 }
 
 /**
  * Servicio para consultar el Padrón de AFIP (ws_sr_padron_a13)
+ *
+ * @example
+ * ```typescript
+ * const padron = new PadronService({
+ *   environment: 'homologacion',
+ *   cuit: '20123456789',
+ *   cert: fs.readFileSync('cert.pem', 'utf-8'),
+ *   key: fs.readFileSync('key.pem', 'utf-8'),
+ * });
+ *
+ * const { taxpayer, error } = await padron.getTaxpayer('30111111118');
+ * if (taxpayer) {
+ *   console.log(taxpayer.companyName || `${taxpayer.firstName} ${taxpayer.lastName}`);
+ *   console.log('¿Inscripto IVA?:', taxpayer.isVATRegistered);
+ * }
+ * ```
  */
 declare class PadronService {
     private wsaa;
     private config;
-    constructor(config: PadronConfig);
+    constructor(config: TaxpayerServiceConfig);
     /**
-     * Consulta los datos de una persona por CUIT
+     * Consulta los datos de un contribuyente por CUIT
      *
-     * @param idPersona CUIT a consultar
-     * @returns Datos de la persona o error
+     * @param taxId CUIT a consultar (11 dígitos sin guiones)
+     * @returns Datos del contribuyente o mensaje de error
      */
-    getPersona(idPersona: string): Promise<PadronResponse>;
+    getTaxpayer(taxId: string): Promise<TaxpayerResponse>;
     /**
-     * Parsear la respuesta XML de getPersona
+     * Parsea la respuesta XML de getPersona
      */
     private parseResponse;
-    private mapDomicilios;
-    private mapActividades;
-    private mapImpuestos;
-    private checkImpuesto;
+    private mapAddresses;
+    private mapActivities;
+    private mapTaxRecords;
+    private hasTaxId;
     /**
-     * Helper para normalizar la respuesta de XML que puede ser objeto único o array
+     * Normaliza un valor que puede ser un objeto único o un array (comportamiento de fast-xml-parser)
      */
-    private ensureArray;
+    private toArray;
 }
 
 /**
  * Genera la URL completa con el código QR para un comprobante emitido.
- * Implementación robusta (Versión 11) que limpia inputs y asegura compatibilidad total con ARCA.
+ * Implementa la versión oficial con orden estricto de campos según spec de ARCA.
  *
  * @param caeResponse Respuesta obtenida al emitir la factura (CAEResponse)
- * @param cuitEmisor Tu CUIT (con o sin guiones)
+ * @param issuerCUIT CUIT del emisor (con o sin guiones)
  * @param total Importe total del comprobante
- * @param comprador Datos del comprador (opcional)
- * @returns La URL lista para embeber en un generador de QR
+ * @param buyer Datos del comprador (opcional)
+ * @returns URL lista para embeber en un generador de QR
  */
-declare function generarUrlQR(caeResponse: CAEResponse, cuitEmisor: string, total: number, comprador?: Comprador): string;
+declare function generateQRUrl(caeResponse: CAEResponse, issuerCUIT: string, total: number, buyer?: Buyer): string;
 
-export { ArcaAuthError, type ArcaConfig, ArcaError, ArcaValidationError, type CAEResponse, type Comprador, Concepto, type Domicilio, type EmitirFacturaRequest, type Environment, type FacturaItem, type LoginTicket, type PadronConfig, type PadronResponse, PadronService, type Persona, TipoComprobante, TipoDocumento, type TokenStorage, type WsaaConfig, WsaaService, type WsfeConfig, WsfeService, generarUrlQR };
+export { type Activity, type Address, ArcaAuthError, type ArcaConfig, ArcaError, ArcaNetworkError, ArcaValidationError, BillingConcept, type Buyer, type CAEResponse, type Environment, type InvoiceDetails, type InvoiceItem, InvoiceType, type IssueInvoiceRequest, type LoginTicket, PadronService, type PointOfSale, type ServiceStatus, TaxIdType, type TaxRecord, type Taxpayer, type TaxpayerResponse, type TaxpayerServiceConfig, type TokenStorage, type WsaaConfig, WsaaService, type WsfeConfig, WsfeService, generateQRUrl };