공급업체 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. 계정 제출: 계정과 status: "completed"를 포함한 POST /api/admin/v2/orders-update

이 간단한 3단계 프로세스를 통해 주문 이행 워크플로를 완전히 자동화할 수 있습니다!

둘 다 핵심 공급업체 문서 가이드입니다. 이들을 연결하면 공급업체가 제품 설정에서 주문 처리로 원활하게 이동하며 논리적인 워크플로를 만들 수 있습니다. 제품 관리 가이드.