> 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 is available only to development teams at hospitals that use the KOS solution.

For details, contact the KOS sales representative for your hospital.

This document can be checked through the [OpenAPI Spec](/openapi.yaml) file.

### API Request Method

1. KOS OpenAPI uses POST for all requests, including queries, updates, and deletions.

2. Except for authentication APIs, every request must include an Auth Token in the `Authorization` header. For details, see [Authentication](/docs/openapi/authorization).

3. All error responses return the `400` status code regardless of error type. Check the error response details to identify the cause. For details, see [Error Response](#error-response).

### Date And Time Format

Fields that convey date or time follow the format specified in each field description.

Fields documented as `format: date-time` use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date-time strings. Fields specified as UTC deliver values in the UTC timezone.

### Country Code Format

Country codes used in product and target country queries are [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) strings.

The country code for phone numbers follows the `countryCode` description in the phone number schema.

<Callout type="caution">
<p>For target countries used to decide which products to show and which prices to apply, <strong>"Other countries" is represented as <code>ETC</code></strong>.</p>
<p>For details, see <a href="/docs/openapi/targetcountry">Target Country</a>.</p>
</Callout>

### Error Response

When a query or command cannot be processed successfully, the API returns a `400` HTTP status code with an error response like this:

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

- `key`: the missing field name or the field name that has an invalid value
- `reason`: the error reason
  - `TooShort`: the string is too short
  - `TooLong`: the string is too long
  - `Required`: a required field is missing
  - `Duplicated`: duplicated value
  - `InvalidTimeRange`: time range validation failed
  - `NotAvailable`: not available
  - `NotFound`: target not found
  - `TooSmall`: the value is too small
  - `TooBig`: the value is too large


## Endpoints

- [Authentication](/en/docs/openapi/authorization.md): 1
- [Image](/en/docs/openapi/image.md): 2
- [Prepaid Card](/en/docs/openapi/prepaid-card.md): 3
- [Product](/en/docs/openapi/product.md): 15
- [Payment](/en/docs/openapi/purchase.md): 2
- [Schedule](/en/docs/openapi/schedule.md): 31
- [Statistics](/en/docs/openapi/statistics.md): 6
- [Target Country](/en/docs/openapi/target-country.md): 1
- [Treatment Ticket](/en/docs/openapi/ticket.md): 1
- [Client](/en/docs/openapi/visitor.md): 8

## Schemas

[Schemas](/en/docs/openapi/~schemas.md)