> 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` 상태 코드를 반환합니다. 에러 응답의 상세 내용을 통해 에러 원인을 확인할 수 있습니다. 자세한 내용은 [에러 응답](#에러-응답)을 참고하세요.

### 날짜 및 시간 형식

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

`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`: 너무 큰 값


## 엔드포인트

- [인증](/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): 2
- [예약](/docs/openapi/schedule.md): 31
- [통계](/docs/openapi/statistics.md): 6
- [타겟 국가](/docs/openapi/target-country.md): 1
- [시술권](/docs/openapi/ticket.md): 1
- [내원객](/docs/openapi/visitor.md): 8

## 스키마

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