@devlas/dte-sii 2.5.0

package/utils/emisor.js

@@ -0,0 +1,174 @@
+// Copyright (c) 2026 Devlas SpA — https://devlas.cl
+// Licencia MIT. Ver archivo LICENSE para mas detalles.
+/**
+ * Utilidades de Emisor
+ * 
+ * Funciones para construir y validar datos de emisor en DTEs
+ * 
+ * @module dte-sii/utils/emisor
+ */
+
+const { sanitizeSiiText } = require('./sanitize');
+const { formatRutSii, validarRut } = require('./rut');
+
+// ============================================
+// CONSTRUCCIÓN DE EMISOR
+// ============================================
+
+/**
+ * Construye objeto de Emisor para DTE (no boleta)
+ * 
+ * @param {Object} config - Configuración del emisor
+ * @param {string} config.rut - RUT del emisor
+ * @param {string} config.razonSocial - Razón social
+ * @param {string} config.giro - Giro comercial
+ * @param {string} config.direccion - Dirección
+ * @param {string} config.comuna - Comuna
+ * @param {string} [config.ciudad] - Ciudad (default: comuna)
+ * @param {string} [config.telefono] - Teléfono
+ * @param {string} [config.correo] - Correo electrónico
+ * @param {number|string} [config.acteco] - Código de actividad económica
+ * @returns {Object} Emisor formateado para DTE
+ */
+function buildEmisor(config) {
+  const {
+    rut,
+    razonSocial,
+    giro,
+    direccion,
+    comuna,
+    ciudad,
+    telefono,
+    correo,
+    acteco,
+  } = config;
+
+  const emisor = {
+    RUTEmisor: formatRutSii(rut),
+    RznSoc: sanitizeSiiText(razonSocial),
+    GiroEmis: sanitizeSiiText(giro),
+  };
+
+  if (acteco) emisor.Acteco = acteco;
+  if (telefono) emisor.Telefono = telefono;
+  if (correo) emisor.CorreoEmisor = correo;
+
+  emisor.DirOrigen = sanitizeSiiText(direccion);
+  emisor.CmnaOrigen = comuna;
+  emisor.CiudadOrigen = ciudad || comuna || '';
+
+  return emisor;
+}
+
+/**
+ * Construye objeto de Emisor para Boleta
+ * 
+ * @param {Object} config - Configuración del emisor
+ * @param {string} config.rut - RUT del emisor
+ * @param {string} config.razonSocial - Razón social
+ * @param {string} config.giro - Giro comercial
+ * @param {string} config.direccion - Dirección
+ * @param {string} config.comuna - Comuna
+ * @param {string} [config.ciudad] - Ciudad
+ * @returns {Object} Emisor formateado para Boleta
+ */
+function buildEmisorBoleta(config) {
+  const { rut, razonSocial, giro, direccion, comuna, ciudad } = config;
+
+  return {
+    RUTEmisor: formatRutSii(rut),
+    RznSocEmisor: sanitizeSiiText(razonSocial),
+    GiroEmisor: sanitizeSiiText(giro),
+    DirOrigen: sanitizeSiiText(direccion),
+    CmnaOrigen: comuna,
+    CiudadOrigen: ciudad || comuna || '',
+  };
+}
+
+/**
+ * Normaliza emisor desde diferentes formatos de entrada
+ * Detecta si viene en formato boleta o DTE y normaliza
+ * 
+ * @param {Object} emisor - Emisor en cualquier formato
+ * @param {boolean} [esBoleta=false] - Si es formato boleta
+ * @returns {Object} Emisor normalizado
+ */
+function normalizeEmisor(emisor, esBoleta = false) {
+  if (esBoleta) {
+    return {
+      RUTEmisor: emisor.RUTEmisor,
+      RznSocEmisor: sanitizeSiiText(emisor.RznSocEmisor || emisor.RznSoc),
+      GiroEmisor: sanitizeSiiText(emisor.GiroEmisor || emisor.GiroEmis),
+      DirOrigen: sanitizeSiiText(emisor.DirOrigen),
+      CmnaOrigen: emisor.CmnaOrigen,
+      CiudadOrigen: emisor.CiudadOrigen || emisor.CmnaOrigen || '',
+    };
+  }
+
+  const result = {
+    RUTEmisor: emisor.RUTEmisor,
+    RznSoc: sanitizeSiiText(emisor.RznSoc || emisor.RznSocEmisor),
+    GiroEmis: sanitizeSiiText(emisor.GiroEmis || emisor.GiroEmisor),
+  };
+
+  if (emisor.Acteco) result.Acteco = emisor.Acteco;
+  if (emisor.Telefono) result.Telefono = emisor.Telefono;
+  if (emisor.CorreoEmisor) result.CorreoEmisor = emisor.CorreoEmisor;
+
+  result.DirOrigen = sanitizeSiiText(emisor.DirOrigen);
+  result.CmnaOrigen = emisor.CmnaOrigen;
+  result.CiudadOrigen = emisor.CiudadOrigen || emisor.CmnaOrigen || '';
+
+  return result;
+}
+
+/**
+ * Valida datos de emisor
+ * 
+ * @param {Object} emisor - Datos del emisor
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validarEmisor(emisor) {
+  const errors = [];
+
+  if (!emisor) {
+    return { valid: false, errors: ['Emisor no proporcionado'] };
+  }
+
+  if (!emisor.RUTEmisor) {
+    errors.push('RUT de emisor requerido');
+  } else if (!validarRut(emisor.RUTEmisor)) {
+    errors.push('RUT de emisor inválido');
+  }
+
+  const razonSocial = emisor.RznSoc || emisor.RznSocEmisor;
+  if (!razonSocial) {
+    errors.push('Razón social requerida');
+  }
+
+  const giro = emisor.GiroEmis || emisor.GiroEmisor;
+  if (!giro) {
+    errors.push('Giro requerido');
+  }
+
+  if (!emisor.DirOrigen) {
+    errors.push('Dirección de origen requerida');
+  }
+
+  if (!emisor.CmnaOrigen) {
+    errors.push('Comuna de origen requerida');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+module.exports = {
+  buildEmisor,
+  buildEmisorBoleta,
+  normalizeEmisor,
+  validarEmisor,
+};

package/utils/endpoints.js

@@ -0,0 +1,225 @@
+// Copyright (c) 2026 Devlas SpA — https://devlas.cl
+// Licencia MIT. Ver archivo LICENSE para mas detalles.
+/**
+ * endpoints.js - URLs centralizadas del SII
+ * 
+ * Centraliza todas las URLs de los servicios del SII para evitar
+ * duplicación y facilitar el mantenimiento.
+ * 
+ * @module utils/endpoints
+ */
+
+/**
+ * Hosts base por ambiente
+ */
+const HOSTS = {
+  certificacion: 'maullin.sii.cl',
+  produccion: 'palena.sii.cl',
+};
+
+/**
+ * Hosts para API REST de Boletas
+ */
+const REST_HOSTS = {
+  certificacion: {
+    api: 'apicert.sii.cl',
+    envio: 'pangal.sii.cl',
+  },
+  produccion: {
+    api: 'api.sii.cl',
+    envio: 'rahue.sii.cl',
+  },
+};
+
+/**
+ * Endpoints SOAP para DTEUpload
+ */
+const SOAP_ENDPOINTS = {
+  certificacion: {
+    seed: 'https://maullin.sii.cl/DTEWS/CrSeed.jws',
+    token: 'https://maullin.sii.cl/DTEWS/GetTokenFromSeed.jws',
+    upload: 'https://maullin.sii.cl/cgi_dte/UPL/DTEUpload',
+    estado: 'https://maullin.sii.cl/DTEWS/QueryEstUp.jws',
+    estadoDte: 'https://maullin.sii.cl/DTEWS/QueryEstDte.jws',
+  },
+  produccion: {
+    seed: 'https://palena.sii.cl/DTEWS/CrSeed.jws',
+    token: 'https://palena.sii.cl/DTEWS/GetTokenFromSeed.jws',
+    upload: 'https://palena.sii.cl/cgi_dte/UPL/DTEUpload',
+    estado: 'https://palena.sii.cl/DTEWS/QueryEstUp.jws',
+    estadoDte: 'https://palena.sii.cl/DTEWS/QueryEstDte.jws',
+  },
+};
+
+/**
+ * Endpoints REST para Boletas Electrónicas
+ */
+const REST_ENDPOINTS = {
+  certificacion: {
+    semilla: 'https://apicert.sii.cl/recursos/v1/boleta.electronica.semilla',
+    token: 'https://apicert.sii.cl/recursos/v1/boleta.electronica.token',
+    envio: 'https://pangal.sii.cl/recursos/v1/boleta.electronica.envio',
+    estado: 'https://apicert.sii.cl/recursos/v1/boleta.electronica.envio/',
+  },
+  produccion: {
+    semilla: 'https://api.sii.cl/recursos/v1/boleta.electronica.semilla',
+    token: 'https://api.sii.cl/recursos/v1/boleta.electronica.token',
+    envio: 'https://rahue.sii.cl/recursos/v1/boleta.electronica.envio',
+    estado: 'https://api.sii.cl/recursos/v1/boleta.electronica.envio/',
+  },
+};
+
+/**
+ * Endpoints de Certificación (portal pe_*)
+ */
+const CERT_ENDPOINTS = {
+  // Generación de sets
+  generar: '/cvc_cgi/dte/pe_generar',
+  generar1: '/cvc_cgi/dte/pe_generar1',
+  
+  // Avance de certificación
+  avance1: '/cvc_cgi/dte/pe_avance1',
+  avance2: '/cvc_cgi/dte/pe_avance2',
+  avance5: '/cvc_cgi/dte/pe_avance5',
+  avance7: '/cvc_cgi/dte/pe_avance7',
+  
+  // CAF
+  solicitarFolios: '/cvc_cgi/dte/of_solicita_folios',
+  estadoFolios: '/cgi_dte/UPL/DTEauth?2',
+  anularFolios: '/cvc_cgi/dte/of_anular_caf',
+  
+  // Boletas Electrónicas
+  validarBoletaEnvio: '/cgi_dte/UPL/DTEauth?3',
+  
+  // Autenticación
+  ingresoRut: '/cvc_cgi/dte/pe_ingrut',
+  enrolaUsuarios: '/cvc_cgi/dte/eu_enrola_usuarios',
+  construccionDte: '/cvc_cgi/dte/pe_construccion_dte',
+};
+
+/**
+ * Obtener host base para un ambiente
+ * @param {string} ambiente - 'certificacion' o 'produccion'
+ * @returns {string} Host base (ej: 'maullin.sii.cl')
+ */
+function getHost(ambiente) {
+  const amb = String(ambiente).toLowerCase();
+  if (!HOSTS[amb]) {
+    throw new Error(`Ambiente inválido: ${ambiente}`);
+  }
+  return HOSTS[amb];
+}
+
+/**
+ * Obtener URL completa para endpoint SOAP
+ * @param {string} ambiente - 'certificacion' o 'produccion'
+ * @param {string} endpoint - Nombre del endpoint (seed, token, upload, estado)
+ * @returns {string} URL completa
+ */
+function getSoapUrl(ambiente, endpoint) {
+  const amb = String(ambiente).toLowerCase();
+  const urls = SOAP_ENDPOINTS[amb];
+  if (!urls) {
+    throw new Error(`Ambiente inválido: ${ambiente}`);
+  }
+  if (!urls[endpoint]) {
+    throw new Error(`Endpoint SOAP inválido: ${endpoint}`);
+  }
+  return urls[endpoint];
+}
+
+/**
+ * Obtener URL completa para endpoint REST (Boletas)
+ * @param {string} ambiente - 'certificacion' o 'produccion'
+ * @param {string} endpoint - Nombre del endpoint (semilla, token, envio, estado)
+ * @returns {string} URL completa
+ */
+function getRestUrl(ambiente, endpoint) {
+  const amb = String(ambiente).toLowerCase();
+  const urls = REST_ENDPOINTS[amb];
+  if (!urls) {
+    throw new Error(`Ambiente inválido: ${ambiente}`);
+  }
+  if (!urls[endpoint]) {
+    throw new Error(`Endpoint REST inválido: ${endpoint}`);
+  }
+  return urls[endpoint];
+}
+
+/**
+ * Obtener URL completa para endpoint de certificación
+ * @param {string} ambiente - 'certificacion' o 'produccion'
+ * @param {string} endpoint - Nombre del endpoint (generar, avance1, etc)
+ * @returns {string} URL completa
+ */
+function getCertUrl(ambiente, endpoint) {
+  const host = getHost(ambiente);
+  const path = CERT_ENDPOINTS[endpoint];
+  if (!path) {
+    throw new Error(`Endpoint de certificación inválido: ${endpoint}`);
+  }
+  return `https://${host}${path}`;
+}
+
+/**
+ * Obtener path relativo de certificación
+ * @param {string} endpoint - Nombre del endpoint
+ * @returns {string} Path relativo
+ */
+function getCertPath(endpoint) {
+  const path = CERT_ENDPOINTS[endpoint];
+  if (!path) {
+    throw new Error(`Endpoint de certificación inválido: ${endpoint}`);
+  }
+  return path;
+}
+
+/**
+ * Obtener todas las URLs para un ambiente
+ * @param {string} ambiente - 'certificacion' o 'produccion'
+ * @returns {Object} Objeto con todas las URLs
+ */
+function getAllUrls(ambiente) {
+  const amb = String(ambiente).toLowerCase();
+  return {
+    host: HOSTS[amb],
+    soap: SOAP_ENDPOINTS[amb],
+    rest: REST_ENDPOINTS[amb],
+    cert: Object.entries(CERT_ENDPOINTS).reduce((acc, [key, path]) => {
+      acc[key] = `https://${HOSTS[amb]}${path}`;
+      return acc;
+    }, {}),
+  };
+}
+
+/**
+ * Validar ambiente
+ * @param {string} ambiente - Ambiente a validar
+ * @returns {string} Ambiente normalizado ('certificacion' o 'produccion')
+ * @throws {Error} Si el ambiente es inválido
+ */
+function validateAmbiente(ambiente) {
+  const amb = String(ambiente).toLowerCase();
+  if (!['certificacion', 'produccion'].includes(amb)) {
+    throw new Error(`Ambiente inválido: "${ambiente}", debe ser 'certificacion' o 'produccion'`);
+  }
+  return amb;
+}
+
+module.exports = {
+  // Constantes
+  HOSTS,
+  REST_HOSTS,
+  SOAP_ENDPOINTS,
+  REST_ENDPOINTS,
+  CERT_ENDPOINTS,
+  
+  // Funciones
+  getHost,
+  getSoapUrl,
+  getRestUrl,
+  getCertUrl,
+  getCertPath,
+  getAllUrls,
+  validateAmbiente,
+};

