{"openapi":"3.0.3","info":{"title":"EDI 제약사 분류 API","version":"1.0.0","description":"처방·EDI 통계 이미지를 올리면 약품코드를 읽어 어느 제약사 약인지 자동으로 분류해 드립니다. 여러 제약사 약이 섞여 있어도 코드 기준으로 나눠 주고, 코드가 없는 문서는 약품명으로 후보 제약사를 추려 검수 시간을 줄여 줍니다. 자동 인식이라 문서 상태(사진 선명도·양식)에 따라 결과가 완벽하지 않을 수 있으니, 중요한 건은 확인을 권장합니다."},"servers":[{"url":"https://marketapi.nadoo.ai"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/balance":{"get":{"summary":"충전 잔액 조회","description":"현재 계정의 선불 충전 잔액(원)과 저잔액 알림 임계값을 반환합니다. 상품과 무관한 계정 단위 조회이며 과금되지 않습니다.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"balanceKrw":{"type":"integer","description":"현재 선불 잔액(원)"},"lowBalanceThresholdKrw":{"type":"integer","nullable":true,"description":"저잔액 이메일 알림 임계값(원). null=알림 꺼짐"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"잔액 마지막 변경 시각(ISO 8601). 충전/차감 이력이 없으면 null"}}},"example":{"balanceKrw":49800,"lowBalanceThresholdKrw":5000,"updatedAt":"2026-08-06T02:31:00.000Z"}}}},"401":{"description":"API 키 누락/무효 (invalid_key)"}}}},"/api/v1/uploads":{"post":{"summary":"대용량 업로드 URL 발급(presigned, 권장)","description":"base64 본문 한계(25MB·원본 ~18MB) 회피. uploadUrl 로 이미지 PUT 후 imageUrl 을 classify/classify-batch(-async) 에 전달(용량 무제한).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","description":"예: image/jpeg"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"type":"string"},"imageUrl":{"type":"string"},"expiresIn":{"type":"integer"}}}}}}}}},"/api/v1/edi-classify/classify":{"post":{"summary":"EDI 제약사 분류 — 단건","description":"처방·EDI 통계 이미지 → 약품코드(9자리) → 제약사 분류. 성공 호출당 70원(무료 10회 후). 비-EDI/빈결과는 자동 반려·환불(과금 제외). 자동 인식이라 100% 정확하지 않습니다. 요청 본문 25MB 초과 시 413(presigned 업로드 사용).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"재시도 이중 과금 방지. 같은 키+같은 본문은 재처리 없이 최초 결과 반환, 같은 키+다른 본문은 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"base64 이미지"},"imageUrl":{"type":"string","format":"uri","description":"이미지 https URL(서버 다운로드). image 와 택일"}}}}}},"responses":{"200":{"description":"분류 결과","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"요청 식별자(Idempotency-Key 와 동일)"},"imageId":{"type":"string","description":"이미지 콘텐츠 해시(파일명 미사용)"},"docType":{"type":"string","description":"edi=약품 통계표, non_edi=사업자등록증 등(자동 반려·과금 제외)"},"manufacturers":{"type":"array","description":"확정 — 약품코드(9자리)로 조회된 제약사","items":{"type":"object","properties":{"name":{"type":"string","description":"제약사명"},"codes":{"type":"array","items":{"type":"string"},"description":"확정된 9자리 약품코드"}}}},"candidates":{"type":"array","items":{"type":"string"},"description":"후보(선택) — 코드 없을 때 약품명으로 추정한 제약사(검수 권장). 없으면 생략"},"cost":{"type":"object","properties":{"krw":{"type":"number"},"free":{"type":"boolean"}}},"balanceKrw":{"type":"number"}}}}}},"400":{"description":"no_image(image/imageUrl 누락)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"no_image"}}}},"401":{"description":"API 키 누락/무효 (invalid_key)"},"402":{"description":"무료 소진 + 잔액 부족 (insufficient_credit)"},"404":{"description":"없는/종료된 API (product_not_found)"},"413":{"description":"요청 본문 25MB 초과 (payload_too_large) → presigned 업로드 사용","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payload_too_large","maxBytes":26214400}}}},"502":{"description":"처리 실패 — 과금분 자동 환불 (worker_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"worker_error","refunded":true}}}}}}},"/api/v1/edi-classify/classify-batch":{"post":{"summary":"EDI 제약사 분류 — 동기 배치(최대 30장)","description":"여러 이미지를 한 번에 처리하고 즉시 전체 결과 반환. 항목별 독립 과금(성공 70원, 비-EDI·실패 자동 환불).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"images":{"type":"array","items":{"type":"string"},"description":"base64 이미지 배열"},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}}}}}}},"responses":{"200":{"description":"배치 결과(부분 성공 포함)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyBatchResult"}}}}}}},"/api/v1/edi-classify/classify-batch-async":{"post":{"summary":"EDI 제약사 분류 — 비동기 대량(최대 500장)","description":"즉시 202(jobId·pollUrl) 반환 후 GET /api/v1/jobs/{id} 로 폴링.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}},"images":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer"},"pollUrl":{"type":"string"}}}}}}}}},"/api/v1/jobs/{id}":{"get":{"summary":"배치 작업 폴링","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"진행/결과","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyBatchResult"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"ClassifyBatchResult":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer"},"done":{"type":"integer"},"ok":{"type":"integer"},"failed":{"type":"integer"},"totalCostKrw":{"type":"number"},"balanceKrw":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string"},"docType":{"type":"string"},"manufacturers":{"type":"array","items":{"type":"object"}},"candidates":{"type":"array","items":{"type":"string"}},"error":{"type":"string"}}}}}}}}}