供应商 API 指南：处理手动订单

前提条件

开始之前，请确保您已具备：

• 一个拥有 API 访问权限的供应商账户
• 您的 API 密钥（可从供应商仪表板生成）
• 对 Admin API v2 端点的访问权限

步骤 1：获取您的 API 密钥

1. 登录您的供应商仪表板
2. 导航至 API 设置 (/api-settings)
3. 如果您还没有 API 密钥，请点击"生成 API 密钥"
4. 复制您的 API 密钥并妥善保管

重要提示：您的 API 密钥应保密。切勿公开分享或将其提交到版本控制系统中。

步骤 2：获取手动订单

使用 GET /api/admin/v2/orders 端点来获取待处理和处理中的手动订单。

API 请求

curl -X GET "https://your-domain.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

请求参数

• status (可选)：订单状态过滤器。支持逗号分隔的值：pending,processing
• productType (手动订单必需)：设置为 manual
• entityType (可选)：按 product 或 smm_service 过滤
• subCategory (可选)：按子类别名称过滤
• limit (可选)：返回的订单数量（最大 500，默认 50）
• offset (可选)：分页偏移量（默认 0）

响应示例

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Instagram Followers",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

重要说明

• 仅返回 paymentStatus: "completed" 的订单
• 订单经过过滤以防止重复处理（30 分钟间隔）
• 您只能看到属于您作为供应商的产品/服务的订单

步骤 3：处理订单并提交账户

获取订单后，处理它们并准备账户凭据。然后使用 POST /api/admin/v2/orders-update 端点来提交账户并更新订单状态。

API 请求

curl -X POST "https://your-domain.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "username1:password1",
      "username2:password2",
      "username3:password3"
    ],
    "supplierOrderId": "SUP-ORDER-12345"
  }'

请求体参数

• order (必需)：订单 ID（数字）
• status (可选)：新的订单状态。有效值：pending, processing, completed, partial, cancelled, error
• accounts (可选，用于产品订单)：账户凭据数组，格式为 "username:password" 或 "email:password"
• supplierOrderId (可选)：您用于跟踪的内部订单 ID

账户格式

对于产品订单，账户应作为字符串数组提供。每个字符串代表一个账户：

• 格式： "username:password" 或 "email:password"
• 示例： ["user1:pass123", "user2:pass456"]
• 数量：提供与订单数量匹配的账户

完整工作流示例

这是一个使用 JavaScript/Node.js 的完整示例：

const axios = require('axios');

const API_BASE_URL = 'https://your-domain.com/api/admin/v2';
const API_KEY = 'YOUR_API_KEY';

// 步骤 1：获取待处理和处理中的手动订单
async function getOrders() {
  try {
    const response = await axios.get(`${API_BASE_URL}/orders`, {
      params: {
        status: 'pending,processing',
        productType: 'manual',
        limit: 50,
        offset: 0
      },
      headers: {
        'X-Api-Key': API_KEY
      }
    });
    
    return response.data.orders;
  } catch (error) {
    console.error('获取订单时出错：', error.response?.data || error.message);
    throw error;
  }
}

// 步骤 2：处理订单并提交账户
async function updateOrder(orderId, accounts, supplierOrderId) {
  try {
    const response = await axios.post(
      `${API_BASE_URL}/orders-update`,
      {
        order: orderId,
        status: 'completed',
        accounts: accounts,
        supplierOrderId: supplierOrderId
      },
      {
        headers: {
          'X-Api-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('更新订单时出错：', error.response?.data || error.message);
    throw error;
  }
}

// 主工作流
async function processOrders() {
  try {
    // 获取订单
    const orders = await getOrders();
    console.log(`找到 ${orders.length} 个待处理的订单`);
    
    // 处理每个订单
    for (const order of orders) {
      console.log(`正在处理订单 ${order.id}...`);
      
      // 准备账户（此处您将从您的系统中获取）
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... 更多账户，匹配 order.quantity
      ];
      
      // 使用账户更新订单并标记为已完成
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`订单 ${order.id} 已成功完成`);
    }
  } catch (error) {
    console.error('工作流出错：', error);
  }
}

// 运行工作流
processOrders();

错误处理

常见错误

1. 无效的 API 密钥

   {
         "error": "INVALID_API_KEY",
         "message": "无效的 API 密钥"
       }

   解决方案：检查您的 API 密钥是否正确且处于活动状态。

2. 订单未找到

   {
         "error": "ORDER_NOT_FOUND",
         "message": "订单未找到"
       }

   解决方案：验证订单 ID 是否存在且属于您。

3. 访问被拒绝

   {
         "error": "ACCESS_DENIED",
         "message": "您无权访问此订单"
       }

   解决方案：确保订单包含属于您的产品/服务。

4. 无效的账户

   {
         "error": "INVALID_ACCOUNTS",
         "message": "去重后未提供有效的账户"
       }

   解决方案：确保账户数组不为空且包含有效的字符串。

最佳实践

1. 轮询频率： 不要过于频繁地轮询。API 通过 30 分钟的时间间隔来防止重复处理。
2. 错误处理： 始终实施适当的错误处理和重试逻辑。
3. 账户验证： 在提交前验证账户，确保其格式正确。
4. 订单追踪： 使用 supplierOrderId 在您的系统中追踪订单。
5. 状态更新： 您可以逐步更新状态：
   • 开始处理订单时，首先设置为 processing
   • 账户准备就绪后，再设置为 completed
6. 部分订单： 如果您只能完成部分订单，请将状态设置为 partial 并提交可用的账户。

总结

完整的工作流程如下：

1. 获取订单： GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. 处理订单： 为每个订单准备账户
3. 提交账户： POST /api/admin/v2/orders-update 并附带账户信息和 status: "completed"

这个简单的三步流程可以让您完全自动化订单履行工作流！

两者都是核心供应商文档指南。将它们链接起来有助于供应商从产品设置导航到订单处理，形成一个逻辑清晰的工作流程。产品管理指南。