샌드박스 환경 및 fixtures

대상: https://api.hiobuy.com(Workers gateway)에 배포하는 통합 — base URL은 프로덕션과 동일.

플랜: 무료 플랜에는 셀프서비스 문서와 Sandbox 액세스가 포함됩니다. 전담 연동 및 풀필먼트 지원은 유료 플랜에서 제공됩니다.

인증: 결정론적 fixtures는 hio_test_* 접두사 API 키(key_type: test)에 만 적용됩니다. hio_live_* 프로덕션 키는 이 페이지 규칙을 절대 사용하지 않으며, 항상 upstream marketplace / warehouse에 정상 접근합니다.

관련 문서: Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Public API 커버리지(요약)

설계 목표

명명: sb_{domain}_{scenario}

문자: [a-z0-9_], 길이 ≤ ~48. fixture 의도가 없으면 실제 upstream id에 sb_를 붙이지 마세요. 일부 fulfillment 리소스는 비 sb_ 안정 id(ret_*, ucp_*, svc_*, tkt_*, inv_*)도 사용합니다.

두 가지 실패 계층

전송/API 오류와 HTTP 200 비즈니스 상태를 구분:

• API 실패 → HTTP 4xx/5xx + error.code(예: NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 + 상태 → 예: variants[].stock = 0, status: wait_payment.

상품 fixtures(개요)

POST /v1/products/detail

Product detail 참조. 샌드박스에서 upstream 형식 미지원.

id, product_id, 파싱된 url, mi_id, **tao_password**가 sb_* id로 해석되면 트리거.

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_test_..." \
  -H "Content-Type: application/json" \
  -d '{"channel":"1688","product_id":"sb_prod_not_found","language":"ko"}'

POST /v1/products/search

channel, keyword, page, page_size, language 적용. 1688 filter / sort / 가격 필터는 수락되나 mock 행에서는 무시.

Parse / upload-image / search-by-image / freight / analytics

주문 및 결제 fixtures(magic id)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview는 고정 illustrative 합계(샘플 라인 ~4500 + 운임 ~800 minor units) 반환. Create는 sbo_* 접두사 동적 order_id를 sandbox storage에 영속 — offer_id: sb_prod_offline / sb_prod_no_stock 참조 라인은 프로덕션 의미와 같이 422.

Cancel / logistics / list / purchase query

cancel, trace, detail list에 따라: 미결제 sb_ord_* 및 동적 미결제 sbo_* 취소 가능; paid/shipped 등 fixtures는 ORDER_NOT_CANCELLABLE. Logistics는 sb_ord_shipped / completed mock에 packages; unpaid/paid-await-shipment는 packages: []. 구매자 목록은 빈 mock에 product_name: sb_ord_list_empty 반영. **Purchase query**는 upstream envelope 반환; not-found pseudo id는 해당 없이 생략.

Fulfillment fixtures

참고: 아래 fixtures는 Sandbox API 테스트 전용입니다. 앱의 WH-DEV 창고 구성을 나타내지 않습니다. WH-DEV 테스트에는 Production API 키(hio_live_*)를 사용하세요.

아래 모든 엔드포인트에는 hio_test_* 키가 필요합니다. create에서 나온 동적 id(pkg_*, sbs_*, sbi_*, …)는 키 단위로 sandbox storage에 영속됩니다.

Balance · quotes · locations · VAS catalog

Shipments

Live warehouse Public id is the numeric PK as a string (e.g. "115"); order_sn is the warehouse order number. Sandbox create returns sbs_*; fixtures below use sb_shp_*.

List path: GET /v1/fulfillment/shipments. Tracking path: GET /v1/fulfillment/shipments/{id}/tracking (language query).

Inbounds(create / cancel)

Create는 동적 package_id(pkg_*)를 반환합니다 — 별도의 inbound_id는 없습니다.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance(transactions / invoices)

Fulfillment finance 참조.

지원 티켓 fixtures

Support tickets 참조.

플랫폼 트리거: sandbox_trigger

hio_test_*에 만 허용; 프로덕션 키는 필드를 조용히 무시.

현실적인 body가 검증되도록 무해한 id와 조합:

{
  "channel": "1688",
  "product_id": "123456",
  "language": "ko",
  "sandbox_trigger": "sb_plat_quota_exceeded"
}

트리거와 결합한 특수 auth fixture **sb_auth_channel_required**는 일반 «authorized by default» 규칙에도 UI 회귀용 CHANNEL_AUTH_REQUIRED(403) 생성 가능.

구현 상태 스냅샷

빠른 복사 치트시트

sb_prod_not_found          → 404 product missing
sb_prod_offline            → 422 unavailable
sb_prod_no_stock           → 200 detail with zero stock

sb_search_empty            → empty search/items
sb_ord_list_empty          → empty buyer order list filter
img_sandbox_mock           → stable upload-image id

sb_ord_unpaid              → detail wait_payment • pay succeeds • cancel ok
sb_ord_pay_declined        → pay 402 PAYMENT_DECLINED
sb_ord_paid                → pay 409 ALREADY_PAID • trace maybe empty until shipped fixtures
sb_ord_shipped             → detail wait_receive • trace populated
sb_ord_cancelled           → cancelled state • pay conflicts

sb_shp_unpaid / sb_shp_shipped / sb_shp_signed / sb_shp_intercepted → shipment list / detail / intercept
sb_pkg_received / sb_pkg_shipped → package detail / fulfillment timeline
sb_inbound_exists          → inbound create 409 tracking exists
ret_pending_001            → return confirm happy path
ucp_01K2ABCDEF1234567890   → unclaimed claimable
svc_photo_completed        → VAS request completed
tkt_01K2ABCDEF1234567890   → support ticket open

sb_plat_quota_exceeded     → sandbox_trigger → 429 QUOTA_EXCEEDED

내부 fixtures 추가 시 회귀 테스트에 이 번호 체계를 반영 — mock 내부 standard JSON 형태는 절대 변경하지 마세요.