리셀러 API 문서

개요

리셀러는 API 키로 인증하여 상품/포인트/주문 정보를 조회합니다.

샘플 페이지: https://btscon.co.kr/guide/reseller-purchase.html

PHP 샘플 파일 경로: frontphp/reseller/index.php

독립 호스팅용 포털 API: /api/reseller/portal/* (리셀러 ID + API 키 기반)

포털 API (독립 호스팅용)

원청 테이블 키를 숨기기 위해 아래 표준 키로 재매핑하여 제공합니다.

공통 헤더: x-api-key: {API_KEY}

공통 쿼리: reseller_id (숫자 ID, 필수)

정산 반영 규약 (웨딩 발행 성공 건)

외부 호스팅된 웨딩 페이지는 발행 성공 직후 아래 API를 1회 호출합니다. 백엔드에서 지갑/원장/회사보유금까지 통합 반영합니다.

요청 예시

POST /api/reseller/portal/event-issue-settle?reseller_id=1
x-api-key: {API_KEY}
Content-Type: application/json

{
  "entry_id": 12345,
  "order_id": "FRONTSIM-ABC123",
  "reseller_debit": 10670,
  "company_debit": 10000,
  "memo": "event_issue:FRONTSIM-ABC123"
}

응답 예시

{
  "status": "ok",
  "already_applied": false,
  "mode": "live",
  "reseller_balance": 39871960,
  "company_balance": 99940000
}

에러 코드: 400 missing_reseller/invalid_entry_id, 401 missing_api_key/invalid_api_key_or_reseller, 404 reseller_not_found

필드 리네이밍 규약

구매 페이지 구현 최소 흐름

1. GET /api/reseller/catalog로 상품 목록 조회
2. 사용자가 goodsId를 선택하고 주문 정보 입력
3. POST /api/reseller/orders로 주문 생성
4. GET /api/reseller/orders/{orderId}로 상태/쿠폰 확인

내부 QA 기능(웹훅 시뮬레이션, 내부 전용 payload/raw 필드)은 리셀러 구매 화면에 노출하지 마세요.

구매 UI 권장 필드

엔드포인트 요청/응답 예시

카탈로그 조회

GET /api/reseller/catalog?limit=20&offset=0
x-api-key: {API_KEY}

{
  "items": [
    {
      "goodsId": "G000000001",
      "goodsName": "아메리카노 Tall",
      "sellPrice": 4500,
      "status": "active"
    }
  ],
  "limit": 20,
  "offset": 0
}

주문 생성

POST /api/reseller/orders
Content-Type: application/json
x-api-key: {API_KEY}

{
  "goodsId": "G000000001",
  "receiver": "01012345678",
  "sender": "BTSCON",
  "title": "쿠폰 발송",
  "msg": "주문하신 쿠폰입니다.",
  "orderId": "my-order-1001"
}

{
  "orderId": "rec01-my-order-1001",
  "clientOrderId": "my-order-1001",
  "status": "queued"
}

주문 조회

GET /api/reseller/orders/rec01-my-order-1001
x-api-key: {API_KEY}

{
  "orderId": "rec01-my-order-1001",
  "goodsId": "G000000001",
  "status": "sent",
  "tradeCode": "02",
  "sellPrice": 4500,
  "trId": "rec01-my-order-1001",
  "couponNo": "1234-5678-9012"
}

보안 정책

• 화이트리스트 ON: 등록된 IP만 허용
• 화이트리스트 OFF: IP 제한 없음
• 관리자 페이지에는 영향 없음

오류 코드

리셀러 제공 데이터 규약 (초안)

원청 수신 데이터를 아래 필드로 정규화해 리셀러에게 제공합니다.

원본 전체 payload는 내부 저장용이며 리셀러에는 공개하지 않습니다.

비공개 항목 (내부 저장용)

1) 상품 목록 (goods)

2) 쿠폰 발급 결과 (coupon/send)

3) 웹훅 이벤트 (거래 상태 통지)

리셀러 API 키에 등록된 hook_url로 JSON POST 전송됩니다.