package/utils/error.js

@@ -0,0 +1,235 @@
+// Copyright (c) 2026 Devlas SpA — https://devlas.cl
+// Licencia MIT. Ver archivo LICENSE para mas detalles.
+/**
+ * Clase de Error Personalizada
+ * 
+ * Errores tipados para mejor manejo y debugging
+ * 
+ * @module dte-sii/utils/error
+ */
+
+// ============================================
+// CÓDIGOS DE ERROR
+// ============================================
+
+const ERROR_CODES = {
+  // Configuración
+  CONFIG_INVALID: 'CONFIG_INVALID',
+  CONFIG_MISSING: 'CONFIG_MISSING',
+
+  // Certificado
+  CERT_NOT_FOUND: 'CERT_NOT_FOUND',
+  CERT_INVALID: 'CERT_INVALID',
+  CERT_EXPIRED: 'CERT_EXPIRED',
+  CERT_PASSWORD_WRONG: 'CERT_PASSWORD_WRONG',
+
+  // CAF / Folios
+  CAF_NOT_FOUND: 'CAF_NOT_FOUND',
+  CAF_INVALID: 'CAF_INVALID',
+  CAF_EXPIRED: 'CAF_EXPIRED',
+  CAF_NO_FOLIOS: 'CAF_NO_FOLIOS',
+  FOLIO_OUT_OF_RANGE: 'FOLIO_OUT_OF_RANGE',
+
+  // DTE
+  DTE_INVALID: 'DTE_INVALID',
+  DTE_MISSING_FIELDS: 'DTE_MISSING_FIELDS',
+  DTE_VALIDATION_FAILED: 'DTE_VALIDATION_FAILED',
+
+  // Firma
+  SIGN_FAILED: 'SIGN_FAILED',
+  SIGN_VERIFY_FAILED: 'SIGN_VERIFY_FAILED',
+
+  // SII
+  SII_CONNECTION_FAILED: 'SII_CONNECTION_FAILED',
+  SII_AUTH_FAILED: 'SII_AUTH_FAILED',
+  SII_REJECTED: 'SII_REJECTED',
+  SII_TIMEOUT: 'SII_TIMEOUT',
+  SII_INVALID_RESPONSE: 'SII_INVALID_RESPONSE',
+
+  // XML
+  XML_PARSE_FAILED: 'XML_PARSE_FAILED',
+  XML_BUILD_FAILED: 'XML_BUILD_FAILED',
+
+  // General
+  UNKNOWN: 'UNKNOWN',
+};
+
+// ============================================
+// CLASE DteSiiError
+// ============================================
+
+/**
+ * Error personalizado del paquete
+ */
+class DteSiiError extends Error {
+  /**
+   * @param {string} message - Mensaje de error
+   * @param {string} [code] - Código de error (de ERROR_CODES)
+   * @param {Object} [details] - Detalles adicionales
+   */
+  constructor(message, code = ERROR_CODES.UNKNOWN, details = {}) {
+    super(message);
+    this.name = 'DteSiiError';
+    this.code = code;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+
+    // Mantener stack trace correcto
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, DteSiiError);
+    }
+  }
+
+  /**
+   * Convierte el error a objeto plano (para logging/serialización)
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      timestamp: this.timestamp,
+      stack: this.stack,
+    };
+  }
+
+  /**
+   * Representación string del error
+   * @returns {string}
+   */
+  toString() {
+    return `[${this.code}] ${this.message}`;
+  }
+
+  /**
+   * Verifica si es un error de SII
+   * @returns {boolean}
+   */
+  isSiiError() {
+    return this.code.startsWith('SII_');
+  }
+
+  /**
+   * Verifica si es un error recuperable (se puede reintentar)
+   * @returns {boolean}
+   */
+  isRetryable() {
+    return [
+      ERROR_CODES.SII_CONNECTION_FAILED,
+      ERROR_CODES.SII_TIMEOUT,
+    ].includes(this.code);
+  }
+}
+
+// ============================================
+// FUNCIONES HELPER
+// ============================================
+
+/**
+ * Crea error de configuración
+ * 
+ * @param {string} message - Mensaje de error
+ * @param {Object} [details] - Detalles
+ * @returns {DteSiiError}
+ */
+function configError(message, details = {}) {
+  return new DteSiiError(message, ERROR_CODES.CONFIG_INVALID, details);
+}
+
+/**
+ * Crea error de certificado
+ * 
+ * @param {string} message - Mensaje de error
+ * @param {string} [code] - Código específico de certificado
+ * @param {Object} [details] - Detalles
+ * @returns {DteSiiError}
+ */
+function certError(message, code = ERROR_CODES.CERT_INVALID, details = {}) {
+  return new DteSiiError(message, code, details);
+}
+
+/**
+ * Crea error de CAF/folios
+ * 
+ * @param {string} message - Mensaje de error
+ * @param {string} [code] - Código específico de CAF
+ * @param {Object} [details] - Detalles
+ * @returns {DteSiiError}
+ */
+function cafError(message, code = ERROR_CODES.CAF_INVALID, details = {}) {
+  return new DteSiiError(message, code, details);
+}
+
+/**
+ * Crea error de DTE
+ * 
+ * @param {string} message - Mensaje de error
+ * @param {Object} [details] - Detalles
+ * @returns {DteSiiError}
+ */
+function dteError(message, details = {}) {
+  return new DteSiiError(message, ERROR_CODES.DTE_INVALID, details);
+}
+
+/**
+ * Crea error de SII
+ * 
+ * @param {string} message - Mensaje de error
+ * @param {string} [code] - Código específico de SII
+ * @param {Object} [details] - Detalles
+ * @returns {DteSiiError}
+ */
+function siiError(message, code = ERROR_CODES.SII_REJECTED, details = {}) {
+  return new DteSiiError(message, code, details);
+}
+
+/**
+ * Crea error de XML
+ * 
+ * @param {string} message - Mensaje de error
+ * @param {Object} [details] - Detalles
+ * @returns {DteSiiError}
+ */
+function xmlError(message, details = {}) {
+  return new DteSiiError(message, ERROR_CODES.XML_PARSE_FAILED, details);
+}
+
+/**
+ * Envuelve un error nativo en DteSiiError
+ * 
+ * @param {Error} error - Error original
+ * @param {string} [code] - Código a asignar
+ * @param {Object} [details] - Detalles adicionales
+ * @returns {DteSiiError}
+ */
+function wrapError(error, code = ERROR_CODES.UNKNOWN, details = {}) {
+  if (error instanceof DteSiiError) {
+    return error;
+  }
+
+  return new DteSiiError(
+    error.message || String(error),
+    code,
+    { ...details, originalError: error.name, stack: error.stack }
+  );
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+module.exports = {
+  DteSiiError,
+  ERROR_CODES,
+
+  // Helpers
+  configError,
+  certError,
+  cafError,
+  dteError,
+  siiError,
+  xmlError,
+  wrapError,
+};