신규 고객 생성 API

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

POST kit-api/v1/customers

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

Example

.../kit-api/v1/customers

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

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

Response

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

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	최대 고객사 담당자 수를 초과한 경우