> Agent-readable docs index: /llms.txt. Fetch only the needed Markdown pages first; use /docs.zip only for broad search after checking /docs-manifest.json or /docs.zip.sha256.

# KOS OpenAPI

KOS OpenAPI는 KOS 솔루션을 사용하는 병원들의 개발팀만 사용 가능합니다.

자세한 사항은 해당 병원의 KOS 영업 담당자를 통해 문의 바랍니다.

이 문서는 [OpenAPI Spec](/openapi.yaml) 파일을 통해 확인할 수 있습니다.

### API 요청 방법

1. KOS OpenAPI는 조회, 수정, 삭제 등 모두 POST 방식으로 요청합니다.

2. 인증 관련을 제외한 모든 요청은 `Authorization` 헤더에 인증 토큰(Auth Token)이 포함되어야 합니다. 자세한 내용은 [인증 방법](/docs/openapi/authorization)을 참고하세요.

3. 에러 응답은 대부분 `400` 상태 코드를 반환합니다. 에러 응답의 상세 내용을 통해 에러 원인을 확인할 수 있습니다. 자세한 내용은 [에러 응답](#에러-응답)을 참고하세요. 인증 토큰이 없거나 만료되면 `401`, [호출 한도](#호출-한도)를 넘으면 `429`를 반환합니다.

### 날짜 및 시간 형식

날짜나 시간을 전달하는 필드는 각 필드 설명에 명시된 형식을 따릅니다.

`format: date-time`으로 문서화된 필드는 [ISO 8601](https://ko.wikipedia.org/wiki/ISO_8601) date-time 문자열을 사용합니다. UTC가 명시된 필드는 UTC 시간대 값을 전달합니다.

### 국가 코드 형식

상품과 타겟 국가 조회에서 사용하는 국가 코드는 [ISO 3166-1 alpha-2](https://ko.wikipedia.org/wiki/ISO_3166-1_alpha-2) 문자열을 사용합니다.

전화번호의 국가번호는 전화번호 스키마의 `countryCode` 설명을 따릅니다.

<Callout type="caution">
<p>단, 국가별로 보여줄 상품을 지정할 수 있고, 해당 국가에 맞는 수가를 설정하기 위한, '타겟 국가'의 <strong>'그 외 국가'는 <code>ETC</code></strong> 로 표기합니다.</p>
<p>자세한 설명은 <a href="/docs/openapi/targetcountry">타겟 국가</a>를 확인하세요.</p>
</Callout>

### 에러 응답

조회 혹은 명령을 정상적으로 처리할 수 없는 경우, `400` HTTP 상태 코드와 함께 아래와 같은 에러 응답이 돌아옵니다.

```json
{
  "status": 400,
  "message": "InvalidCommandException",
  "className": "InvalidCommandException",
  "errorProperties": [
    {
      "key": "{{ Key }}",
      "reason": "{{ ErrorReason }}"
    }
  ]
}
```

- `key`: 누락된 필드명 혹은 잘못된 값을 가진 필드명
- `reason`: 에러 원인
  - `TooShort`: 문자열이 너무 짧음
  - `TooLong`: 문자열이 너무 길음
  - `Required`: 필수 항목이 누락됨
  - `Duplicated`: 중복됨
  - `InvalidTimeRange`: 시간 범위 유효성 검사 실패
  - `NotAvailable`: 사용 불가
  - `NotFound`: 대상이 없음
  - `TooSmall`: 너무 작은 값
  - `TooBig`: 너무 큰 값

### 호출 한도

같은 IP에서 최근 1분 동안 3,000회를 넘게 호출하면 요청이 차단되고 `429` 상태 코드가 반환됩니다. 호출 수는 API Key나 엔드포인트와 관계없이 IP 단위로 합산합니다.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

```json
{
  "status": 429,
  "className": "TooManyRequests",
  "message": "Too many requests. Please retry after 1 minute."
}
```

`Retry-After` 헤더에 적힌 시간(초)이 지난 뒤 다시 요청하세요. 호출 한도는 KOS 정책에 따라 바뀔 수 있습니다.


## 엔드포인트

- [직원](/docs/openapi/account.md): 1
- [인증](/docs/openapi/authorization.md): 1
- [이미지](/docs/openapi/image.md): 2
- [선불카드](/docs/openapi/prepaid-card.md): 3
- [상품](/docs/openapi/product.md): 15
- [수납](/docs/openapi/purchase.md): 3
- [만족도 조사](/docs/openapi/satisfactionsurvey.md): 1
- [예약](/docs/openapi/schedule.md): 37
- [통계](/docs/openapi/statistics.md): 7
- [타겟 국가](/docs/openapi/target-country.md): 1
- [시술권](/docs/openapi/ticket.md): 1
- [내원객](/docs/openapi/visitor.md): 9

## 스키마

[스키마](/docs/openapi/~schemas.md)