animal-medication-api/docs/API_SPEC.md

# 애니팜 투약지도서 API 명세서

> **Base URL:** `https://ap.0bin.in`  
> **Local:** `http://localhost:7002`  
> **Version:** 1.0.0  
> **Last Updated:** 2026-03-19

---

## 📋 엔드포인트 목록

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/health` | 헬스체크 |
| GET | `/api/products` | 약품 목록 조회 |
| POST | `/api/guide/pdf` | PDF 생성 |
| POST | `/api/guide/preview` | 미리보기 (메타데이터) |

---

## 1. 헬스체크

서버 상태 확인

### Request
```
GET /health
```

### Response
```json
{
  "status": "ok",
  "service": "anipharm-api",
  "timestamp": "2026-03-19T20:01:13.292109"
}
```

---

## 2. 약품 목록 조회

등록된 모든 약품 목록 반환

### Request
```
GET /api/products
```

### Response
```json
{
  "success": true,
  "count": 21,
  "products": [
    {
      "product_id": "MASTER-001",
      "name": "넥스가드 스펙트라",
      "category": "antiparasitic",
      "category_display": "올인원 구충제"
    },
    {
      "product_id": "MASTER-002",
      "name": "아시카프 츄어블정",
      "category": "nsaid",
      "category_display": "진통소염제 (NSAIDs)"
    }
    // ... 21개
  ]
}
```

---

## 3. PDF 생성

투약지도서 PDF 파일 생성 및 다운로드

### Request
```
POST /api/guide/pdf
Content-Type: application/json
```

### Request Body
```json
{
  "product_ids": ["MASTER-001", "MASTER-002", "MASTER-005"],
  "patient_name": "김남곤",
  "pet_name": "뽀삐",
  "pet_species": "푸들",
  "pet_age": "3세",
  "pharmacy_name": "청춘약국 동물약 전문상담",
  "pharmacy_tel": "033-481-0384"
}
```

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| product_ids | string[] | ✅ | 약품 ID 배열 |
| patient_name | string | ❌ | 보호자 이름 (기본: "보호자") |
| pet_name | string | ❌ | 반려동물 이름 (기본: "반려동물") |
| pet_species | string | ❌ | 품종 |
| pet_age | string | ❌ | 나이 |
| pharmacy_name | string | ❌ | 약국명 (기본: "청춘약국 동물약 전문상담") |
| pharmacy_tel | string | ❌ | 전화번호 (기본: "033-481-0384") |

### Response
- **Success:** `application/pdf` (PDF 파일 다운로드)
- **Error:**
```json
{
  "success": false,
  "error": "에러 메시지"
}
```

### cURL 예시
```bash
curl -X POST https://ap.0bin.in/api/guide/pdf \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["MASTER-001", "MASTER-002"],
    "patient_name": "김남곤",
    "pet_name": "뽀삐",
    "pet_species": "푸들",
    "pet_age": "3세"
  }' \
  --output 투약지도서.pdf
```

---

## 4. 미리보기 (메타데이터)

PDF 생성 전 약품 정보 및 예상 페이지 수 확인

### Request
```
POST /api/guide/preview
Content-Type: application/json
```

### Request Body
```json
{
  "product_ids": ["MASTER-001", "MASTER-002", "MASTER-005"]
}
```

### Response
```json
{
  "success": true,
  "drug_count": 3,
  "page_count": 1,
  "drugs": [
    {
      "id": "MASTER-001",
      "name": "넥스가드 스펙트라",
      "category": "antiparasitic",
      "has_image": true
    },
    {
      "id": "MASTER-002",
      "name": "아시카프 츄어블정",
      "category": "nsaid",
      "has_image": true
    },
    {
      "id": "MASTER-005",
      "name": "하트세이버 츄어블",
      "category": "antiparasitic",
      "has_image": true
    }
  ]
}
```

---

## 📦 등록된 약품 목록 (21개)

| ID | 이름 | 카테고리 |
|----|------|----------|
| MASTER-001 | 넥스가드 스펙트라 | antiparasitic |
| MASTER-002 | 아시카프 츄어블정 | nsaid |
| MASTER-003 | 아시엔로 50 | antibiotic |
| MASTER-004 | 세레니아 정 | antiemetic |
| MASTER-005 | 하트세이버 츄어블 | antiparasitic |
| MASTER-006 | 프로닐스팟 | antiparasitic |
| MASTER-007 | 오리더밀 | otic |
| MASTER-008 | 터비덤 스프레이 | antifungal |
| MASTER-009 | 클로르헥시딘 샴푸 | topical |
| MASTER-010 | 셀라이트 | antiparasitic |
| MASTER-011 | 멜록시캐시 CH | nsaid |
| MASTER-012 | 복합 개시딘 겔 | topical |
| MASTER-013 | 임팩트액 | antiparasitic |
| MASTER-014 | 안텔민 뽀삐/킹 | antiparasitic |
| MASTER-015 | 티어가드 정 | antibiotic |
| MASTER-016 | 액티벳정 | antibiotic |
| MASTER-017 | 아포퀠 | immunomodulator |
| MASTER-018 | 브라벡토 | antiparasitic |
| MASTER-019 | 심파리카 트리오 | antiparasitic |
| MASTER-020 | 가바펜틴 | analgesic |
| MASTER-021 | 메트로니다졸 | antibiotic |

---

## 🔧 서버 정보

| 항목 | 값 |
|------|-----|
| 프레임워크 | Flask |
| 포트 | 7002 |
| PM2 이름 | anipharm-api |
| PDF 엔진 | WeasyPrint |
| 페이지당 약품 | 4개 |

---

## 📝 변경 이력

| 날짜 | 버전 | 내용 |
|------|------|------|
| 2026-03-19 | 1.0.0 | 최초 배포 |