The Standard for Veterinary Pharmacological Intelligence,
SEON API & SDK
Empower your enterprise platform with real-time Drug-Nutrient Interaction (DNI) safety and organ metabolic load analytics.
B2B ENTERPRISE TARGET VERTICALS
🛡️ Pet Insurers
Loss-Ratio Control & Risk-Tiered Underwriting
DNI(약물-영양소 충돌) 및 장기 대사 부하를 정량화해 손해율(Loss-Ratio)을 낮추고, 언더라이팅 리스크를 차등화해요.
- • 예방 가능한 약물-영양소 사고를 사전에 차단
- • 간·신장 부하 지수 기반 계약 리스크 등급화
🛒 Pet E-Commerce
Safe Cross-Selling & Higher Basket Value
결제/장바구니 단계에서 실시간 DNI 충돌을 체크하고, 안전한 대체 영양소 Cross-selling(교차 판매)으로 객단가를 높여요.
- • 위험 조합 상품은 차단, 안전 대체 상품으로 자동 유도
- • 위험 조합 구매로 인한 반품·클레임 감소
🩺 Veterinary EMRs
Prescription Safety & Polypharmacy Alerts
전자처방 시스템 내부에 실시간 Chrono-DNI 알림과 다약제(Polypharmacy) 장기 부담 경고 모듈을 그대로 이식해요.
- • 처방 입력 즉시 상극 조합·격리 시간 경고
- • 다약제 복용 시 간·신장 누적 부담 표시
5-NODE ENGINE PIPELINE
🔬 Powered by our production-grade B2C diagnostic engine
아래 모듈은 실제 소비자 진단 서비스와 동일한 엔진·DB로 동작하는 Proof-of-Technology예요. 진단 폼을 직접 작성하고 실시간 DB 연산 리포트까지 확인해보세요.
B2B ENGINE MODULES — LIVE DEMO
기업 고객사 시스템에 그대로 이식되는
3대 B2B API 연산 모듈
아래 각 모듈은 Mock이 아닌 서온의 실제 프로덕션 연산 엔진과 DB에 100% 라이브로 연동돼요. 버튼을 누르면 실제 데이터 흐름을 직접 체험할 수 있어요.
100점 급여·복약 관리 스코어 & 데이터 리포트 연산 모듈
RER/DER 연산 및 3종 세부 점수를 기반으로 정밀 PDF 리포트를 생성하고 프로덕션 DB에 저장하는 라이브 엔진이에요.
간·신장 대사 부하율(%) 정량 연산 모듈
5종 식단·부재료 비율을 반영해 간/신장 배설 부하율을 정밀 연산하고, 자동 교정 레시피까지 실시간으로 생성해요.
처방약과 특정 영양 성분(칼슘, 철분, 비타민 등)이 몸속에서 서로 만나 약효가 떨어지거나 장기에 부담을 주는 '약물-영양소 체내 충돌(상극 반응)'을 의미합니다. 서온은 이 충돌을 피할 수 있는 안전한 투약 시간대를 계산해 드립니다.
상극 충돌 방지 24시간 안전 투약 스케줄 연산 모듈
처방약과 영양 성분 간 킬레이트 결합·흡수 방해 요소를 실시간 분석해 시간대별 안전 투약 스케줄을 산출해요.
※ 서온은 수의사의 직접적인 진료나 처방을 대신하지 않으며, 수의영양학 및 약학 수식 데이터를 기반으로 한 비진단(Non-Diagnostic) 의사결정 보조 API입니다.
READY TO INTEGRATE?
서온의 약학 지능 API를 귀사 서비스에 이식해보세요.
PoC(Proof of Concept) 또는 정식 계약(LOI) 문의부터 개발자 문서까지, 필요한 모든 자료를 안내해 드려요.
TECHNOLOGY ESCROW
서온(SEON)은 기술자료 임치가 완료된 기술입니다.
대·중소기업·농어업협력재단에 임치되어 있습니다. 임치기간은 2026-10-29부터 2027-10-28까지입니다.
계약번호 2026-02-32-4626
임치증 확인 →STEP 1
어떤 케어 플랜이 필요하신가요?
선택한 플랜에 따라 계산 지표와 추천 제품이 달라져요.
Live API Sandbox
3대 코어 엔진 통합 테스트 & B2B JSON Response Playground — [Send Request]는 배포된 SEON API 서버(탭별로 POST /v1/analyze · /v1/health-score · /v1/metabolic-load · /v1/chrono-dni)를 실제로 호출하고, 응답 RAW JSON을 그대로 보여줘요.
급여 & 복약 관리 스코어
현재 식단과 투약 관리를 평가하는 급여 & 복약 관리 스코어
INTERACTIVE REQUEST
· 서버가 유휴 상태였다면 첫 요청은 수십 초 걸릴 수 있어요.
👤 Pet Bio
🎯 Care Goal
🍽️ Feeding (Mix-feeding)
💊 Prescriptions
🧪 Supplements
{ } Live JSON Editor
REAL-TIME RAW JSON RESPONSE
LIVE WIDGET PREVIEW
API 응답 결과가 파트너(e-commerce / 보험사 / EMR) 앱에 이식됐을 때 실시간으로 렌더링되는 SEON 위젯이에요.
⬆️ 요청을 보내면(Send Request) 응답 결과가 이 위젯으로 렌더링돼요.
{ } LIVE JSON EDITOR
POST https://seonforivy.com/v1/metabolic-load · 설문을 완료하면 요청 JSON이 자동으로 입력돼요.
REAL-TIME RAW JSON RESPONSE
대사 부하 검문
개체 생체 정보와 오늘 먹인 사료·간식·영양제·처방약을 정밀 입력해 간·신장 대사 부하를 임상 수준으로 확인해요.
🐾 개체 생체 Baseline
🩺 진단 질환
장기 계통을 고른 뒤 세부 질환을 선택해주세요 — 여러 개를 함께 추가할 수 있어요.
🍽️ 주식 & 간식 정밀 입력
📚 SEON 프리셋 라이브러리 (feeding.preset_id)
브랜드/프리셋 선택 시 아래 값이 자동으로 채워져요 — 포장지나 레시피 실측치로 언제든 직접 수정하세요.
💊 영양제
해당 시 선택 후 제형과 회당 용량·1일 횟수를 입력해주세요 — 주요 대사 성분이 자동으로 매핑돼요.
🩺 처방약
🔒 처방약의 용량/횟수는 수의사 처방을 그대로 따르며, 1-Click 교정 시에도 절대 임의로 조정하지 않아요.
🫀 장기별 대사 부하 게이지
💡 [서온] 장기 대사 최적화 Action Plan
오늘 입력하신 Health Profile과 대사 부하 계산 결과를 바탕으로 맞춤 실행 지침을 안내해드려요.
⚡ 1-Click 영양 부하 자동 교정 레시피
처방약 용량/횟수는 그대로 유지하고, 사료·영양제·트릿 조정만으로 안전 범위(80% 이하)까지 낮춰드려요.
💧 오늘의 목표 음수량
{ } LIVE JSON EDITOR
POST https://seonforivy.com/v1/chrono-dni · 설문을 완료하면 요청 JSON이 자동으로 입력돼요.
REAL-TIME RAW JSON RESPONSE
1일 안전 투약 타임라인
아이의 약과 영양제가 서로 충돌하지 않는 안전한 복용 시각과 식사 스케줄을 자동으로 계산해 드려요.
① 기본 정보
② 복용 중인 약물 (② Metabolic 탭과 같은 입력)
처방전 사진을 올리면 AI가 약물 성분명·용량·카테고리를 자동으로 읽어드려요.
약 이름이 정확히 기억나지 않아도 괜찮아요. 증상만 알려주시면 일반적인 약물 계열을 유추해 타임라인에 반영해드려요.
약물이 없다면 추가하지 않고 넘어가셔도 돼요.
🩺 유추된 약물 복약 가이드
③ 복용 중인 영양제 (② Metabolic 탭과 같은 입력)
🚨 DNI Warning Banner
현재 등록된 약물·영양제 조합에서 상극이 감지되지 않았어요.
✅ 이렇게 급여해주세요
📅 1일 안전 투약 타임라인
아이의 건강 목표와 사료 정보를 입력하시면, 약물 상극을 피하는 최적의 1일 안전 투약 스케줄을 산출해 드려요.
🍽️ 급여 스케줄 입력
🍽️ 주식 & 부재료 ([대사 부하 검문] 탭과 완전히 동일한 식단 정보를 공유해요)
브랜드/프리셋 선택 시 아래 값이 자동으로 채워져요 — 포장지나 레시피 실측치로 언제든 직접 수정하세요.
복용 시각을 따로 정하지 않은 약·영양제는 서버가 이 식사 시간을 기준으로 배치하고, 충돌하는 영양제는 격리 시간만큼 떨어뜨려요.
🧮 자동 계산된 1일 권장 급여량
0.0g (DER 0kcal 기준)
SEON SDK & RESTful API Reference
5분 만에 위젯을 이식하거나, 서버 간 REST API로 실시간 DNI 충돌·대사 부하 지수를 받아보세요.
3-STEP QUICK INTEGRATION GUIDE
Obtain Partner API Key
Enterprise PoC 탭에서 신청하면 Sandbox API Key가 즉시 발급돼요. 프로덕션 키는 별도 계약 후 발급돼요.
Choose Integration Method (SDK Widget or REST API)
단 한 줄의 스크립트 태그(SDK)로 UI 위젯을 즉시 삽입하거나, 백엔드 서버 간 REST API를 직접 호출해 커스텀 로직을 구축해요.
Receive & Render Real-Time DNI & Strain Data
REST API 응답 데이터를 자사 백엔드 데이터베이스에 연동하거나, SDK 위젯을 통해 화면에 실시간 리포트로 렌더링해요.
CODE SNIPPETS
API SPECIFICATION
Request
| Base URL | https://seonforivy.com |
|---|---|
| Auth Header | X-SEON-API-KEY: <YOUR_PARTNER_KEY> (x-api-key도 허용) · Sandbox 데모 키는 seon_demo_pk_로 시작 |
| Content-Type | application/json |
| Region | 요청 본문 "region": "KR" | "US" (생략 시 US — 기존 연동 영향 없음) · KR이면 식약처 국내 동물약 사전(11,850품목)을 먼저 조회 · 응답에 region·drug_matches 에코 |
| Rate Limit | 60 req/min (키 단위) · Production은 계약 조건에 따라 조정 |
| Interoperability | HL7/FHIR 호환 응답 매핑 (fhir_compatible: true) |
Endpoints
| Endpoint | 필수 입력 | 선택 입력 (없으면 note 표기) | 주요 출력 |
|---|---|---|---|
POST /v1/analyze통합 (①②③ 전체) | pet_bio | care_goal · feeding · prescriptions · supplements | 아래 Response Fields 전체 |
POST /v1/health-score① Regimen Management | pet_bio (weight_kg, bcs, age_years, conditions) · care_goal | prescriptions → 없으면 health_score_note: "처방약 미입력 — 복약 점수는 요청에 포함된 항목만 반영"pet_bio.activity (inactive 1.2 · normal 1.6 · active 1.8 · working 2.0)feeding · supplements → 세부 점수·칼로리 갭 계산 (②와 같은 스키마)care_goal.weekly_rate_pct (0.5–3, 기본 1.2)pet_bio.diseases (질환 코드, GET /v1/diseases) → 질환별 영양 기준 감점·안내feeding.*.preset_id (GET /v1/presets) → 비어 있는 성분 칸 자동 채움 | health_score · health_light · score_blockers · rer_kcal · der_kcal · der_note · sub_scores · weight_plan · daily_calories_note · bloodwork (pet_bio.bloodwork가 있을 때 — IRIS 3–4단계는 인 기준 0.5% DM) · diseases · diet_nutrients_dm · preset_applied |
POST /v1/metabolic-load② Metabolic Load | pet_bio · feeding · prescriptions | supplements · care_goal → 없으면 metabolic_load_note: "영양제 가중치·감량 목표 미반영"feeding.main_diet.phosphorus_mg_per_100g → 신장 질환견 식량 기본 부하 (없으면 미반영 사유)pet_bio.life_stage (puppy/junior/adult/senior)pet_bio.bloodwork (creatinine · sdma · bun · upc · systolic_bp · alt · alp) → IRIS 단계 가중치는 신장 부하율에만 ×1.0/1.2/1.35/1.5. ALT·ALP와 간 수치 선택값은 경고만 하고 점수·간 대사 부하에는 넣지 않음pet_bio.diseases → 질환 가중치(같은 장기는 최대값, 곱하지 않음)feeding.*.preset_id → 성분 칸 자동 채움 | hepatic_strain_index · renal_strain_index · *_status · *_note · daily_water_ml · actual_water_ml · water_observed · bloodwork · diseases · preset_applied |
POST /v1/chrono-dni③ Chrono-DNI | prescriptions · supplements (각 항목 time_of_day, 또는 아래 식사 시간 기준점) | breakfast_time · dinner_time ("HH:MM") → time_of_day가 없는 약·영양제를 식사 시간 기준으로 자동 배치 (약 1회 아침 · 2회 아침/저녁 · 3회 이상 그 사이 균등, 상극 영양제는 격리 시간만큼 떨어뜨림)약 이름은 제품명(예: 아포퀠)도 가능 — 성분명으로 매칭 | dni_conflict_detected · conflicts (generic_name·mechanism 포함) · isolation_hours · timeline · timeline_24h · timeline_auto_placed · meal_anchors · safe_alternatives |
GET /v1/presets프리셋 라이브러리 278종 | — | q (이름 검색) · category (RAW_INGREDIENT · COMMERCIAL_FOOD · SNACK_TOPPING · CLINICAL_DIET · SUPPLEMENT_PRODUCT) · limit (기본 50, 최대 300) · offsetGET /v1/presets/:id → 1건 (없으면 404) | total · items[] (수분·조단백·조지방·칼슘·인·나트륨·kcal · suggested_type) |
GET /v1/diseases진단 질환 50종 | — | — | organs[] (장기 7개) → diseases[] (code · name_kr · metabolic_load_weight · nutri_rule) — 장기 → 질환 2단 선택용 |
※ 선택 입력 note는 필드가 아예 없을 때만 붙어요. 빈 배열([])은 "해당 없음"으로 보고 note 없이 계산해요. ③에서 필수 필드가 없으면 status: "PARTIAL" + timeline_reason이 내려가요.
Response Codes
| Code | Meaning |
|---|---|
200 | OK — status: "SUCCESS"(전체 계산) 또는 "PARTIAL"(일부 입력 누락 → 해당 필드 null + *_status: "INSUFFICIENT_DATA" + *_reason) |
400 | Bad Request — 요청 본문이 올바른 JSON이 아님 |
401 | Unauthorized — 유효하지 않은 API Key |
422 | Unprocessable — 값이 유효 범위를 벗어남 (예: feeding.water_intake.observed_ml 음수, pet_bio.life_stage 허용값 외, age_months(총 월령)와 age_years 불일치, region이 KR/US 외, breakfast_time·dinner_time이 "HH:MM" 형식이 아님) |
429 | Too Many Requests — 분당 요청 한도(60회) 초과 |
500 | Server Error — 일시적 오류 (재시도 권장) |
Response Fields
| Field | Description |
|---|---|
status | SUCCESS / PARTIAL — 엔드포인트별로 자기 출력 필드 기준 판정 |
region · drug_matches | 적용된 사전 지역 · 약물별 인식 결과 (matched, matched_name, ndc_code, dictionary_region: KR/US) — drug_matches는 analyze·chrono-dni |
health_score · health_light | 급여 & 복약 관리 스코어 (0–100, 세부 점수 3종의 평균. 임신·수유는 칼로리를 빼고 영양·안전 2개의 평균). 계산된 점수가 없으면 null · 신호등 (green/yellow/red) |
score_blockers | 스코어 감점 요인 목록 |
rer_kcal · der_kcal · der_note | 휴식/1일 에너지 요구량 (kcal) · DER 계수 적용 근거 (1세 미만 성장기: 4개월 미만 RER × 3.0 / 4~12개월 미만 × 2.0) |
health_score_note | ① 선택 입력(처방약)이 없어 반영하지 못한 항목 |
hepatic_strain_index · renal_strain_index | 간/신장 대사 부하 지수 (0–100) · hepatic_status/renal_status (NORMAL <25 · MODERATE <60 · HIGH <85 · CRITICAL) |
hepatic_strain_note · renal_strain_note | 기저질환 가중치(x1.35) · 노령견 가중치(x1.15 — life_stage: senior, 미입력 시 7세 이상) 적용 근거 |
renal_food_load | 신장 질환견 식량 기본 부하 (0–100) = 사료 인 섭취량(mg/kg/day) ÷ 60 × 100, 약·영양제 부하에 합산 후 가중치(x1.35) |
food_phosphorus_mg_per_kg · food_phosphorus_mg_per_100kcal | 사료 인 섭취량 참고값 (phosphorus_mg_per_100g 입력 시) |
renal_water_note | 음수량 실측 시 신장 부하 보정 근거 (충족률 <50% +15 · 50–80% +5 · 80–100% 0 · ≥100% −15) |
metabolic_load_note | ② 선택 입력(영양제·감량 목표)이 없어 반영하지 못한 항목 |
daily_water_ml · actual_water_ml | 목표 음수량 · 실제 음수량 (ml) |
water_observed · water_note | true: observed_ml 실측 포함 "총 음수량" (0ml도 실측) / false: "식이를 통한 음수 추정치" |
daily_calories_kcal · daily_calories_note | 입력 급여량 기준 1일 섭취 칼로리 · 사료 ME(kcal_per_100g) 미입력 시 표준값 적용 안내 (건식 350 · 습식 90 kcal/100g) |
sub_scores | 세부 점수 (0–100): caloric_balance_score 일일 칼로리 적정성 · nutritional_completeness_score 영양소 & 식단 균형 · pharmacological_safety_index 복약 & 상호작용 관리. 감점 deductions[](score·points·reason), 안내 warnings[]. 계산 불가 시 null + *_status(NOT_REQUESTED/INSUFFICIENT_DATA/API_ERROR) + *_reason |
weight_plan | ① 목표 타임라인: direction(loss/gain/maintain) · current_weight_kg · target_weight_kg · target_source · target_daily_kcal · current_daily_kcal · daily_calorie_gap_kcal(섭취 − 목표, 음수면 부족) · weekly_rate_pct · weekly_change_kg · estimated_weeks · summary (예: "주당 -1.2% 감량 기준 약 16주 소요 (12kg → 10kg)") · gap_note. 성장기는 NOT_APPLICABLE |
drug_matches[].active_ingredients · generic_name | 제품명 → 주성분 매핑 결과 (예: 아포퀠 → Oclacitinib). 사전에 없는 약은 [] · null |
conflicts[].mechanism | 상극이 생기는 이유를 설명하는 한 문장 (킬레이트 결합·생균 사멸·영양소 고갈 등) |
timeline_24h | 00–23시 24칸: hour · status(DOSE 투약 / RESTRICTED 상극 영양제 금지 구간 / CONFLICT 투약이 금지 구간과 겹침 / SAFE) · label · items · restricted |
meal_anchors · timeline_auto_placed | 적용된 식사 시간 기준점 · 서버가 자동 배치한 항목과 시각 (자리를 못 찾은 영양제는 timeline_unplaced) |
dni_conflict_detected · conflicts | 약물-영양제 상극 여부 · 충돌 목록 (rule_type, isolation_hours, message 포함) |
isolation_hours · timeline | conflicts[].rule_type은 SEPARATE(시간 간격) · MONITOR(모니터링, 그 충돌의 isolation_hours는 null) · AVOID(회피). 응답 isolation_hours는 SEPARATE만의 최댓값이고, SEPARATE가 없으면 0. 기본 간격 2시간, 항생제×프로바이오틱스 3시간. 플루오로퀴놀론 × 칼슘·마그네슘·철·아연은 2시간이며 문구 끝에 라벨·수의사 지시 우선. 푸로세미드 × 칼슘·마그네슘은 MONITOR. 같은 약×영양소는 안전 점수에서 한 번만 감점하고, 사용자가 양쪽 시각을 입력해 SEPARATE 간격을 이미 지키면 그 충돌은 감점하지 않습니다. MONITOR MEDIUM은 감점하지 않습니다. 상호작용 감점 합계가 45를 넘으면 45만 반영하고 상한 적용 한 줄이 추가됩니다. 장기 대사 부하 감점은 그 상한 밖입니다. 시간대별 타임라인 |
safe_alternatives | 충돌 성분을 대체할 수 있는 안전 대체 성분 목록 |
*_status · *_reason | 계산 불가 필드는 0으로 채우지 않고 null + INSUFFICIENT_DATA + 사유로 내려가요 |
※ Live API Sandbox 탭은 위 엔드포인트를 실제로 호출해요(서버가 유휴 상태였다면 첫 응답은 수십 초 걸릴 수 있어요). 각 엔진 탭은 해당 엔드포인트(①=/v1/health-score · ②=/v1/metabolic-load · ③=/v1/chrono-dni)를, 통합 탭은 /v1/analyze를 호출해요.
ERROR CODES & FALLBACK GUIDE
400 Bad Request
{
"status": "ERROR",
"message": "400 Bad Request: 요청 본문이 올바른 JSON이 아닙니다."
}401 Unauthorized
{
"status": "UNAUTHORIZED",
"message": "401 Unauthorized: 유효하지 않은 API Key 입니다. (X-SEON-API-KEY 헤더 확인)"
}422 Unprocessable
{
"status": "ERROR",
"message": "water_intake.observed_ml는 0 이상의 숫자여야 합니다. (입력값: -10)"
}429 Too Many Requests
{
"status": "TOO_MANY_REQUESTS",
"message": "429 Too Many Requests: 분당 요청 한도(60회)를 초과했습니다. 잠시 후 다시 시도해주세요."
}ENTERPRISE COMPLIANCE
SEON API/SDK의 모든 출력은 진단·처방을 대체하지 않는 비진단(Non-Diagnostic) 의사결정 보조 신호예요. 통신 구간은 TLS 1.3, 저장 데이터는 AES-256으로 암호화돼요. 최종 진단·처방 판단은 반드시 수의사가 내려야 해요.
1. INSTALLATION
Web / WebView
사용 가능 · v1.3.0스크립트 태그 한 줄. 외부 의존성 없음(바닐라 JS), Shadow DOM으로 호스트 CSS와 격리돼요.
https://seonforivy.com/sdk/seon-sdk.js
TypeScript 타입: seon-sdk.d.ts · CDN: https://cdn.seonforivy.com/v1/sdk.js
React Native
사용 가능 · v1.2.0npm install @seon.forivy/react-native-sdk react-native-webview
Web 위젯을 WebView로 띄우고 onResult/onError를 타입으로 전달해요.
Flutter
사용 가능 · v1.2.0flutter pub add seon_flutter_sdk
같은 위젯 엔진 + Dart 타입 모델.
iOS (Swift)
사용 가능 · v1.3.0Swift Package Manager github.com/mayjin03/seon-ios-sdk · from: "1.3.0"
WKWebView 기반 SeonWidgetView.
Android (Kotlin)
사용 가능 · v1.3.0Gradle implementation("com.seonforivy:seon-sdk:1.3.0")
WebView 기반 SeonWidgetView.
앱 패키지 4종은 모두 위 Web 위젯을 공통 엔진으로 써요. 위젯이 개선되면 모든 플랫폼에 같은 화면·같은 Fail-safe 규칙이 적용돼요.
2. API KEY 적용 & 첫 화면
<div id="seon-widget"></div>
<script src="https://seonforivy.com/sdk/seon-sdk.js"></script>
<script>
SEON.init({
apiKey: 'seon_demo_pk_sandbox_key', // X-SEON-API-KEY 헤더로 전송돼요
target: '#seon-widget',
region: 'KR', // 선택 — KR이면 식약처 국내 동물약 사전 우선 (기본 US)
pet: { breed: '말티즈', weight_kg: 4.2, age_years: 10, age_months: 123, bcs: 5, conditions: ['kidney'] },
drugs: [{ name: '엔로삭신액', frequency_per_day: 2, time_of_day: ['08:00', '20:00'] }],
supplements: [{ name: '유산균', time_of_day: ['09:00'] }],
onResult: (res) => console.log('SEON 결과', res.status, res.drug_matches),
onError: (err) => console.warn('SEON 오류', err.http_status, err.message)
});
</script>
• Sandbox 키는 seon_demo_pk_로 시작하고 Enterprise PoC 탭에서 바로 발급돼요. 프로덕션 키는 계약 후 발급돼요.
• 웹 위젯의 키는 브라우저에서 보이는 값이에요. 키를 화면에 두고 싶지 않다면 자사 서버에서 REST API를 호출하고, 받은 응답을 SEON.render()로 같은 위젯 UI에 그리면 돼요(아래 4번).
• 선언형으로도 붙일 수 있어요: <script src="…/seon-sdk.js" data-api-key="…" data-target="#seon-widget" data-region="KR"></script> (선택 data-api-base)
3. WIDGET OPTIONS — SEON.init(options)
| Option | Type | 기본값 | 설명 |
|---|---|---|---|
apiKey * | string | — | 파트너 API Key (없으면 init이 예외를 던져요) |
target | string | HTMLElement | '#seon-widget' | 위젯을 붙일 요소 |
region | 'KR' | 'US' | 'US' | 약물 사전 조회 순서. KR이면 식약처 국내 동물약(11,850품목) 우선 — 국내 제품명·한글 성분명 인식 |
pet | SeonPetBio | — | breed, weight_kg, age_years, age_months(총 월령 — 10세 3개월 = 123), life_stage(puppy|junior|adult|senior), bcs, neutered, activity, conditions |
drugs | (string | SeonPrescription)[] | [] | 처방약 — name, frequency_per_day, dose_mg, time_of_day. 문자열 축약 허용 |
supplements | (string | SeonSupplement)[] | [] | 영양제 — name, time_of_day, 선택 active_ingredients·dose |
care_goal | SeonCareGoal | — | 건강 목표 (primary_goal, target_weight_kg) |
feeding | SeonFeeding | — | 주사료·토핑·음수량 (없으면 칼로리·음수량은 계산하지 않아요) |
timeoutMs | number | 15000 | 요청 1회당 타임아웃(ms) |
retries | number | 2 | 재시도 횟수 — 네트워크 오류·타임아웃·429·5xx만, 지수 백오프(500ms → 1s → …) |
apiBase | string | https://seonforivy.com | API 서버 주소 (전용 도메인·프록시 사용 시) |
onResult | (res: SeonAnalyzeResponse) => void | — | SUCCESS/PARTIAL 응답 수신 시. PARTIAL도 정상 결과예요(필드별 *_status 확인) |
onError | (err: SeonError) => void | — | 최종 실패 시 { http_status, message, retryable, body }. 위젯은 이미 에러 카드로 폴백한 상태예요 |
SEON.init()은 { refresh() } 핸들을 반환해요 — 같은 설정으로 재요청·재렌더링. SEON.version으로 SDK 버전을, SEON.noConflict()로 기존 전역 SEON을 복원할 수 있어요.
4. 서버 응답을 위젯으로 그리기 — SEON.render()
// 자사 백엔드가 SEON REST API를 호출하고(키는 서버에만 보관), 결과 JSON만 프론트로 내려준 경우
const res = await fetch('/api/pet-report').then(r => r.json());
SEON.render({ target: '#seon-widget', response: res });
// 에러 응답도 같은 규칙의 에러 카드로 그려요
SEON.render({ target: '#seon-widget', response: { status: 'ERROR', message: '…' }, httpStatus: 401 });
5. FAIL-SAFE 화면 예시
계산할 수 없는 값은 0이나 기본값으로 채우지 않아요. 서버는 null + *_status(INSUFFICIENT_DATA 입력 부족 / API_ERROR 조회 실패) + *_reason을 내려주고, 위젯은 필드 단위로 경고를 보여주면서 계산된 지표는 그대로 표시해요. 아래 카드는 실제 SDK(SEON.render)가 예시 응답으로 그린 화면이에요.
① 정상 (SUCCESS)
② 일부 계산 불가 (PARTIAL · INSUFFICIENT_DATA)
③ 계산된 지표 없음 (전용 Fail-safe 카드)
④ 미인식 약물 (수치 미표시)
// 위젯 없이 결과를 직접 그릴 때도 같은 규칙을 지켜주세요
onResult: (res) => {
if (res.health_score === null && res.health_score_status) {
showNotice(res.health_score_reason); // "데이터 부족으로 계산 불가" — 0점으로 표시하지 않기
} else {
showScore(res.health_score);
}
}
6. ERROR CODES & RETRY
| http_status | 의미 | SDK 자동 재시도 | 위젯 화면 | 권장 처리 |
|---|---|---|---|---|
0 | 네트워크 오류 · 타임아웃(timeoutMs) | ✅ retries회 | CONNECTION ERROR 카드 | 연결 상태 확인 후 handle.refresh() |
400 | 요청 본문이 올바른 JSON이 아님 | — | 400 ERROR 카드 | 요청 직렬화 확인 |
401 | 유효하지 않은 API Key | — | 401 ERROR 카드 | 키·헤더 확인 (재시도해도 같은 결과) |
422 | 값이 허용 범위를 벗어남 (age_months·age_years 불일치, life_stage·region 허용값 외, 음수 음수량 등) | — | 422 ERROR 카드 + 사유 | err.message의 필드를 수정해 다시 호출 |
429 | 분당 요청 한도(60회/키) 초과 | ✅ retries회 | 429 ERROR 카드 | 호출 간격 조정 |
5xx | 일시적 서버 오류 | ✅ retries회 | CONNECTION ERROR 카드 | 잠시 후 handle.refresh() |
재시도 대기: 1회차 500ms → 2회차 1s → 3회차 2s (Exponential Backoff). 총 시도 = retries + 1, 각 시도마다 timeoutMs 적용. 400·401·422는 재시도해도 결과가 같아서 바로 onError로 넘어가요. err.retryable이 true면 SDK가 이미 재시도를 마친 최종 실패예요.
7. 앱 WebView 브릿지 메시지
window.ReactNativeWebView · window.SeonFlutter · webkit.messageHandlers.seon · window.SeonAndroid{ "source": "seon-sdk", "version": "1.3.0", "type": "result", "payload": { "status": "SUCCESS", … } }
{ "source": "seon-sdk", "version": "1.3.0", "type": "error", "payload": { "http_status": 401, "message": "…", "retryable": false, "body": { … } } }
8. 문구 원칙 (Non-Diagnostic)
위젯 문구에는 "진단" 표현을 쓰지 않아요. 결과는 위험도 스코어·의사결정 지원 정보로 표기하고, 카드 하단에 "본 위젯은 수의사의 판단을 돕는 의사결정 지원 정보를 제공합니다."가 항상 붙어요. 결과를 자체 화면으로 다시 그릴 때도 같은 원칙을 권장해요.
Enterprise PoC & Sandbox Key
보험사 · 커머스 · 수의 EMR 파트너를 위한 PoC 신청 창구예요. 신청과 동시에 Sandbox API Key가 발급돼요.
🔑 Sandbox vs Production License Key
- Sandbox Key — 신청 즉시 발급, Live API Sandbox에서 실제 SEON API 서버를 호출해볼 수 있어요.
- Production License Key — PoC 협의 및 계약(LOI) 후 SEON이 별도 발급해요.
문의 시 함께 알려주세요
💡 기술 사양 · SDK 연동 문의: seon.forivy@gmail.com