B2C
GHC 앱 + LogShop API
LOG 앱에서 고객에게 노출되는 상품은 season_event_products만 사용한다.
GHC B2C 개발용 백오피스·API 문서
Read this first
포털 사용 기준
B2B
LogShop Backoffice
기존 수발주와 백오피스 운영을 유지한다. B2C 요구 때문에 B2B 흐름을 깨지 않는다.
공유 자산
Products + CDN
이미지, 상품 설명, 재고 기준은 기존 자산을 재활용한다. 필요한 경우 이벤트 상품에 복사한다.
Backoffice flow
B2C 상품 노출과 주문 흐름
1
상품 마스터
products공급사·브랜드·원가·기본 상품 정보의 기준 데이터다.
2
시즌 이벤트 상품 복사
season_event_productsB2C 노출 대상은 이 테이블 기준이다. LOG 앱은 이 목록만 사용한다.
3
LOG 앱 카탈로그
/api/catalog/event-products노출 가능한 시즌 이벤트 상품을 조회하고 상세 페이지를 구성한다.
4
B2C 주문 생성
b2c_orders / b2c_order_itemsGHC 서버가 API Key로 주문을 생성한다. 클라이언트에 키를 노출하지 않는다.
5
백오피스 처리
orders / fulfillment운영자는 주문 상태, 재고, 출고 흐름을 기존 운영 규칙과 맞춰 처리한다.
Order states
B2C 주문 상태값
| 상태값 | 설명 | 설명 | 전이 권한 |
|---|---|---|---|
| pending | 주문 접수 | 결제 대기 중인 초기 상태 | partner |
| confirmed | 결제 확정 | 결제가 완료되고 배송 준비 대기 중 | partner |
| preparing | 배송 준비 중 | 배송 준비를 진행 중 (3PL에서 관리) | logistics |
| shipped | 배송 중 | 배송사에 인계됨 (송장 정보 포함) | logistics |
| delivered | 배송 완료 | 고객이 배송을 수령함 | logistics |
| cancelled | 주문 취소 | 파트너가 주문을 취소함 | partner |
| refund_requested | 환불 요청 | 고객이 환불을 신청함 (PG 취소 대기 중) | partner |
| refunded | 환불 처리 | 관리자가 PG 취소 확인 후 환불 완료 처리함 | admin |
| refund_failed | 환불 실패 | 관리자가 환불 요청을 거절하거나 PG 취소 불가 | admin |
| failed | 주문 실패 | 결제 실패, 재고 없음 등의 사유로 실패 | partner |
Current state
구현 상태와 TBD
시즌 이벤트 상품 카탈로그
LOG 앱이 조회할 B2C 상품 목록 기준이 존재한다.
B2C 주문 생성 API
API Key 기반으로 주문과 주문 품목을 생성한다.
B2C 주문 조회 API
주문 ID 기준으로 주문 상세를 조회한다.
B2C 주문 목록 조회
external_user_id 필터링 지원으로 특정 사용자의 주문만 조회할 수 있다.
주문 상태 관리 API (PATCH)
partner와 logistics 역할별로 상태 전이를 제어한다.
3PL(더신나게) 배송 연동 API
배송 중, 배송 완료 상태 전이 시 송장 정보를 함께 기록한다.
백오피스 B2C 운영 화면
운영 조회·상태 관리 범위는 현재 화면 구현과 맞춰 확인이 필요하다.
B2C 환불 요청 API
delivered 상태에서만 신청 가능. 중복 신청 방지. 백오피스에서 승인·거절 처리.
환불 상태 조회 API
주문 ID 기준으로 환불 요청 현황을 조회한다.
백오피스 환불 관리 화면
어드민이 PG 콘솔 확인 후 환불 승인·거절 처리. pid(PG 결제 ID) 표시.
취소·부분 취소
정책 확정 후 API와 운영 화면을 별도 설계한다.
주문 상태 Webhook
GHC 앱에 상태 변경을 push할지 polling으로 갈지 결정이 필요하다.
정산 리포트
B2C 매출·수수료·출고 비용 기준 확정 후 개발한다.
3PL guide
더신나게(3PL) 배송 연동
API Key 발급 설정
더신나게 파트너사가 요청할 때 key_role: "logistics"로 설정하여 API Key를 발급한다.
허용된 작업
- • preparing → shipped: 배송 중 상태로 전이 (필수: tracking_number, carrier)
- • shipped → delivered: 배송 완료 상태로 전이
- • 주문 상세 조회 (GET /api/b2c/orders/{orderId})): 배송 상태 확인
주의사항
- • GHC 등 파트너 API Key는
key_role: "partner"로 발급되므로 배송 상태 전이 불가 - • logistics 역할도 pending, confirmed, cancelled, failed 상태로는 전이 불가
- • 송장 정보(tracking_number, carrier)는 LogShop 백오피스에 기록되어 고객에게 안내된다
API reference
GHC 서버 연동 API
GET구현됨Public GET
B2C 노출 상품 목록
GET /api/catalog/event-productsLOG 앱에서 노출할 시즌 이벤트 상품 목록을 조회한다.
Response
{
"data": [
{
"id": "product-uuid",
"product_name": "상품명",
"consumer_price": 35000,
"event_supply_price": 28000,
"stock_quantity": 100,
"brand_name": "브랜드명",
"brand_id": "brand-uuid",
"is_perpetual": 0,
"event_start_at": "2026-07-01T00:00:00.000Z",
"event_end_at": "2026-07-31T23:59:59.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"totalPages": 3
},
"synonymsExpanded": []
}- B2C 화면은 이 응답을 상품 목록의 기준으로 사용한다.
- is_perpetual이 0이면 이벤트 기간 제한, 1이면 상시 판매를 의미한다.
GET구현됨Public GET
상품 상세
GET /api/catalog/products/{id}상품 상세 페이지에 필요한 설명, 이미지, 가격 정보를 조회한다.
Response
{
"data": {
"id": "product-uuid",
"product_name": "상품명",
"consumer_price": 35000,
"event_supply_price": 28000,
"stock_quantity": 100,
"brand_name": "브랜드명",
"brand_id": "brand-uuid",
"description": "상품 설명",
"thumbnail_url": "https://...",
"is_perpetual": 0,
"event_start_at": "2026-07-01T00:00:00.000Z",
"event_end_at": "2026-07-31T23:59:59.000Z"
}
}- 상세 화면은 이벤트 상품 ID와 원본 상품 ID 관계를 확인해야 한다.
GET구현됨Public GET
브랜드 목록
GET /api/catalog/brands카탈로그 필터 또는 브랜드 칩 구성에 사용할 브랜드 목록이다.
Response
{
"data": [
{
"id": "brand-uuid",
"brand_name": "브랜드명",
"description": "브랜드 설명",
"logo_url": "https://...",
"event_count": 3
}
],
"eventCount": 5
}- B2C 화면에서 브랜드 필터가 필요할 때 사용한다.
POST구현됨API Key
B2C 주문 생성
POST /api/b2c/ordersGHC 서버가 고객 결제 완료 후 LogShop에 주문을 생성한다.
API Key는 서버 간 통신 전용이다. GHC 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
Request
{
"customer_name": "홍길동",
"customer_phone": "01012345678",
"delivery_address": "서울시 강남구 테헤란로 123",
"delivery_detail_address": "456호",
"delivery_postal_code": "06234",
"external_order_id": "GHC-ORDER-001",
"external_user_id": "ghc-user-123",
"pid": "T1234567890",
"pay_type": 1,
"items": [
{
"season_event_product_id": "product-uuid",
"quantity": 1
}
]
}Response
{
"order_number": "B2C-20260710-59240",
"order_id": "uuid",
"status": "confirmed",
"total_amount": 35000,
"total_quantity": 1,
"items": [
{
"season_event_product_id": "product-uuid",
"product_name": "상품명",
"quantity": 1,
"unit_price": 35000,
"subtotal": 35000
}
]
}- API Key는 GHC 서버에서만 보관한다. 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
- 주문 품목은 season_event_products 기준으로 전달한다.
- 동일 주문 중복 생성 방지를 위해 external_order_id를 고유하게 관리한다.
- external_user_id는 파트너사 내부 사용자 ID로, 주문 목록 조회 시 필터링에 사용된다.
- pid: PG사 결제 ID (카카오페이 tid, 네이버페이 paymentId). 환불 신청 시 어드민이 PG 콘솔에서 직접 취소할 때 사용한다.
- pay_type: 1 = 카카오페이, 2 = 네이버페이.
GET구현됨API Key
B2C 주문 조회
GET /api/b2c/orders/{orderId}주문 상세와 처리 상태를 조회한다.
API Key는 서버 간 통신 전용이다. GHC 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
Response
{
"order_id": "uuid",
"order_number": "B2C-20260710-59240",
"status": "confirmed",
"customer_name": "홍길동",
"customer_phone": "01012345678",
"delivery_address": "서울시 강남구 테헤란로 123",
"delivery_detail_address": "456호",
"delivery_postal_code": "06234",
"total_amount": 35000,
"total_quantity": 1,
"external_order_id": "GHC-ORDER-001",
"external_user_id": "ghc-user-123",
"pid": "T1234567890",
"pay_type": 1,
"created_at": "2026-07-10T08:30:00.000Z",
"updated_at": "2026-07-10T08:30:00.000Z",
"items": [
{
"season_event_product_id": "product-uuid",
"product_name": "상품명",
"quantity": 1,
"unit_price": 35000,
"subtotal": 35000,
"brand_id": "brand-001",
"brand_name": "글로우뷰티",
"tracking_number": "1234567890",
"carrier": "CJ대한통운",
"shipped_at": "2026-07-11T10:00:00.000Z"
}
]
}- 상태 동기화 방식은 polling 또는 webhook 중 정책 결정이 필요하다.
- v2.82부터 각 item에 brand_id, brand_name, tracking_number, carrier, shipped_at이 추가되었습니다.
- v2.94부터 pid(PG 결제 ID)와 pay_type(1=카카오페이, 2=네이버페이)이 추가되었습니다.
GET구현됨API Key
B2C 주문 목록 조회
GET /api/b2c/orders파트너의 모든 B2C 주문을 조회한다. external_user_id로 특정 사용자의 주문만 필터링할 수 있다.
API Key는 서버 간 통신 전용이다. GHC 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
Response
{
"data": [
{
"order_id": "uuid",
"order_number": "B2C-20260710-59240",
"status": "confirmed",
"customer_name": "홍길동",
"customer_phone": "01012345678",
"delivery_address": "서울시 강남구 테헤란로 123",
"delivery_detail_address": "456호",
"delivery_postal_code": "06234",
"total_amount": 35000,
"total_quantity": 1,
"external_order_id": "GHC-ORDER-001",
"external_user_id": "ghc-user-123",
"pid": "T1234567890",
"pay_type": 1,
"created_at": "2026-07-10T08:30:00.000Z",
"updated_at": "2026-07-10T08:30:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3,
"totalPages": 1
}
}- external_user_id 파라미터로 특정 사용자의 주문만 조회할 수 있다.
- page와 limit 파라미터로 페이지네이션을 제어한다.
PATCH구현됨API Key
B2C 주문 상태 업데이트
PATCH /api/b2c/orders/{orderId}/status주문 상태를 전이한다. API Key의 role(partner/logistics)에 따라 허용된 전이만 가능하다.
API Key는 서버 간 통신 전용이다. GHC 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
Request
{
"status": "shipped",
"tracking_number": "1234567890",
"carrier": "CJ대한통운"
}Response
{
"order_id": "uuid",
"order_number": "B2C-20260710-59240",
"status": "shipped",
"tracking_number": "1234567890",
"carrier": "CJ대한통운",
"updated_at": "2026-07-10T12:00:00.000Z"
}- partner 역할: pending→confirmed, confirmed/preparing/shipped→cancelled, delivered→refund_requested 전이 허용.
- logistics 역할: confirmed→preparing, preparing→shipped, shipped→delivered 전이 허용.
- shipped 상태 전이 시 tracking_number, carrier는 필수 필드다.
- 유효하지 않은 상태 전이는 403 error를 반환한다.
POST구현됨API Key
B2C 환불 신청
POST /api/b2c/orders/{orderId}/refunddelivered 상태의 주문에 대해 환불을 신청한다. 어드민이 PG 콘솔에서 수동 취소 후 승인 처리한다.
API Key는 서버 간 통신 전용이다. GHC 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
Request
{
"reason": "고객 변심",
"refund_amount": 35000
}Response
{
"refund_id": "uuid",
"order_id": "uuid",
"status": "pending",
"refund_amount": 35000,
"reason": "고객 변심",
"created_at": "2026-07-14T09:00:00.000Z"
}- delivered 상태의 주문에만 신청 가능하다. 다른 상태에서는 409 error를 반환한다.
- 이미 pending 또는 approved 상태의 환불 요청이 있으면 409 error를 반환한다.
- 환불 신청 후 주문 상태는 refund_requested로 변경된다.
- 어드민은 /admin/b2c-refunds에서 pid(PG 결제 ID)를 확인하고 PG 콘솔(카카오페이/네이버페이)에서 수동 취소 후 승인 처리한다.
- 승인 시 주문 상태는 refunded, 거절 시 refund_failed로 변경된다.
GET구현됨API Key
B2C 환불 상태 조회
GET /api/b2c/orders/{orderId}/refund주문의 환불 요청 현황을 조회한다.
API Key는 서버 간 통신 전용이다. GHC 앱 클라이언트, 웹뷰, 번들 파일에 포함하지 않는다.
Response
{
"refund_id": "uuid",
"order_id": "uuid",
"status": "pending",
"refund_amount": 35000,
"reason": "고객 변심",
"admin_note": null,
"created_at": "2026-07-14T09:00:00.000Z",
"updated_at": "2026-07-14T09:00:00.000Z"
}- 환불 요청이 없는 경우 404를 반환한다.
- status: pending(처리대기), approved(환불완료), rejected(거절).
Docs index