> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/platform/create-customer.md).

# 신규 고객 생성 API

플랫폼 서비스에서 특정 비즈니스에 고객을 생성할 수 있는 API를 제공합니다.

<br>

## `POST` kit-api/v1/customers

Method: POST\
Endpoint: kit-api/v1/customers

<br>

## Example

```
.../kit-api/v1/customers
```

```json
{
  "input": {
    "title": "김철수",
    "customKey": "A5-k159402",
    "ceo": "김대표",
    "registrationNumber": "789-30-01467",
    "address": "서울특별시 서초구 프릭스로 551",
    "industry": "정보통신업",
    "category": "응용 소프트웨어 개발 및 공급업",
    "managers": [
      {
        "name": "이담당자",
        "email": "prix-customer-manager@email.com",
        "position": "이담당자 직책",
        "note": "이담당자 메모",
        "contact": "이담당자 연락처",
        "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할
      }
    ]
  }
}
```

<br>

## Request Body

| Key                      | Description                                                             | Required |
| ------------------------ | ----------------------------------------------------------------------- | -------- |
| input.title              | 한글, 영어 대소문자, 숫자, -, , \_, 등으로 구성된 40자 이하의 새로 생성할 고객 이름 (같은 비즈니스 내 중복불가) | yes      |
| input.customKey          | 새로 생성할 고객에게 할당하고 싶은 영어 대소문자, 숫자, -, \_로 구성된 40자 이하의 키 (같은 비즈니스 내 중복불가)  | no       |
| input.ceo                | 새로 생성할 고객 정보 - 대표자명                                                     | no       |
| input.registrationNumber | 새로 생성할 고객 정보 - 사업자등록번호 (10자리 숫자, 해외기업은 15자리까지)                          | no       |
| input.address            | 새로 생성할 고객 정보 - 사업장 주소                                                   | no       |
| input.industry           | 새로 생성할 고객 정보 - 업태                                                       | no       |
| input.category           | 새로 생성할 고객 정보 - 업종                                                       | no       |
| input.managers           | 새로 생성할 고객 정보 - 고객사 담당자 목록                                               | no       |

### Request Body : input.managers

| Key      | Description                                        | Required |
| -------- | -------------------------------------------------- | -------- |
| name     | 고객사 담당자 이름                                         | yes      |
| email    | 고객사 담당자 이메일                                        | no       |
| position | 고객사 담당자 직책                                         | no       |
| note     | 고객사 담당자 노트                                         | no       |
| contact  | 고객사 담당자 연락처                                        | no       |
| roles    | 고객사 담당자 역할 목록 (세금계산서 기본 담당자, 세금계산서 추가 담당자, 계약 담당자) | no       |

<br>

## Response

```json
{
  "ok": true,
  "message": undefined, // 실패하는 경우 메시지
  "data": {
    "id": 1,
    "title": "김철수",
    "customKey": "A5-k159402",
    "ceo": "김대표",
    "registrationNumber": "789-30-01467",
    "address": "서울특별시 서초구 프릭스로 551",
    "industry": "정보통신업",
    "category": "응용 소프트웨어 개발 및 공급업",
    "managers": [
      {
        "name": "이담당자",
        "email": "prix-customer-manager@email.com",
        "position": "이담당자 직책",
        "note": "이담당자 메모",
        "contact": "이담당자 연락처",
        "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할
      }
    ]
  }
}
```

<br>

## Error Codes

| Status Code | Error Code                        | Description                     |
| ----------- | --------------------------------- | ------------------------------- |
| 400         | INVALID\_CUSTOMER\_TITLE          | title이 생성 규칙을 벗어난 경우            |
| 400         | INVALID\_CUSTOMER\_CUSTOM\_KEY    | customKey가 생성 규칙을 벗어난 경우        |
| 409         | DUPLICATED\_CUSTOMER\_TITLE       | 해당 title을 가진 고객이 이미 존재하는 경우     |
| 409         | DUPLICATED\_CUSTOMER\_CUSTOM\_KEY | 해당 customKey를 가진 고객이 이미 존재하는 경우 |
| 500         | FAILED\_CREATE\_CUSTOMER          | 고객 생성 과정에서 알 수 없는 에러가 발생한 경우    |
| 400         | CUSTOMER\_MANAGER\_NAME\_REQUIRED | 고객사 담당자 이름이 누락된 경우              |
| 400         | CUSTOMER\_INVALID\_MANAGER\_ROLE  | 유효하지 않은 고객사 담당자 역할              |
| 400         | CUSTOMER\_MANAGER\_MAX\_COUNT     | 최대 고객사 담당자 수를 초과한 경우            |

<br>