Google Sheets与Lightspeed X系列API集成脚本排障请求

一、核心问题排查方向 #

1. API请求与响应验证 #

• 日期参数格式：Lightspeed X-Series API要求start_date和end_date为UTC时间的ISO 8601格式，原脚本的toISOString()虽符合格式，但未限定到当日0点，可能导致数据范围不准确，建议调整为前一日全天的时间范围：

  var startDate = new Date();
  startDate.setDate(startDate.getDate() - 1);
  startDate.setHours(0, 0, 0, 0); // 设为前一日0点
  var endDate = new Date(startDate);
  endDate.setDate(endDate.getDate() + 1); // 设为当日0点，覆盖前一日全天
  

• 响应结构验证：在getLightspeedSalesData中添加日志，确认API返回的结构是否正确：

  Logger.log(data); // 查看控制台日志，确认sales数组是否存在
  

  部分环境下API响应的销售数据可能在data.data而非data.sales，需根据实际返回调整。

2. 字段存在性验证 #

Lightspeed的销售对象中，product的部分字段可能为对象而非字符串，或存在空值：

• supplier是包含id、name的对象，需改为sale.product.supplier.name
• category同理，需改为sale.product.category.name
• 对可能为空的字段添加空值判断，避免脚本报错

3. Google Sheets权限与工作表存在性 #

• 确认脚本绑定的账号有目标表格的编辑权限
• 检查工作表名称Sales Data是否完全匹配（大小写、空格一致）
• 添加工作表存在性判断，避免因工作表不存在报错：

  if (!worksheet) {
    spreadsheet.insertSheet('Sales Data');
    worksheet = spreadsheet.getSheetByName('Sales Data');
  }
  

4. 批量写入优化（避免性能限制） #

原脚本逐个单元格写入会触发大量API调用，易被限制，改为批量写入数组：先将所有数据整理成二维数组，再一次性写入工作表。

二、修复后的完整脚本 #

function getLightspeedSalesData() {
  var endpoint = 'https://xyz.vendhq.com/api/2.0/sales';
  var apiKey = 'uniqueKEY';

  // 调整日期范围为前一日全天（UTC时间）
  var startDate = new Date();
  startDate.setDate(startDate.getDate() - 1);
  startDate.setHours(0, 0, 0, 0);
  var endDate = new Date(startDate);
  endDate.setDate(endDate.getDate() + 1);

  try {
    var request = UrlFetchApp.fetch(endpoint, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer ' + apiKey
      },
      params: {
        'start_date': startDate.toISOString(),
        'end_date': endDate.toISOString(),
        'include': 'product' // 确保返回产品关联数据
      }
    });

    var response = request.getContentText();
    var data = JSON.parse(response);
    
    // 兼容不同响应结构，优先取sales，无则取data
    var salesData = data.sales || data.data || [];
    Logger.log('获取到销售数据条数：' + salesData.length);
    return salesData;
  } catch (e) {
    Logger.log('API请求错误：' + e.message);
    return [];
  }
}

function populateLightspeedSalesData() {
  var salesData = getLightspeedSalesData();
  if (salesData.length === 0) {
    Logger.log('无销售数据可写入');
    return;
  }

  var spreadsheet = SpreadsheetApp.openById('GOOGLEsheetsID');
  var worksheet = spreadsheet.getSheetByName('Sales Data');
  
  // 若工作表不存在则创建
  if (!worksheet) {
    worksheet = spreadsheet.insertSheet('Sales Data');
  }

  // 清空工作表
  worksheet.clearContents();

  // 表头数组
  var headers = [
    'SKU', 'SKU Name', 'Supplier Code', 'Brand', 'Supplier', 
    'Category', 'Items Sold', 'Remaining Inventory'
  ];
  
  // 准备数据数组（包含表头）
  var dataToWrite = [headers];
  
  // 遍历销售数据，整理成行
  salesData.forEach(function(sale) {
    var product = sale.product || {};
    var row = [
      product.sku || '',
      product.name || '',
      product.supplier_code || '',
      product.brand || '',
      product.supplier ? product.supplier.name : '', // 处理supplier对象
      product.category ? product.category.name : '', // 处理category对象
      sale.quantity || 0,
      product.inventory_remaining || 0
    ];
    dataToWrite.push(row);
  });

  // 批量写入数据
  worksheet.getRange(1, 1, dataToWrite.length, dataToWrite[0].length).setValues(dataToWrite);
  Logger.log('数据写入完成，共写入' + (dataToWrite.length - 1) + '条销售记录');
}

三、调试步骤 #

1. 单独运行getLightspeedSalesData，查看Google Apps Script控制台日志，确认是否成功获取数据
2. 若API报错，检查apiKey、店铺域名、权限是否正确
3. 运行populateLightspeedSalesData，查看日志提示，同时检查工作表数据是否写入

内容的提问来源于stack exchange，提问作者Alex F