리셀러 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, 필수)

문자 발송 라인

POST /api/reseller/orders는 주문을 생성한 뒤 리셀러의 문자 발송 설정값에 따라 백엔드 워커가 발송 채널을 결정합니다. 리셀러 설정이 aligo면 알리고 MMS 큐로 보내고, giftishow면 기프티쇼 발송 라인으로 보냅니다.

실패 응답 또는 워커 최종 실패는 발송 수량/정산에 포함하지 않습니다. 프런트는 우선 주문을 접수하고, GET /api/reseller/orders/{orderId}로 sent/failed 최종 상태를 확인해야 합니다.

상품 이미지 조회/캐시 규약

상품 이미지는 포털 API가 내려주는 image_url을 기본으로 사용합니다. 백엔드는 로컬 캐시 이미지가 있으면 우선 반환하고, 없으면 원청 이미지 필드를 정규화해서 반환합니다.

이미지 캐시 요청 예시

POST /api/reseller/portal/product-image/cache?reseller_id=1
x-api-key: {API_KEY}
Content-Type: application/json

{
  "productCode": "G00000117135",
  "image_url": "https://imgs.giftishow.co.kr/Resource/..."
}

{
  "ok": true,
  "source_id": "G00000117135",
  "image_url": "/data/uploads/event-goods/reseller-1/G00000117135_xxx.jpg",
  "file_path": "event-goods/reseller-1/G00000117135_xxx.jpg",
  "cached": true
}

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

외부 호스팅된 웨딩 페이지는 발행 성공 직후 아래 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

포털 상품 응답 예시

응답 예시

{
  "reseller": {
    "resellerId": 1,
    "resellerCode": "rec01",
    "resellerName": "샘플 리셀러"
  },
  "items": [
    {
      "productCode": "G00000125871",
      "productName": "CU 모바일상품권 1만원권",
      "brand": "CU",
      "brandImageUrl": "https://imgs.giftishow.co.kr/Resource/...",
      "category": "일반상품(금액형)",
      "image_url": "https://imgs.giftishow.co.kr/Resource/...",
      "imageUrl": "https://imgs.giftishow.co.kr/Resource/...",
      "basePrice": 9000,
      "retailPrice": 10000,
      "resellerRate": null,
      "policyRate": null,
      "resellerPrice": 9000,
      "status": "active",
      "validPrdDay": "30",
      "validPrdDate": ""
    }
  ]
}

image_url가 기본 필드이며, 프런트 호환용으로 imageUrl도 같이 제공합니다. 이미지가 없으면 빈 문자열로 내려갑니다.

포털 상품 상세 응답 예시

{
  "reseller": {
    "resellerId": 1,
    "resellerCode": "rec01",
    "resellerName": "샘플 리셀러"
  },
  "item": {
    "productCode": "G00000125871",
    "productName": "CU 모바일상품권 1만원권",
    "brand": "CU",
    "brandCode": "B001",
    "brandImageUrl": "https://imgs.giftishow.co.kr/Resource/...",
    "brand_image_url": "https://imgs.giftishow.co.kr/Resource/...",
    "category": "일반상품(금액형)",
    "image_url": "https://imgs.giftishow.co.kr/Resource/...",
    "imageUrl": "https://imgs.giftishow.co.kr/Resource/...",
    "description": "상품 상세 설명",
    "notice": "사용 시 유의사항",
    "basePrice": 9000,
    "retailPrice": 10000,
    "resellerPrice": 9000,
    "status": "active",
    "validPrdDay": "30",
    "validPrdDate": "",
    "cancelPossible": true,
    "refundPossible": true,
    "extendPossible": false
  }
}

상세 API는 판매에 필요한 메타만 공개하며 raw_payload 같은 원청 원본은 외부에 노출하지 않습니다.

필드 리네이밍 규약

구매 페이지 구현 최소 흐름

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",
  "customImageUrl": "/data/uploads/event-couple/123/message-image.jpg"
}

{
  "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",
  "pinNo": "9000-8231-3934",
  "barcode": "900082313934"
}

보안 정책

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

오류 코드

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

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

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

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

1) 상품 목록 (goods)

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

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

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