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

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

두 문서 모두 핵심 공급업체 문서 가이드입니다. 이들을 연결하면 공급업체가 제품 설정부터 주문 처리까지 원활하게 이동하여 논리적인 워크플로우를 만들 수 있습니다. 제품 관리 가이드를 참조하세요.