버전: 2.0.0 최종 업데이트: 2025-11-30 대상: 병원, 약국, 제약사, IoT 제조사, 의료기기 업체
AI Medical Platform은 진단 → 처방 → 구매 → 협업의 완전한 건강 관리 생태계를 구축합니다. 파트너사는 플랫폼을 통해 고객에게 상품과 서비스를 제공하고, 매출을 증대할 수 있습니다.
┌─────────────────────────────────────────────────────────────────────────────┐
│ AI Medical Platform 생태계 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ │
│ │ AI Medical │ │
│ │ Platform │ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────────────────────┼───────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 고객 │◀─────────▶│ 파트너 │◀─────────▶│ 의료 │ │
│ │ (환자) │ │ (판매사) │ │ 전문가 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 건강 │ │ 상품 │ │ 진단 │ │
│ │ 데이터 │ │ 주문 │ │ 처방 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ← 데이터 흐름 → │
│ ← 수익 흐름 → │
└─────────────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────────────┐
│ 파트너 유형별 역할 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 병원 (HOSPITAL) ─────────────────────────────────────────────────────┐ │
│ │ 역할: 의료 서비스 제공 │ │
│ │ 서비스: │ │
│ │ • 비대면 상담 (WebRTC 화상) │ │
│ │ • 처방전 발급 및 승인 │ │
│ │ • FHIR R4 데이터 연동 │ │
│ │ • 의사 스케줄 관리 │ │
│ │ 수수료: 진료비의 20% │ │
│ │ 정산: 월 1회 (익월 15일) │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 약국 (PHARMACY) ──────────────────────────────────────────────────────┐ │
│ │ 역할: 의약품 판매 및 조제 │ │
│ │ 서비스: │ │
│ │ • 처방전 조제 │ │
│ │ • 의약품 배송 │ │
│ │ • 복약 상담 │ │
│ │ • OTC 의약품 판매 │ │
│ │ 수수료: 10% │ │
│ │ 정산: 월 1회 (익월 15일) │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 제약사 (PHARMACEUTICAL) ──────────────────────────────────────────────┐ │
│ │ 역할: 건강기능식품 제조/공급 │ │
│ │ 서비스: │ │
│ │ • 상품 등록 및 관리 │ │
│ │ • 재고 관리 │ │
│ │ • 배송 처리 │ │
│ │ • AI 처방 추천 연동 │ │
│ │ 수수료: 15% │ │
│ │ 정산: 월 1회 (익월 15일) │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ IoT 제조사 (IOT_MANUFACTURER) ────────────────────────────────────────┐ │
│ │ 역할: 웨어러블/의료기기 제조 │ │
│ │ 서비스: │ │
│ │ • 디바이스 연동 │ │
│ │ • 실시간 데이터 수집 │ │
│ │ • 기기 판매 │ │
│ │ • 펌웨어 업데이트 │ │
│ │ 수수료: 12% │ │
│ │ 정산: 월 1회 (익월 15일) │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘| 혜택 | 설명 | 예상 효과 |
|---|---|---|
| 💰 매출 증대 | 플랫폼 사용자에게 상품/서비스 노출 | +30% 신규 고객 |
| 🤖 AI 추천 | AI가 고객에게 파트너 상품 자동 추천 | +50% 전환율 |
| 📊 데이터 분석 | 고객 구매 패턴, 인기 상품 분석 | 데이터 기반 의사결정 |
| 🔗 API 연동 | 자동화된 주문/재고 관리 | -70% 운영 비용 |
| 📈 마케팅 지원 | 플랫폼 내 프로모션 및 광고 | +40% 노출 |
| 🏆 파트너 등급 | 실적 기반 등급 혜택 | 수수료 할인 최대 5% |
| 📚 교육 지원 | 파트너 교육 프로그램 | 비즈니스 역량 강화 |
| 🎯 전담 매니저 | 실버 등급 이상 전담 매니저 배정 | 1:1 지원 |
| 파트너 유형 | 플랫폼 수수료 | 결제 수수료 | 실질 수수료 |
|---|---|---|---|
| 제약사 | 15% | 2.5% | 17.5% |
| 약국 | 10% | 2.5% | 12.5% |
| 병원 | 20% | 2.5% | 22.5% |
| IoT 제조사 | 12% | 2.5% | 14.5% |
| 등급 | 월 매출 기준 | 수수료 할인 |
|---|---|---|
| 브론즈 | ₩5M 미만 | 0% |
| 실버 | ₩5M ~ ₩20M | -1% |
| 골드 | ₩20M ~ ₩50M | -2% |
| 플래티넘 | ₩50M ~ ₩100M | -3% |
| 다이아몬드 | ₩100M 이상 | -5% |
┌─────────────────────────────────────────────────────────────────────────────┐
│ 월간 정산 사이클 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1일 말일 5일 15일 20일 │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌───────────────────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 판매 기간 │ │ 정산 │ │ 정산금 │ │ 이의 │ │
│ │ (배송완료 기준) │ │ 마감 │ │ 지급 │ │ 신청 │ │
│ │ │ │ │ │ │ │ 마감 │ │
│ └───────────────────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ 예시: 11월 판매분 │
│ • 11/1 ~ 11/30: 판매 (배송완료 기준) │
│ • 12/5: 11월 정산 마감 │
│ • 12/15: 정산금 지급 │
│ • 12/20: 이의 신청 마감 │
└─────────────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────────────┐
│ 파트너 등록 프로세스 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ 1. 신청 │ 온라인 신청서 작성 (5분) │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 2. 서류제출 │ 필수 서류 업로드 (당일) │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 3. 서류검토 │ 관리자 서류 검토 (3영업일) │
│ └──────┬───────┘ │
│ │ │
│ ├──────────────────────────────┐ │
│ │ 승인 │ 보완 요청 │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 4. 계약체결 │ │ 서류 보완 │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ ▼ └──────────────────┐ │
│ ┌──────────────┐ │ │
│ │ 5. 계정발급 │ 파트너 계정 + API 키 발급 │ │
│ └──────┬───────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────┐ │ │
│ │ 6. 온보딩 │ 교육 + 상품 등록 │ │
│ └──────┬───────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────┐ │ │
│ │ 7. 판매시작 │ 🎉 정식 판매 시작! │ │
│ └──────────────┘ │
│ │
│ 총 소요 기간: 약 5~7 영업일 │
└─────────────────────────────────────────────────────────────────────────────┘신청 URL: https://starium.site:8080/partner/register
신청 정보 입력:
┌─────────────────────────────────────────────────────────────────────────────┐
│ 파트너 신청서 Step 1/3 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 기업 정보 ────────────────────────────────────────────────────────────┐ │
│ │ 회사명 * [ ] │ │
│ │ 사업자등록번호 * [ - - ] │ │
│ │ 대표자명 * [ ] │ │
│ │ 업종 * [ 제약사 ▼ ] │ │
│ │ 설립일 [ / / ] │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 연락처 정보 ──────────────────────────────────────────────────────────┐ │
│ │ 회사 주소 * [ ] │ │
│ │ 대표 전화 * [ ] │ │
│ │ 담당자명 * [ ] │ │
│ │ 담당자 이메일 * [ ] │ │
│ │ 담당자 연락처 * [ ] │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [이전] [다음] [임시저장] │
└─────────────────────────────────────────────────────────────────────────────┘| 서류 | 설명 | 형식 | 필수 |
|---|---|---|---|
| 사업자등록증 | 최근 발급본 | ✓ | |
| 통신판매업 신고증 | 온라인 판매 시 필수 | ✓ | |
| 대표자 신분증 | 주민등록증 또는 운전면허증 | JPG/PDF | ✓ |
| 법인등기부등본 | 법인만 해당 | 법인만 | |
| 통장 사본 | 정산용 계좌 | JPG/PDF | ✓ |
| 서류 | 설명 | 필수 |
|---|---|---|
| 건강기능식품 제조업 등록증 | 식약처 발급 | ✓ |
| GMP 인증서 | 우수제조관리기준 | ✓ |
| 제품 성분 분석표 | 주요 상품별 | ✓ |
| 기능성 인증서 | 개별 인정형 해당 시 | 선택 |
| 상품 카탈로그 | PDF 또는 링크 | ✓ |
| 서류 | 설명 | 필수 |
|---|---|---|
| 의료기관 개설 허가증 | 보건소 발급 | ✓ |
| 의사 면허증 | 진료 의사 전원 | ✓ |
| 전문의 자격증 | 해당 시 | 선택 |
| 비대면 상담 시스템 확인서 | 자체 확인서 | ✓ |
| 의료배상책임보험 증서 | 의료 사고 대비 | ✓ |
| 서류 | 설명 | 필수 |
|---|---|---|
| 약국 개설 허가증 | 지자체 발급 | ✓ |
| 약사 면허증 | 담당 약사 | ✓ |
| 의약품 도매업 허가증 | 해당 시 | 선택 |
| 서류 | 설명 | 필수 |
|---|---|---|
| 의료기기 제조업 허가증 | 의료기기 해당 시 | 해당 시 |
| 제품 인증서 | KC, CE, FDA 등 | ✓ |
| 기술 사양서 | API 연동 관련 | ✓ |
| 개인정보 처리방침 | 데이터 수집 관련 | ✓ |
표준 계약 조건:
| 항목 | 내용 |
|---|---|
| 계약 기간 | 1년 (자동 갱신) |
| 해지 통보 | 30일 전 서면 통보 |
| 최소 판매 조건 | 없음 |
| 배타적 계약 | 비배타적 (타 플랫폼 판매 가능) |
| 손해배상 | 상호 계약 위반 시 실손해 배상 |
| 분쟁 해결 | 서울중앙지방법원 관할 |
Base URL:
https://starium.site:8080/api/v1
API 버전: v1
프로토콜: HTTPS (TLS 1.3)
데이터 형식: JSON
문자 인코딩: UTF-8
┌─────────────────────────────────────────────────────────────────────────────┐
│ API 인증 흐름 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 파트너 시스템 AI Medical Platform │
│ │ │ │
│ │ 1. 로그인 요청 │ │
│ │ (apiKey, apiSecret) │ │
│ │────────────────────────────────▶│ │
│ │ │ │
│ │ 2. 토큰 발급 │ │
│ │ (accessToken, refreshToken) │ │
│ │◀────────────────────────────────│ │
│ │ │ │
│ │ 3. API 호출 │ │
│ │ (Authorization: Bearer token) │ │
│ │────────────────────────────────▶│ │
│ │ │ │
│ │ 4. 응답 │ │
│ │◀────────────────────────────────│ │
│ │ │ │
│ │ ... (토큰 만료 시) ... │ │
│ │ │ │
│ │ 5. 토큰 갱신 요청 │ │
│ │ (refreshToken) │ │
│ │────────────────────────────────▶│ │
│ │ │ │
│ │ 6. 새 토큰 발급 │ │
│ │◀────────────────────────────────│ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘products:read - 상품 조회products:write - 상품 등록/수정orders:read - 주문 조회orders:write - 주문 상태 변경settlements:read - 정산 조회⚠️ 중요: API Secret은 생성 시 한 번만 표시됩니다. 안전하게 보관하세요.
요청:
POST /api/v1/auth/partner/login
Content-Type: application/json
{
"apiKey": "pk_live_abc123def456...",
"apiSecret": "sk_live_xyz789..."
}응답 (성공):
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwYXJ0bmVyXzEyMyIsInNjb3BlcyI6WyJwcm9kdWN0czpyZWFkIiwicHJvZHVjdHM6d3JpdGUiXSwiaWF0IjoxNzAxMjM0NTY3LCJleHAiOjE3MDEzMjA5Njd9.abc123...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"tokenType": "Bearer",
"expiresIn": 86400,
"refreshExpiresIn": 604800,
"scopes": ["products:read", "products:write", "orders:read", "orders:write"]
}
}응답 (실패):
{
"success": false,
"error": {
"code": "AUTH_INVALID_CREDENTIALS",
"message": "API 키 또는 Secret이 올바르지 않습니다."
}
}POST /api/v1/auth/partner/refresh
Content-Type: application/json
{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}GET /api/v1/partner/products
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/jsonGET /api/v1/partner/products?page=1&limit=20&status=ACTIVE
Authorization: Bearer {token}Query Parameters:
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page |
number | X | 페이지 번호 (기본: 1) |
limit |
number | X | 페이지당 항목 수 (기본: 20, 최대: 100) |
status |
string | X | 상태 필터 (ACTIVE, INACTIVE, OUT_OF_STOCK) |
category |
string | X | 카테고리 필터 |
search |
string | X | 상품명 검색 |
sortBy |
string | X | 정렬 기준 (name, price, stock, createdAt) |
sortOrder |
string | X | 정렬 순서 (asc, desc) |
응답:
{
"success": true,
"data": [
{
"id": "prod_abc123",
"name": "프리미엄 오메가-3 1000mg",
"category": "SUPPLEMENT",
"subcategory": "오메가3",
"price": 35000,
"originalPrice": 45000,
"discountRate": 22,
"stock": 500,
"status": "ACTIVE",
"images": [
"https://storage.hospital.com/products/omega3-1.jpg",
"https://storage.hospital.com/products/omega3-2.jpg"
],
"ingredients": {
"EPA": "500mg",
"DHA": "300mg",
"비타민E": "10mg"
},
"description": "고농축 오메가-3 건강기능식품",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-11-30T15:45:00Z",
"salesCount": 1250,
"rating": 4.8,
"reviewCount": 245
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 156,
"totalPages": 8
}
}POST /api/v1/partner/products
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "프리미엄 오메가-3 1000mg",
"category": "SUPPLEMENT",
"subcategory": "오메가3",
"price": 35000,
"originalPrice": 45000,
"stock": 1000,
"sku": "OMEGA3-1000-001",
"barcode": "8801234567890",
"ingredients": {
"EPA": "500mg",
"DHA": "300mg",
"비타민E": "10mg"
},
"nutrition": {
"servingSize": "1캡슐 (1g)",
"calories": 10,
"fat": "1g"
},
"description": "고농축 오메가-3 건강기능식품입니다.",
"shortDescription": "EPA 500mg + DHA 300mg 고함량",
"images": [
"https://storage.hospital.com/products/omega3-1.jpg"
],
"warnings": [
"임산부 섭취 전 의사 상담 권장",
"개봉 후 냉장 보관"
],
"storage": "직사광선을 피해 서늘한 곳에 보관",
"expirationMonths": 24,
"manufacturer": "(주)건강제약",
"origin": "대한민국",
"certifications": ["GMP", "HACCP"],
"tags": ["오메가3", "EPA", "DHA", "심혈관"]
}응답 (성공):
{
"success": true,
"data": {
"id": "prod_xyz789",
"name": "프리미엄 오메가-3 1000mg",
"status": "PENDING_REVIEW",
"createdAt": "2025-11-30T16:00:00Z"
},
"message": "상품이 등록되었습니다. 관리자 검토 후 활성화됩니다."
}PATCH /api/v1/partner/products/{productId}/stock
Authorization: Bearer {token}
Content-Type: application/json
{
"stock": 1500,
"reason": "입고"
}응답:
{
"success": true,
"data": {
"id": "prod_abc123",
"previousStock": 500,
"currentStock": 1500,
"updatedAt": "2025-11-30T16:30:00Z"
}
}GET /api/v1/partner/orders?status=PAID&startDate=2025-11-01&endDate=2025-11-30
Authorization: Bearer {token}Query Parameters:
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
status |
string | X | 주문 상태 필터 |
startDate |
date | X | 시작일 (YYYY-MM-DD) |
endDate |
date | X | 종료일 (YYYY-MM-DD) |
page |
number | X | 페이지 번호 |
limit |
number | X | 페이지당 항목 수 |
응답:
{
"success": true,
"data": [
{
"id": "order_abc123",
"orderNumber": "ORD-2025-001234",
"status": "PAID",
"customer": {
"name": "홍*동",
"phone": "010-****-5678"
},
"items": [
{
"productId": "prod_xyz789",
"productName": "프리미엄 오메가-3 1000mg",
"quantity": 2,
"price": 35000,
"subtotal": 70000
}
],
"shipping": {
"name": "홍길동",
"phone": "010-1234-5678",
"zipCode": "12345",
"address": "서울시 강남구 테헤란로 123",
"addressDetail": "456호",
"memo": "부재 시 경비실"
},
"payment": {
"method": "CARD",
"totalAmount": 73000,
"shippingFee": 3000,
"discountAmount": 0
},
"orderedAt": "2025-11-30T14:30:00Z",
"paidAt": "2025-11-30T14:35:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"totalPages": 3
}
}PATCH /api/v1/partner/orders/{orderId}/shipping
Authorization: Bearer {token}
Content-Type: application/json
{
"status": "SHIPPED",
"trackingNumber": "1234567890123",
"carrier": "CJ대한통운",
"carrierCode": "CJ"
}지원 택배사 코드:
| 코드 | 택배사 |
|---|---|
CJ |
CJ대한통운 |
HANJIN |
한진택배 |
LOTTE |
롯데택배 |
POST |
우체국택배 |
LOGEN |
로젠택배 |
EPOST |
우체국 EMS |
응답:
{
"success": true,
"data": {
"orderId": "order_abc123",
"status": "SHIPPED",
"trackingNumber": "1234567890123",
"carrier": "CJ대한통운",
"trackingUrl": "https://www.cjlogistics.com/tracking?no=1234567890123",
"shippedAt": "2025-11-30T16:00:00Z"
},
"message": "배송 정보가 등록되었습니다. 고객에게 알림이 발송됩니다."
}GET /api/v1/partner/settlements?year=2025&month=11
Authorization: Bearer {token}응답:
{
"success": true,
"data": {
"period": {
"year": 2025,
"month": 11,
"startDate": "2025-11-01",
"endDate": "2025-11-30"
},
"summary": {
"totalSales": 15000000,
"orderCount": 320,
"refundAmount": 500000,
"platformFee": 2175000,
"paymentFee": 362500,
"netSettlement": 11962500
},
"breakdown": {
"byCategory": [
{
"category": "SUPPLEMENT",
"sales": 12000000,
"orders": 260
},
{
"category": "IOT_DEVICE",
"sales": 3000000,
"orders": 60
}
],
"byProduct": [
{
"productId": "prod_abc123",
"productName": "프리미엄 오메가-3",
"sales": 3500000,
"orders": 100
}
]
},
"status": "PENDING",
"scheduledPaymentDate": "2025-12-15"
}
}파트너 대시보드 → 설정 → 웹훅에서 설정
지원 이벤트:
| 이벤트 | 설명 |
|---|---|
order.created |
신규 주문 생성 |
order.paid |
주문 결제 완료 |
order.cancelled |
주문 취소 |
order.refund_requested |
환불 요청 |
product.approved |
상품 승인 |
product.rejected |
상품 거부 |
settlement.completed |
정산 완료 |
{
"event": "order.paid",
"timestamp": "2025-11-30T14:35:00Z",
"data": {
"orderId": "order_abc123",
"orderNumber": "ORD-2025-001234",
"totalAmount": 73000,
"items": [...]
},
"signature": "sha256=abc123..."
}const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expectedSignature = 'sha256=' +
crypto.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}| 코드 | HTTP | 설명 | 해결 방법 |
|---|---|---|---|
AUTH_TOKEN_INVALID |
401 | JWT 토큰 무효 | 토큰 재발급 |
AUTH_TOKEN_EXPIRED |
401 | JWT 토큰 만료 | 토큰 갱신 |
AUTH_SCOPE_INSUFFICIENT |
403 | 권한 부족 | API 키 권한 확인 |
PRODUCT_NOT_FOUND |
404 | 상품 없음 | 상품 ID 확인 |
PRODUCT_OUT_OF_STOCK |
409 | 재고 부족 | 재고 업데이트 |
PRODUCT_DUPLICATE_SKU |
409 | SKU 중복 | SKU 변경 |
ORDER_NOT_FOUND |
404 | 주문 없음 | 주문 ID 확인 |
ORDER_INVALID_STATUS |
400 | 잘못된 주문 상태 변경 | 상태 흐름 확인 |
VALIDATION_ERROR |
400 | 입력값 검증 실패 | 요청 데이터 확인 |
RATE_LIMIT_EXCEEDED |
429 | 요청 한도 초과 | 잠시 후 재시도 |
SYSTEM_INTERNAL_ERROR |
500 | 내부 오류 | 지원팀 문의 |
| 엔드포인트 유형 | 제한 | 윈도우 |
|---|---|---|
| 인증 API | 10회 | 1분 |
| 조회 API | 60회 | 1분 |
| 생성/수정 API | 30회 | 1분 |
| 웹훅 수신 | 1000회 | 1분 |
응답 헤더:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1701234567
Retry-After: 30건강기능식품 (SUPPLEMENT)
├── 비타민/미네랄
│ ├── 종합 비타민
│ ├── 비타민 D
│ ├── 비타민 C
│ ├── 비타민 B군
│ ├── 철분
│ └── 칼슘/마그네슘
├── 오메가3/오일
│ ├── 오메가-3
│ ├── 크릴 오일
│ └── 식물성 오메가
├── 유산균/소화
│ ├── 프로바이오틱스
│ ├── 프리바이오틱스
│ └── 소화 효소
├── 관절/뼈
│ ├── 글루코사민
│ ├── MSM
│ └── 콘드로이틴
├── 면역/항산화
│ ├── 프로폴리스
│ └── 홍삼/인삼
└── 기타
├── 수면 개선
└── 스트레스 관리
의약품 (MEDICINE) - 약국 전용
├── 일반의약품 (OTC)
└── 전문의약품 (처방전 필요)
IoT 기기 (IOT_DEVICE)
├── 스마트워치
├── 혈압계
├── 혈당계
├── 체중계
└── 수면 모니터
의료용품 (MEDICAL_SUPPLY)
├── 마스크
├── 소독제
└── 기타 용품필수 정보:
| 필드 | 설명 | 예시 | 제한 |
|---|---|---|---|
| 상품명 | 상품 이름 | “프리미엄 오메가-3 1000mg” | 2~100자 |
| 카테고리 | 분류 | SUPPLEMENT | 목록 선택 |
| 가격 | 판매가 (원) | 35000 | 1,000원 이상 |
| 재고 | 현재 재고 | 500 | 0 이상 |
| SKU | 재고관리코드 | OMEGA3-1000 | 고유값 |
| 설명 | 상품 설명 | - | 10~5000자 |
| 이미지 | 상품 이미지 | - | 최소 1장 |
선택 정보:
| 필드 | 설명 |
|---|---|
| 원가 | 할인 전 가격 |
| 바코드 | EAN-13 등 |
| 성분 정보 | JSON 형식 |
| 영양 정보 | 영양성분표 |
| 주의사항 | 섭취 주의사항 |
| 보관 방법 | 보관 조건 |
| 유통기한 | 개월 단위 |
| 제조사 | 제조 회사명 |
| 원산지 | 제조 국가 |
| 인증서 | GMP, HACCP 등 |
이미지 규격:
| 항목 | 규격 |
|---|---|
| 형식 | JPG, PNG, WebP |
| 최소 크기 | 800 x 800 px |
| 권장 크기 | 1200 x 1200 px |
| 최대 용량 | 5MB |
| 비율 | 1:1 (정사각형) |
| 배경 | 흰색 권장 |
| 이미지 수 | 최소 1장, 최대 10장 |
좋은 이미지 예시:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ✓ 정면 사진 │ │ ✓ 측면 사진 │ │ ✓ 상세 사진 │
│ │ │ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ [상품] │ │ │ │ [상품] │ │ │ │ [성분표] │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
│ │ │ │ │ │
│ 흰색 배경 │ │ 흰색 배경 │ │ 흰색 배경 │
└─────────────────┘ └─────────────────┘ └─────────────────┘| 상태 | 조건 | 노출 |
|---|---|---|
| 판매중 | 재고 > 10 | 정상 판매 |
| 품절임박 | 재고 1~10 | “품절임박” 뱃지 |
| 품절 | 재고 = 0 | 구매 불가 |
┌─────────────────────────────────────────────────────────────────────────────┐
│ 재고 알림 설정 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 알림 조건 │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 재고가 [ 50 ] 개 이하가 되면 알림 │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
│ 알림 방법 │
│ ☑ 이메일 (partner@company.com) │
│ ☑ SMS (010-1234-5678) │
│ ☐ 슬랙 웹훅 (URL 입력 필요) │
│ │
│ [저장] │
└─────────────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────────────┐
│ 주문 상태 흐름도 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ │
│ │ PENDING │ ← 고객 주문 생성 (결제 전) │
│ └────┬─────┘ │
│ │ │
│ │ 결제 완료 │
│ ▼ │
│ ┌──────────┐ │
│ │ PAID │ ← ⚠️ 파트너 액션 필요! │
│ │ │ 알림: 이메일, SMS, 대시보드 │
│ └────┬─────┘ │
│ │ │
│ │ 처리 시작 (파트너) │
│ ▼ │
│ ┌──────────┐ │
│ │PROCESSING│ ← 상품 준비 중 │
│ └────┬─────┘ │
│ │ │
│ │ 송장 등록 (파트너) │
│ ▼ │
│ ┌──────────┐ │
│ │ SHIPPED │ ← 배송 중 │
│ │ │ 고객에게 배송 알림 자동 발송 │
│ └────┬─────┘ │
│ │ │
│ │ 배송 완료 (택배사 연동) │
│ ▼ │
│ ┌──────────┐ │
│ │DELIVERED │ ← 배송 완료 │
│ │ │ 정산 대상 확정 │
│ └──────────┘ │
│ │
│ ┌─ 취소/환불 플로우 ───────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 결제 후 배송 전: PAID → CANCELLED → REFUNDED (자동) │ │
│ │ 배송 후: DELIVERED → REFUND_REQUESTED → REFUNDED (파트너 승인 필요) │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘알림 채널:
| 채널 | 설명 | 설정 방법 |
|---|---|---|
| 이메일 | 신규 주문 알림 | 파트너 대시보드 → 설정 |
| SMS | 긴급 알림 | 파트너 대시보드 → 설정 |
| 웹훅 | 시스템 연동 | API 웹훅 설정 |
| 대시보드 | 실시간 알림 | 기본 활성화 |
1. 주문 확인 (PAID 상태)
↓
2. 재고 확인
↓
3. 상품 포장
• 파손 방지 포장
• 냉장/냉동 상품: 아이스팩 동봉
• 송장 출력 및 부착
↓
4. 택배사 수거/접수
↓
5. 송장 번호 등록 (대시보드/API)
• 상태 자동 변경: PROCESSING → SHIPPED
• 고객 배송 알림 자동 발송
↓
6. 배송 추적
• 택배사 API 연동으로 자동 추적
• 배송 완료 시 자동 상태 변경| 항목 | 기준 | 패널티 |
|---|---|---|
| 출고 기한 | 결제 후 3영업일 | 지연 알림 |
| 송장 등록 | 출고 당일 | 지연 시 노출 순위 하락 |
| 배송 완료 | 출고 후 3영업일 | 택배사 책임 |
| 구분 | 기간 | 환불율 | 배송비 |
|---|---|---|---|
| 단순 변심 | 수령 후 7일 | 100% | 왕복 고객 부담 |
| 상품 불량 | 수령 후 30일 | 100% | 파트너 부담 |
| 오배송 | 수령 후 30일 | 100% | 파트너 부담 |
| 미수령 | 배송 중 | 100% | 배송비 환급 |
┌─────────────────────────────────────────────────────────────────────────────┐
│ 환불 처리 화면 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 환불 요청 #REF-2025-001234 │
│ │
│ ┌─ 주문 정보 ────────────────────────────────────────────────────────────┐ │
│ │ 주문 번호: ORD-2025-005678 │ │
│ │ 주문 일시: 2025-11-25 14:30 │ │
│ │ 결제 금액: ₩73,000 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 상품 정보 ────────────────────────────────────────────────────────────┐ │
│ │ 상품명: 프리미엄 오메가-3 1000mg │ │
│ │ 수량: 2개 │ │
│ │ 금액: ₩70,000 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 환불 사유 ────────────────────────────────────────────────────────────┐ │
│ │ 사유: 상품 불량 (캡슐 변색) │ │
│ │ 증빙 사진: │ │
│ │ [사진1] [사진2] │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 환불 금액: ₩73,000 (배송비 포함) │
│ │
│ 반품 주소 입력: │
│ [ ] │
│ │
│ [환불 거부] [환불 승인] │
└─────────────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────────────┐
│ 정산 계산 상세 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 예시: 2025년 11월 정산 (제약사) │
│ │
│ ┌─ 매출 집계 ────────────────────────────────────────────────────────────┐ │
│ │ 총 판매 금액 ₩15,000,000 │ │
│ │ 주문 건수 320건 │ │
│ │ 평균 주문 금액 ₩46,875 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 공제 항목 ────────────────────────────────────────────────────────────┐ │
│ │ 환불 금액 -₩500,000 │ │
│ │ 플랫폼 수수료 (15%) -₩2,175,000 │ │
│ │ 결제 수수료 (2.5%) -₩362,500 │ │
│ │ ───────────────────────────────────── │ │
│ │ 총 공제 금액 -₩3,037,500 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 정산 금액 ────────────────────────────────────────────────────────────┐ │
│ │ 최종 정산 금액 ₩11,962,500 │ │
│ │ 예정 지급일 2025-12-15 │ │
│ │ 입금 계좌 국민은행 ***-***-12345 (주)건강제약 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘경로: 파트너 대시보드 → 정산 관리 → 정산 내역
확인 가능 정보: - 기간별 매출 현황 - 주문별 상세 내역 - 수수료 상세 - 환불 내역 - 정산 예정/완료 금액
FHIR (Fast Healthcare Interoperability Resources)는 의료 데이터 교환을 위한 국제 표준입니다.
┌─────────────────────────────────────────────────────────────────────────────┐
│ FHIR 연동 아키텍처 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 병원 EMR AI Medical Platform │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ │ │ │ │
│ │ 환자 정보 │◀────────▶│ Patient Resource │ │
│ │ │ FHIR │ │ │
│ │ 진료 기록 │◀────────▶│ Encounter Resource │ │
│ │ │ R4 │ │ │
│ │ 생체 데이터 │◀────────▶│ Observation Resource│ │
│ │ │ API │ │ │
│ │ 처방 정보 │◀────────▶│ MedicationRequest │ │
│ │ │ │ │ │
│ └──────────────┘ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘| 리소스 | 설명 | 작업 |
|---|---|---|
| Patient | 환자 정보 | CRUD |
| Observation | 생체 신호 (혈압, 혈당 등) | CR |
| DiagnosticReport | AI 진단 결과 | R |
| MedicationRequest | 처방전 | CR |
| Appointment | 비대면 예약 | CRUD |
| Encounter | 진료 기록 | CR |
GET /fhir/Patient/patient_123
Authorization: Bearer {token}
Accept: application/fhir+json응답:
{
"resourceType": "Patient",
"id": "patient_123",
"meta": {
"versionId": "1",
"lastUpdated": "2025-11-30T10:00:00Z"
},
"identifier": [
{
"system": "http://hospital.com/patient-id",
"value": "P12345"
}
],
"name": [
{
"use": "official",
"family": "김",
"given": ["철수"]
}
],
"gender": "male",
"birthDate": "1990-01-01",
"telecom": [
{
"system": "phone",
"value": "010-1234-5678"
}
],
"address": [
{
"use": "home",
"city": "서울시",
"line": ["강남구 테헤란로 123"]
}
]
}POST /fhir/Observation
Authorization: Bearer {token}
Content-Type: application/fhir+json
{
"resourceType": "Observation",
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "vital-signs",
"display": "Vital Signs"
}
]
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
]
},
"subject": {
"reference": "Patient/patient_123"
},
"effectiveDateTime": "2025-11-30T10:30:00Z",
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8480-6",
"display": "Systolic blood pressure"
}
]
},
"valueQuantity": {
"value": 120,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8462-4",
"display": "Diastolic blood pressure"
}
]
},
"valueQuantity": {
"value": 80,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
}
]
}| 프로토콜 | 용도 | 포트 |
|---|---|---|
| MQTT | 실시간 데이터 전송 | 1883 (TCP), 8883 (TLS) |
| REST API | 디바이스 등록/관리 | 443 (HTTPS) |
| WebSocket | 실시간 양방향 통신 | 9002 |
브로커 정보: - 호스트:
mqtt.starium.site - 포트: 8883 (TLS) - 프로토콜: MQTT
v3.1.1 / v5.0
토픽 구조:
devices/{device_id}/data - 데이터 전송
devices/{device_id}/command - 명령 수신
devices/{device_id}/status - 상태 보고페이로드 예시 (심박 데이터):
{
"deviceId": "watch_abc123",
"userId": "user_xyz789",
"timestamp": "2025-11-30T10:30:00Z",
"type": "HEART_RATE",
"value": 72,
"unit": "bpm"
}POST /api/v1/partner/devices
Authorization: Bearer {token}
Content-Type: application/json
{
"model": "SmartWatch Pro 2",
"serialNumber": "SW-2025-001234",
"firmwareVersion": "2.1.0",
"capabilities": ["HEART_RATE", "BLOOD_PRESSURE", "SLEEP", "STEPS"],
"connectivityType": "BLUETOOTH_BLE"
}URL: https://starium.site:8080/partner
📊 대시보드
├── 개요 (매출, 주문, 인기상품)
├── 실시간 현황
└── 통계 분석
📦 상품 관리
├── 상품 목록
├── 신규 상품 등록
├── 재고 관리
└── 가격 관리
🛒 주문 관리
├── 신규 주문
├── 처리 중
├── 배송 중
├── 완료
└── 취소/환불
💰 정산 관리
├── 정산 내역
├── 세금계산서
└── 계좌 관리
📈 분석
├── 매출 분석
├── 상품 분석
├── 고객 분석
└── 트렌드
⚙️ 설정
├── 기업 정보
├── API 관리
├── 알림 설정
└── 보안 설정┌─────────────────────────────────────────────────────────────────────────────┐
│ [로고] 파트너 대시보드 [(주)건강제약 ▼] [알림🔔] [설정] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │ │
│ │ ┌─ 금월 현황 (2025.11) ─────────────────────────────────────────────┐ │
│ │ │ │ │
│ 사│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ 이│ │ │ 총 매출 │ │ 주문 건수 │ │ 신규 주문 │ │ 환불 건수 │ │ │
│ 드│ │ │ ₩15.2M │ │ 320 │ │ 12 │ │ 8 │ │ │
│ 바│ │ │ ▲ 12% │ │ ▲ 8% │ │ 🔴 즉시 │ │ ▼ 3% │ │ │
│ │ │ │ (전월대비) │ │ (전월대비) │ │ 처리 필요 │ │ (전월대비) │ │ │
│ 메│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ 뉴│ │ │ │
│ │ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌─ 인기 상품 TOP 5 ─────────────────────────────────────────────────┐ │
│ │ │ │ │
│ │ │ 1. 프리미엄 오메가-3 ₩3.5M 100건 ★4.8 │ │
│ │ │ 2. 프로바이오틱스 골드 ₩2.8M 85건 ★4.7 │ │
│ │ │ 3. 비타민D 3000IU ₩2.1M 78건 ★4.9 │ │
│ │ │ 4. 종합 멀티비타민 ₩1.9M 65건 ★4.6 │ │
│ │ │ 5. 루테인 40mg ₩1.5M 52건 ★4.8 │ │
│ │ │ │ │
│ │ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘| 유형 | 설명 | 수수료 |
|---|---|---|
| 기획전 참여 | 플랫폼 기획전 상품 노출 | 기본 수수료 |
| 광고 상품 | 검색 결과 상단 노출 | 클릭당 ₩50~200 |
| 할인 쿠폰 | 파트너 부담 할인 | 할인분 파트너 부담 |
| 번들 상품 | 묶음 상품 구성 | 기본 수수료 |
경로: 파트너 대시보드 → 마케팅 → 프로모션 신청
┌─────────────────────────────────────────────────────────────────────────────┐
│ 파트너 등급 체계 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ◇ 다이아몬드 월 매출 ₩100M 이상 │
│ │ └ 수수료 5% 할인, 전담 매니저, VIP 지원 │
│ │ │
│ ◆ 플래티넘 월 매출 ₩50M ~ ₩100M │
│ │ └ 수수료 3% 할인, 전담 매니저 │
│ │ │
│ ★ 골드 월 매출 ₩20M ~ ₩50M │
│ │ └ 수수료 2% 할인, 우선 지원 │
│ │ │
│ ● 실버 월 매출 ₩5M ~ ₩20M │
│ │ └ 수수료 1% 할인 │
│ │ │
│ ○ 브론즈 월 매출 ₩5M 미만 │
│ └ 기본 수수료 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘| 혜택 | 브론즈 | 실버 | 골드 | 플래티넘 | 다이아몬드 |
|---|---|---|---|---|---|
| 수수료 할인 | - | 1% | 2% | 3% | 5% |
| 전담 매니저 | - | - | - | ✓ | ✓ |
| 우선 지원 | - | - | ✓ | ✓ | ✓ |
| 광고 크레딧 | - | - | ₩100K | ₩300K | ₩500K |
| 교육 프로그램 | 기본 | 기본 | 고급 | 프리미엄 | VIP |
| 데이터 리포트 | 기본 | 기본 | 상세 | 상세 | 커스텀 |
| 언어 | 패키지 | 버전 |
|---|---|---|
| JavaScript | @aimedical/partner-sdk |
1.2.0 |
| Python | aimedical-partner |
1.2.0 |
| Java | com.aimedical:partner-sdk |
1.2.0 |
| PHP | aimedical/partner-sdk |
1.2.0 |
const { AIMedicalPartner } = require('@aimedical/partner-sdk');
const client = new AIMedicalPartner({
apiKey: 'pk_live_xxx',
apiSecret: 'sk_live_xxx'
});
// 상품 목록 조회
const products = await client.products.list({ status: 'ACTIVE' });
// 주문 처리
await client.orders.updateStatus('order_123', {
status: 'SHIPPED',
trackingNumber: '1234567890'
});| 채널 | 용도 | 응답 시간 |
|---|---|---|
| 이메일 | 일반 문의 | 24시간 이내 |
| 긴급 전화 | 시스템 장애 | 즉시 |
| 파트너 포털 | 티켓 문의 | 4시간 이내 |
| 슬랙 | 골드 이상 | 실시간 |
| 구분 | 연락처 |
|---|---|
| 파트너 지원 | partner@hospital.com |
| 기술 지원 | dev@hospital.com |
| FHIR 연동 | fhir@hospital.com |
| 긴급 상황 | 02-xxxx-xxxx |
Q1. API 키를 분실했습니다. A. 파트너 대시보드 → 설정 → API 관리에서 새 키를 발급받으세요. 기존 키는 즉시 무효화됩니다.
Q2. 정산 금액이 맞지 않습니다. A. 파트너 대시보드 → 정산 관리에서 상세 내역을 확인하세요. 이의 신청은 정산 후 5일 이내 가능합니다.
Q3. 상품 승인이 거부되었습니다. A. 거부 사유를 확인하고 수정 후 재등록하세요. 일반적인 거부 사유: 이미지 품질, 필수 정보 누락, 인증서 미비.
Q4. 배송이 지연되고 있습니다. A. 출고 기한(3영업일) 초과 시 패널티가 부과될 수 있습니다. 특별한 사유가 있는 경우 지원팀에 연락하세요.
품질 기준: - 모든 상품은 정품이어야 합니다 - 유통기한이 최소 6개월 이상 남아야 합니다 - 상품 설명은 정확해야 합니다 - 허위/과대 광고 금지
배송 기준: - 주문 후 3영업일 이내 출고 - 파손 방지 포장 필수 - 정확한 송장 번호 입력
고객 응대: - 문의에 24시간 이내 응답 - 친절하고 전문적인 응대 - 환불/교환 요청 신속 처리
| 위반 수준 | 조치 |
|---|---|
| 경고 | 1차 서면 경고 |
| 제재 | 노출 순위 하락, 프로모션 제한 |
| 정지 | 30일 판매 정지 |
| 해지 | 파트너 계약 해지 |
| 용어 | 설명 |
|---|---|
| SKU | Stock Keeping Unit, 재고관리코드 |
| GMV | Gross Merchandise Value, 총 거래액 |
| FHIR | Fast Healthcare Interoperability Resources |
| JWT | JSON Web Token |
| MQTT | Message Queuing Telemetry Transport |
| 코드 | 의미 |
|---|---|
| 200 | 성공 |
| 201 | 생성됨 |
| 400 | 잘못된 요청 |
| 401 | 인증 실패 |
| 403 | 권한 없음 |
| 404 | 리소스 없음 |
| 429 | 요청 한도 초과 |
| 500 | 서버 오류 |
| 버전 | 날짜 | 변경 내용 |
|---|---|---|
| 2.0.0 | 2025-11-30 | 전면 개편, 상세 내용 추가 |
| 1.0.0 | 2025-11-29 | 초기 버전 |
© 2025 AI Medical Platform. All Rights Reserved.
파트너십 문의: partner@hospital.com 기술 지원: dev@hospital.com