NestJS调用Shopify REST API获取履行订单返回空数组问题排查

在NestJS应用中使用@shopify/shopify-api包调用Shopify REST API，尝试获取指定订单的所有履行订单，代码如下：

async getFulfillmentOrders(orderId: string) {
    const res = await this.shopify.rest.FulfillmentOrder.all({
      session: this.getSession(),
      order_id: orderId,
    });

    return res?.fulfillment_orders;
}

调用API后返回的对象包含值为空数组的data字段和headers字段，但直接访问URL（https://xxx.shopify.com/store/xxx/orders/orderId/fulfillment_orders.json）可得到预期的履行订单。所有Shopify连接密钥等配置均正常，寻求问题原因及解决办法。

1. API版本不匹配 #

@shopify/shopify-api包默认使用的API版本可能与你手动访问的版本不一致，部分旧版本的API对履行订单的返回格式或查询逻辑有差异。

解决办法：
调用时显式指定与手动访问一致的API版本：

const res = await this.shopify.rest.FulfillmentOrder.all({
  session: this.getSession(),
  order_id: orderId,
  api_version: '2024-04' // 替换为你手动访问时使用的API版本
});

也可以在NestJS的Shopify全局配置中设置默认API版本。

2. Session对象的店铺域名错误 #

手动访问的URL包含/store/xxx路径（这是店铺前台的访问路径），但Shopify REST API要求使用店铺的后台域名（格式为xxx.myshopify.com或xxx.shopify.com，不带/store/xxx）。如果getSession()返回的session中shop属性包含/store/xxx，会导致API请求路径错误。

解决办法：
检查getSession()返回的session对象，确保shop字段为纯店铺域名（如xxx.shopify.com），去除/store/xxx后缀。

3. 订单ID格式或值错误 #

确认代码中传入的orderId与手动URL中的订单ID完全一致，避免出现字符串转数字丢失精度、多传前缀/后缀等问题。Shopify订单ID是纯数字字符串，确保没有传入包含其他字符的ID。

解决办法：
在调用前打印orderId值，与手动访问的URL中的ID对比，确保完全匹配；必要时将orderId转为数字类型后传入：

order_id: parseInt(orderId, 10)

4. 访问令牌权限不足 #

虽然连接密钥配置正常，但session对应的访问令牌可能缺少read_fulfillments权限，导致API返回空数据（而非权限错误）。

解决办法：

• 登录Shopify合作伙伴后台，检查应用的权限设置，确认已添加read_fulfillments权限；
• 重新安装应用以获取包含该权限的新访问令牌；
• 验证session中的访问令牌权限范围，可通过解码JWT令牌查看包含的权限。

5. API请求路径自动拼接问题 #

@shopify/shopify-api的FulfillmentOrder.all方法会自动拼接API路径，若session的shop域名不正确，会导致请求发送到错误的端点。

解决办法：
开启API请求日志，查看实际发送的请求URL，确认是否与预期的https://xxx.shopify.com/admin/api/{version}/orders/{order_id}/fulfillment_orders.json一致。在NestJS中可通过配置Shopify客户端的日志级别实现：

// Shopify配置示例
Shopify.Context.initialize({
  // 其他配置
  logger: {
    level: LogSeverity.Debug,
  },
});

内容的提问来源于stack exchange，提问作者Mustafa Aswadi