サプライヤーAPIガイド：手動注文の処理

前提条件

開始する前に、以下を確認してください：

• APIアクセス権を持つサプライヤーアカウント
• APIキー（サプライヤーダッシュボードから生成できます）
• Admin API v2 エンドポイントへのアクセス権

ステップ 1: APIキーを取得する

1. サプライヤーダッシュボードにログインします
2. API設定（/api-settings）に移動します
3. APIキーをお持ちでない場合は「Generate API Key」をクリックします
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

アカウント形式

製品注文の場合、アカウントは文字列の配列として提供する必要があります。各文字列は1つのアカウントを表します：

• 形式： "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',
        // ... 注文数量に一致するその他のアカウント
      ];
      
      // アカウントで注文を更新し、完了としてマークする
      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": "Invalid API key"
       }

   解決策: APIキーが正しく、有効であることを確認してください。

2. 注文が見つかりません

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Order not found"
       }

   解決策: 注文IDが存在し、あなたに属していることを確認してください。

3. アクセスが拒否されました

   {
         "error": "ACCESS_DENIED",
         "message": "You do not have access to this order"
       }

   解決策: 注文にあなたに属する製品/サービスが含まれていることを確認してください。

4. 無効なアカウント

   {
         "error": "INVALID_ACCOUNTS",
         "message": "No valid accounts provided after deduplication"
       }

   解決策: アカウント配列が空でなく、有効な文字列が含まれていることを確認してください。

ベストプラクティス

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. アカウント送信: アカウントとstatus: "completed"を指定してPOST /api/admin/v2/orders-update

このシンプルな3ステップのプロセスで、注文履行ワークフローを完全に自動化できます！

これらは両方ともサプライヤー向けのコアドキュメントガイドです。これらをリンクすることで、サプライヤーは製品設定から注文処理へと自然にナビゲートでき、論理的なワークフローが構築されます。製品管理ガイド。