Agent API 문서

개요

Base URL은 사이트 루트입니다. Agent API는 /api/v1/agent/* 아래에 있습니다. APPROVED 이고 Agent 공급이 켜진 상품만 보이며, 가격은 대리가(고정/할인)입니다. 주문 수량 1–5.

• 승인된 Agent와 API Key 필요
• 결제: USDT TRC20(기본) 또는 BEP20
• 주문 생성 시 입금 주소·금액 반환
• deliveryUrl로 납품 내용 조회(동일 인증)

https://YOUR_HOST 를 실제 오리진으로 바꾸세요 (로컬: http://127.0.0.1:43321)

인증

아래 헤더 중 하나로 API Key를 보냅니다. 승인 후 발급되며 서버는 SHA-256 해시만 저장합니다.

Authorization: Bearer <api_key>

x-api-key: <api_key>

Key 없음/무효 또는 미승인 → HTTP 401 {"error":"unauthorized"}.

엔드포인트

{
  "products": [
    {
      "id": "prod_xxx",
      "slug": "x-account-sms",
      "title": { "zh": "…", "en": "…", "ko": "…" },
      "listPrice": "3.00",
      "agentPrice": "2.40",
      "stock": 73,
      "deliveryType": "AUTO",
      "category": "accounts"
    }
  ]
}

{
  "productId": "prod_xxx",
  "quantity": 1,
  "network": "TRC20"
}

{
  "checkoutId": "chk_xxx",
  "orderNumber": "XN123456",
  "paymentId": "pay_xxx",
  "amount": "2.40",
  "address": "T…",
  "payPath": "/pay/pay_xxx"
}

{
  "number": "XN123456",
  "status": "FULFILLED",
  "deliveryType": "AUTO",
  "quantity": 1,
  "total": "2.40",
  "hasDelivery": true,
  "deliveryUrl": "/api/orders/XN123456/delivery",
  "paymentStatus": "CONFIRMED"
}

오류 코드

• 401 unauthorized — API Key 없음/무효
• 404 unavailable — 상품 없음·미승인·Agent 비공급
• 404 not_found — 주문 없음 또는 소유 아님
• 400 — 비즈니스 오류(재고 등), error는 소문자 문자열

대리가·공급

supplyToAgents 가 켜진 상품만 대상. 가격 모드:

• FIXED: agentPrice 단가
• DISCOUNT: listPrice × (1 − agentDiscountPct) − agentDiscountAmt (최소 0)
• 모드 미설정 시 listPrice

목록은 stock > 0 만. 주문 시에도 공급·재고 검증.