PAYZEN API

Method	Endpoint	Description	Auth
POST	`/api/user/login`	로그인 (JWT 토큰 발급)	-
POST	`/api/user/refresh`	토큰 갱신	-
POST	`/api/user/logout`	로그아웃	-
GET	`/api/user/me`	내 정보 조회	Required

Parameter	Type	Required	Description
user_id	string	Yes	로그인 아이디
password	string	Yes	비밀번호

Parameter	Type	Required	Description
Body 파라미터 없음 (Authorization 헤더 사용)

Parameter	Type	Required	Description
Body 파라미터 없음 (Authorization 헤더 사용)

Parameter	Type	Required	Description
파라미터 없음 (Authorization 헤더 사용)

Method	Endpoint	Description	Auth
POST	`/api/user/create`	사용자 계정 생성	-
GET	`/api/user/{user_id}`	사용자 정보 조회	Required

Parameter	Type	Required	Description
user_id	string	Yes	로그인 아이디 (영문+숫자 8~16자)
password	string	Yes	비밀번호 (영문+숫자+특수기호 10~16자)
name	string	Yes	사용자 이름
email	string	No	이메일 주소

Parameter	Type	Required	Description
user_id	string	Yes	조회할 사용자 아이디 (URL 경로)

Product API

상품, 상품군, 납입기간 관리 API - ProductController에서 통합 관리

상품 관리

Method	Endpoint	Description	Auth
POST	`/api/product/create`	상품 생성	Required
GET	`/api/product/{id}`	상품 조회	Required
GET	`/api/product/list`	상품 목록 조회	Required
PUT	`/api/product/{id}`	상품 수정 (ID기준, 상품코드 변경 가능)	Required
GET	`/api/product/{id}/history`	상품 수정 이력 조회	Required
GET	`/api/product/{product_code}/download`	상품 파일 다운로드	Required

상품군 관리

Method	Endpoint	Description	Auth
GET	`/api/product-group/list`	상품군 목록 조회	Required
GET	`/api/product-group/{id}/check-usage`	상품군 사용 여부 체크	Required
POST	`/api/product-group/bulk-save`	상품군 일괄 저장	Required

납입기간 관리

Method	Endpoint	Description	Auth
GET	`/api/product-term/list`	납입기간 목록 조회	Required
GET	`/api/product-term/{id}/check-usage`	납입기간 사용 여부 체크	Required
POST	`/api/product-term/bulk-save`	납입기간 일괄 저장	Required

Create (상품 생성)

POST /api/product/create

새로운 상품을 생성합니다.

Parameter	Type	Required	Description
product_group_id	integer	Yes	상품군 ID
product_code	string	Yes	상품코드 (고유)
product_name	string	Yes	상품명
product_term_ids	array	Yes	납입기간 ID 배열 (최소 1개)
product_file	string	No	파일명 (사전 업로드 필요)
product_file_name	string	No	원본 파일명 (최대 255자)
remarks	string	No	비고
use_yn	string	No	사용여부 (Y/N, 기본값: Y)
aliases	array	No	별칭 배열

API 테스트

product_group_id:

product_code:

product_name:

product_term_ids:

Ctrl+클릭으로 다중 선택

product_file:

PDF, 이미지, 문서 (최대 20MB) - 선택 시 자동 업로드

remarks:

use_yn:

aliases:

상품명의 다른 이름 (선택)

Request

Response

Show (상품 조회)

GET /api/product/{id}

상품 ID로 상품 정보를 조회합니다.

Parameter	Type	Required	Description
id	integer	Yes	상품 ID (URL 경로)

API 테스트

id:

Request

Response

List (상품 목록)

GET /api/product/list

상품 목록을 조회합니다. 필터링 및 검색 가능합니다.

Parameter	Type	Required	Description
product_group_ids	array	No	상품군 ID 배열 (필터)
use_yn	string	No	사용여부 필터 (Y/N)
search_type	string	No	검색유형 (all/product_code/product_name)
search_keyword	string	No	검색어 (상품명/코드)
sort_by	string	No	정렬기준 (created_at/group_name/product_code/product_name/use_yn)
sort_order	string	No	정렬방향 (asc/desc)
per_page	integer	No	페이지당 항목 수 (기본값: 20)
page	integer	No	페이지 번호 (기본값: 1)

API 테스트

검색 조건

상품군:

Ctrl+클릭으로 다중 선택 (미선택시 전체)

사용여부:

검색조건:

정렬 조건

정렬기준:

정렬방향:

per_page:

page:

Request

Response

Update (상품 수정)

PUT /api/product/{id}

기존 상품 정보를 수정합니다. 상품코드를 입력 후 "데이터 불러오기"를 클릭하면 기존 데이터가 로드됩니다. 상품코드도 변경 가능합니다.

Parameter	Type	Required	Description
id	integer	Yes	상품 ID (URL 경로)
product_code	string	No	상품코드 (변경 가능)
product_group_id	integer	No	상품군 ID
product_name	string	No	상품명
product_term_ids	array	No	납입기간 ID 배열
product_file	string	No	파일명
product_file_name	string	No	원본 파일명 (최대 255자)
remarks	string	No	비고
use_yn	string	No	사용여부 (Y/N)
aliases	array	No	별칭 배열

API 테스트

상품 ID:

product_code: * 변경 시 중복 체크됨

product_group_id:

product_name:

product_term_ids:

Ctrl+클릭으로 다중 선택

product_file:

PDF, 이미지, 문서 (최대 20MB) - 선택 시 자동 업로드

remarks:

use_yn:

aliases:

별칭이 없습니다.

ID가 있는 별칭은 수정됨, ID가 없는 별칭은 새로 생성됨, X로 제거한 별칭은 삭제됨

Request

Response

History (상품 수정 이력 조회)

GET /api/product/{id}/history

상품의 수정 이력을 조회합니다. 수정항목, 변경유형, 변경 전/후 값, 변경일시를 확인할 수 있습니다.

Parameter	Type	Required	Description
id	integer	Yes	상품 ID (URL 경로)

API 테스트

상품 ID:

Request

Response

Download (상품 파일 다운로드)

GET /api/product/{product_code}/download

상품코드로 등록된 파일을 다운로드합니다.

Parameter	Type	Required	Description
product_code	string	Yes	상품코드 (URL 경로)

API 테스트

product_code:

Request

Response

List (상품군 목록)

GET /api/product-group/list

상품군 목록을 조회합니다. 사용여부 필터 가능합니다.

Parameter	Type	Required	Description
use_yn	string	No	사용여부 필터 (Y/N, 미입력시 전체)

API 테스트

use_yn:

Request

Response

Check Usage (상품군 사용 여부 체크)

GET /api/product-group/{id}/check-usage

해당 상품군이 상품에서 사용되고 있는지 확인합니다. 삭제 전 확인용으로 사용합니다.

Parameter	Type	Required	Description
id	integer	Yes	상품군 ID (URL path parameter)

API 테스트

상품군 ID:

Request

Response

Bulk Save (상품군 일괄 저장)

POST /api/product-group/bulk-save

여러 상품군을 한 번에 추가하거나 수정합니다. ID가 있으면 수정, 없으면 생성합니다.

Parameter	Type	Required	Description
groups	array	Yes	상품군 배열
groups[].id	integer	No	상품군 ID (수정시 필수)
groups[].group_name	string	Yes	상품군명 (최대 100자)
groups[].sort_order	integer	No	정렬순서
groups[].use_yn	string	No	사용여부 (Y/N, 기본값: Y)
groups[].edit_yn	string	No	수정가능여부 (Y/N, 기본값: Y)

API 테스트

기존 목록을 불러와서 수정하거나, 직접 JSON을 입력할 수 있습니다.
💡 드래그앤드랍으로 정렬순서를 변경할 수 있습니다!

상품군 JSON:

Request

Response

List (납입기간 목록)

GET /api/product-term/list

납입기간 목록을 조회합니다. 사용여부 필터 가능합니다.

Parameter	Type	Required	Description
use_yn	string	No	사용여부 필터 (Y/N, 미입력시 전체)

API 테스트

use_yn:

Request

Response

Check Usage (납입기간 사용 여부 체크)

GET /api/product-term/{id}/check-usage

특정 납입기간이 상품에서 사용되고 있는지 확인합니다.

Parameter	Type	Required	Description
id	integer	Yes	납입기간 ID (URL path parameter)

API 테스트

id:

Request

Response

Bulk Save (납입기간 일괄 저장)

POST /api/product-term/bulk-save

여러 납입기간을 한 번에 추가하거나 수정합니다. ID가 있으면 수정, 없으면 생성합니다.

Parameter	Type	Required	Description
terms	array	Yes	납입기간 배열
terms[].id	integer	No	납입기간 ID (수정시 필수)
terms[].term_name	string	Yes	납입기간명 (최대 100자)
terms[].sort_order	integer	No	정렬순서
terms[].use_yn	string	No	사용여부 (Y/N, 기본값: Y)
terms[].edit_yn	string	No	수정가능여부 (Y/N, 기본값: Y)

API 테스트

기존 목록을 불러와서 수정하거나, 직접 JSON을 입력할 수 있습니다.
💡 드래그앤드랍으로 정렬순서를 변경할 수 있습니다!

납입기간 JSON:

Request

Response

Center API

센터/부서 관리 API - CenterController, TeamController에서 관리

센터 관리

Method	Endpoint	Description	Auth
GET	`/api/center/list`	센터 목록 조회	Required
POST	`/api/center/bulk-save`	센터 일괄 저장	Required

부서 관리

Method	Endpoint	Description	Auth
GET	`/api/team/list`	부서 목록 조회	Required
POST	`/api/team/create`	부서 추가	Required
PUT	`/api/team/{id}`	부서 수정	Required

List (센터 목록)

GET /api/center/list

센터 목록을 조회합니다. 사용여부 필터 가능합니다.

Parameter	Type	Required	Description
use_yn	string	No	사용여부 필터 (Y/N)

API 테스트

use_yn:

Request

Response

Bulk Save (센터 일괄 저장)

POST /api/center/bulk-save

여러 센터를 한 번에 추가하거나 수정합니다. ID가 있으면 수정, 없으면 생성합니다.

Parameter	Type	Required	Description
centers	array	Yes	센터 배열
centers.*.id	integer	No	센터 ID (수정 시)
centers.*.center_name	string	Yes	센터명
centers.*.sort_order	integer	No	정렬순서 (기본값: 0)
centers.*.use_yn	string	No	사용여부 (Y/N, 기본값: Y)

API 테스트

JSON:

불러오기 필터:

Request

Response

List (부서 목록)

GET /api/team/list

부서 목록을 조회합니다. 센터별 필터 가능합니다.

Parameter	Type	Required	Description
center_id	integer	No	센터 ID 필터
use_yn	string	No	사용여부 필터 (Y/N)

API 테스트

센터:

use_yn:

Request

Response

Create (부서 추가)

POST /api/team/create

새로운 부서를 추가합니다.

Parameter	Type	Required	Description
center_id	integer	Yes	센터 ID
team_name	string	Yes	부서명
team_memo	string	No	부서메모

API 테스트

센터:

부서명:

부서메모:

Request

Response

Update (부서 수정)

PUT /api/team/{id}

부서 정보를 수정합니다. 센터 ID와 부서 ID로 조회 후 수정합니다.

Parameter	Type	Required	Description
center_id	integer	No	센터 ID (조회 필터)
team_name	string	Yes	부서명
team_memo	string	No	부서메모
use_yn	string	Yes	사용여부 (Y/N)

API 테스트

센터:

부서:

부서명:

부서메모:

사용여부:

Request

Response

Agent API

직원/직급 관리 API - AgentController, JobGroupController, JobPositionController에서 관리

Method	Endpoint	Description	Auth
GET	`/api/job-group/list`	직급구분 목록 조회	Required
GET	`/api/job-position/list`	직급 목록 조회	Required
POST	`/api/job-group/bulk-save`	직급구분 + 직급 통합 일괄 저장	Required
POST	`/api/agent/create`	직원 추가	Required
GET	`/api/agent/list`	직원 목록 조회	Required
GET	`/api/agent/show/{id}`	직원 상세 조회	Required
POST	`/api/agent/unmask/{id}`	민감정보 마스킹 해제	Required
PUT	`/api/agent/update/{id}`	직원 수정	Required
GET	`/api/agent/{id}/history`	수정 이력 조회	Required
POST	`/api/agent/{id}/history/{logId}/unmask`	수정 이력 마스킹 해제	Required
GET	`/api/agent/file/download/{fileId}`	파일 다운로드	Required

List (직급구분 목록)

GET /api/job-group/list

직급구분 목록을 조회합니다.

API 테스트

Request

Response

List (직급 목록)

GET /api/job-position/list

직급 목록을 조회합니다. 직급구분별 필터 가능합니다.

Parameter	Type	Required	Description
job_group_id	integer	No	직급구분 ID 필터

API 테스트

직급구분:

Request

Response

Bulk Save (직급구분 + 직급 통합 일괄 저장)

POST /api/job-group/bulk-save

여러 직급구분과 하위 직급을 한 번에 추가하거나 수정합니다. ID가 있으면 수정, 없으면 생성합니다.

Parameter	Type	Required	Description
groups	array	Yes	직급구분 배열
groups.*.id	integer	No	직급구분 ID (수정 시)
groups.*.group_name	string	Yes	구분명
groups.*.edit_yn	string	No	수정가능여부 (Y/N, 기본값: Y)
groups.*.positions	array	No	하위 직급 배열
groups..positions..id	integer	No	직급 ID (수정 시)
groups..positions..position_name	string	Yes	직급명
groups..positions..sort_order	integer	No	정렬순서
groups..positions..edit_yn	string	No	수정가능여부 (Y/N, 기본값: Y)

API 테스트

JSON:

Request

Response

Create (직원 추가)

POST /api/agent/create

새로운 직원을 등록합니다. 소속 정보(부서, LP코드)를 함께 등록할 수 있습니다.

Parameter	Type	Required	Description
name	string	Yes	이름 (최대 50자)
job_group_id	integer	No	직급구분 ID
job_position_id	integer	No	직급 ID
commission_date	date	No	위촉일 (YYYY-MM-DD)
counseling_start_date	date	No	상담 시작일 (YYYY-MM-DD)
employment_status	string	No	재직상태 (Y: 재직, L: 휴직, N: 퇴직 / 기본값: Y)
resignation_date	date	No	퇴직일 (YYYY-MM-DD, 재직상태가 N인 경우에만 등록 가능)
resident_number	string	No	주민등록번호
phone	string	No	연락처
address	string	No	주소
account_holder	string	No	예금주
bank_code	string	No	은행코드
bank_name	string	No	은행명
account_number	string	No	계좌번호
contract_files	array	No	첨부파일 배열
contract_files[].file_path	string	Yes	파일 경로
contract_files[].file_name	string	Yes	파일명
contract_files[].file_size	integer	No	파일 크기
contract_files[].mime_type	string	No	MIME 타입
referrer_id	integer	No	소개자 ID
memo	string	No	메모
career_yn	string	No	경력여부 (Y/N)
prev_salary	integer	No	전직장급여 (원, 정수)
teams	array	No	소속 정보 배열
teams[].team_id	integer	Yes	부서 ID
teams[].lp_code	string	Yes	LP코드 (전체 고유)
teams[].settlement_yn	string	No	정산기준 여부 (Y/N, 기본값: N, 활성 소속 중 1개만 Y 가능)
teams[].use_yn	string	No	사용여부 (Y/N, 기본값: Y)

API 테스트

기본 정보

이름*:

직급구분:

직급:

위촉일:

상담시작일:

재직상태:

주민등록번호:

연락처:

주소:

계좌/기타 정보

예금주:

은행코드:

은행명:

계좌번호:

소개자ID:

메모:

경력여부:

전직장급여:

첨부파일

소속 정보

Request

Response

List (직원 목록 조회)

GET /api/agent/list

직원 목록을 조회합니다. 부서, 날짜범위, 직급구분, 재직상태로 필터링하고 이름/연락처로 검색할 수 있습니다.

Parameter	Type	Required	Description
team_ids[]	array	No	부서 ID (다중 선택)
commission_date_from	date	No	위촉일 시작 (YYYY-MM-DD)
commission_date_to	date	No	위촉일 종료 (YYYY-MM-DD)
counseling_start_date_from	date	No	상담시작일 시작 (YYYY-MM-DD)
counseling_start_date_to	date	No	상담시작일 종료 (YYYY-MM-DD)
job_group_id	integer	No	직급구분 ID
employment_status	string	No	재직상태 (Y: 재직, L: 휴직, N: 퇴직)
search_type	string	No	검색유형 (name/phone/lp_code/all)
search_keyword	string	No	검색어 (연락처는 뒷4자리)
sort_by	string	No	정렬기준 (job_group/name/commission_date/counseling_start_date/employment_status)
sort_order	string	No	정렬순서 (asc/desc)
page	integer	No	페이지 번호
per_page	integer	No	페이지당 수 (기본: 20, 최대: 100)

API 테스트

검색 조건

부서:

직급구분:

재직상태:

위촉일:

상담시작일:

검색어 / 정렬

검색유형:

검색어:

정렬기준:

정렬순서:

페이지:

페이지당:

Request

Response

Show (직원 상세 조회)

GET /api/agent/show/{id}

직원의 상세 정보를 조회합니다. 민감정보는 마스킹 처리되어 반환됩니다.

Parameter	Type	Required	Description
id	integer	Yes	직원 ID (URL 경로)

마스킹 처리:

연락처: 010-••••-5678
주민등록번호: ••0212-•••••••
주소: 숫자만 • 처리
계좌번호: 뒷자리 6자리 ••••••

API 테스트

직원 ID:

Request

Response

Unmask (민감정보 마스킹 해제)

POST /api/agent/unmask/{id}

직원의 민감정보 마스킹을 해제하여 원본 데이터를 조회합니다.

Parameter	Type	Required	Description
id	integer	Yes	직원 ID (URL 경로)
field	string	Yes	마스킹 해제할 필드 (phone/resident_number/address/account_number)

API 테스트

직원 ID:

필드:

Request

Response

Update (직원 수정)

PUT /api/agent/update/{id}

직원 정보를 수정합니다. 직원 ID를 입력 후 "데이터 불러오기"를 클릭하면 기존 데이터가 로드됩니다.

Parameter	Type	Required	Description
id	integer	Yes	직원 ID (URL 경로)
name	string	Yes	이름 (최대 50자)
job_group_id	integer	No	직급구분 ID
job_position_id	integer	No	직급 ID
commission_date	date	No	위촉일 (YYYY-MM-DD)
counseling_start_date	date	No	상담 시작일 (YYYY-MM-DD)
employment_status	string	No	재직상태 (Y: 재직, L: 휴직, N: 퇴직)
resignation_date	date	No	퇴직일 (YYYY-MM-DD, 재직상태 N일 때만 저장, N→Y 변경 시 자동 삭제)
resident_number	string	No	주민등록번호
phone	string	No	연락처
address	string	No	주소
account_holder	string	No	예금주
bank_code	string	No	은행코드
bank_name	string	No	은행명
account_number	string	No	계좌번호
contract_files	array	No	첨부파일 배열
contract_files[].file_path	string	Yes	파일 경로
contract_files[].file_name	string	Yes	파일명
contract_files[].file_size	integer	No	파일 크기
contract_files[].mime_type	string	No	MIME 타입
referrer_id	integer	No	소개자 ID
memo	string	No	메모
career_yn	string	No	경력여부 (Y/N)
prev_salary	integer	No	전직장급여 (원, 정수)
teams	array	No	소속 정보 배열 (use_yn 값으로 활성/비활성 직접 지정)
teams[].team_id	integer	Yes	부서 ID
teams[].lp_code	string	Yes	LP코드 (전체 고유)
teams[].settlement_yn	string	No	정산기준 여부 (Y/N, 기본값: N, 활성 소속 중 1개만 Y 가능)
teams[].use_yn	string	No	사용여부 (Y/N, 기본값: Y)

API 테스트

직원 ID:

기본 정보

이름*:

직급구분:

직급:

위촉일:

상담시작일:

재직상태:

주민등록번호:

연락처:

주소:

계좌/기타 정보

예금주:

은행코드:

은행명:

계좌번호:

소개자ID:

메모:

경력여부:

전직장급여:

첨부파일

소속 정보

Request

Response

History (직원 수정 이력 조회)

GET /api/agent/{id}/history

직원의 수정 이력을 조회합니다. 수정항목, 변경유형, 변경 전/후 값, 변경일시를 확인할 수 있습니다.

Parameter	Type	Required	Description
id	integer	Yes	직원 ID (URL 경로)

API 테스트

직원 ID:

Request

Response

History Unmask (수정 이력 마스킹 해제)

POST /api/agent/{id}/history/{logId}/unmask

수정 이력에서 마스킹된 민감정보를 해제합니다. 현재 저장된 값과 동일한 경우에만 해제 가능합니다.

Parameter	Type	Required	Description
id	integer	Yes	직원 ID (URL 경로)
logId	integer	Yes	이력 로그 ID (URL 경로)

API 테스트

직원 ID:

로그 ID:

Request

Response

File Download (파일 다운로드)

GET /api/agent/file/download/{fileId}

직원 첨부파일을 다운로드합니다. 파일 ID는 직원 상세 조회(show) 또는 수정용 조회(edit) API 응답의 contract_files 배열에서 확인할 수 있습니다.

Parameter	Type	Required	Description
fileId	integer	Yes	파일 ID (URL 경로)

API 테스트

파일 ID:

Request

Response

Allowance API

수당 관리 API - AllowanceController에서 관리

Method	Endpoint	Description	Auth
GET	`/api/allowance/conversion-rate`	부서별 환산율 조회	Required
POST	`/api/allowance/conversion-rate`	환산율 일괄 저장	Required
GET	`/api/allowance/product-terms`	상품-납입기간 조회	Required
GET	`/api/allowance/performance`	성과수당 구간 조회	Required
POST	`/api/allowance/performance`	성과수당 구간 일괄 저장	Required
GET	`/api/allowance/policy`	시책수당 조회	Required
POST	`/api/allowance/policy`	시책수당 일괄 저장	Required
GET	`/api/allowance/maintenance`	유지수당 조회	Required
POST	`/api/allowance/maintenance`	유지수당 일괄 저장	Required
GET	`/api/allowance/clawback`	환수수당 조회	Required
POST	`/api/allowance/clawback`	환수수당 일괄 저장	Required
GET	`/api/allowance/mgm`	MGM수당 조회	Required
POST	`/api/allowance/mgm`	MGM수당 일괄 저장	Required
GET	`/api/allowance/education`	교육비수당 조회	Required
POST	`/api/allowance/education`	교육비수당 일괄 저장	Required
GET	`/api/allowance/long-service`	장기근속수당 조회	Required
POST	`/api/allowance/long-service`	장기근속수당 일괄 저장	Required
GET	`/api/allowance/acquaintance`	연고지인수당 조회	Required
POST	`/api/allowance/acquaintance`	연고지인수당 일괄 저장	Required
GET	`/api/allowance/leader-performance`	팀장성과수당 조회	Required
POST	`/api/allowance/leader-performance`	팀장성과수당 일괄 저장	Required
GET	`/api/allowance/leader-activity`	팀장가동수당 조회	Required
POST	`/api/allowance/leader-activity`	팀장가동수당 일괄 저장	Required
GET	`/api/allowance/{type}/history`	수당 히스토리 조회	Required

Get Conversion Rate (부서별 환산율 조회)

GET /api/allowance/conversion-rate

부서의 상품별 환산율을 조회합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
product_group_id	integer	No	상품군 ID (미입력시 전체 조회)

API 테스트

부서:

상품군:

Request

Response

Save Conversion Rate (환산율 일괄 저장)

POST /api/allowance/conversion-rate

환산율을 일괄 저장합니다. 신규 등록, 수정, 삭제를 한번에 처리합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	환산율 ID (수정 시)
items.*.product_id	integer	Yes*	상품 ID
items.*.product_term_id	integer	Yes*	납입기간 ID
items.*.non_replacement_rate	numeric	Yes*	비대체환산율
items.*.replacement_rate	numeric	Yes*	대체환산율
delete_ids	array	No	삭제할 환산율 ID 배열

API 테스트

부서:

저장 항목 (items):

Request

Response

Get Product Terms (상품-납입기간 조회)

GET /api/allowance/product-terms

환산율 등록을 위한 상품-납입기간 목록을 조회합니다.

Parameter	Type	Required	Description
product_group_id	integer	No	상품군 ID
product_term_id	integer	No	납입기간 ID
search_type	string	No	검색유형 (all, product_code, product_name)
search_keyword	string	No	검색어

API 테스트

상품군:

납입기간:

검색유형:

검색어:

Request

Response

Get Performance Allowance (성과수당 구간 조회)

GET /api/allowance/performance

부서의 성과수당 실적금액 구간별 지급율을 조회합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Performance Allowance (성과수당 구간 일괄 저장)

POST /api/allowance/performance

성과수당 구간을 일괄 저장합니다. 신규 등록, 수정, 삭제를 한번에 처리합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 구간 배열
items.*.id	integer	No	구간 ID (수정 시)
items.*.min_amount	integer	Yes*	구간 시작 금액
items.*.max_amount	integer	No	구간 끝 금액 (미입력=무제한)
items.*.rate	integer	Yes*	지급율 (%)
delete_ids	array	No	삭제할 구간 ID 배열

API 테스트

부서:

구간 목록 (items):

Request

Response

Get Policy Allowance (시책수당 조회)

GET /api/allowance/policy

부서의 시책수당 위촉차월/실적금액 구간별 지급율을 조회합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Policy Allowance (시책수당 일괄 저장)

POST /api/allowance/policy

시책수당을 일괄 저장합니다. 위촉차월구간 + 실적금액구간별 1차/2차 지급율을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.min_month	integer	Yes*	위촉차월 시작
items.*.max_month	integer	No	위촉차월 끝 (미입력=무제한)
items.*.min_amount	integer	Yes*	실적금액 시작
items.*.max_amount	integer	No	실적금액 끝 (미입력=무제한)
items.*.rate_1	integer	Yes*	1차 지급율 (%)
items.*.rate_2	integer	Yes*	2차 지급율 (%)
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Maintenance Allowance (유지수당 조회)

GET /api/allowance/maintenance

부서별 유지수당 구간을 조회합니다. 유지회차별 유지율구간 + 지급율을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Maintenance Allowance (유지수당 일괄 저장)

POST /api/allowance/maintenance

유지수당을 일괄 저장합니다. 유지회차별 유지율구간 + 지급율을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.maintenance_round	integer	Yes*	유지회차
items.*.min_rate	integer	Yes*	유지율 시작 (%)
items.*.max_rate	integer	No	유지율 끝 (%, 미입력=무제한)
items.*.pay_rate	integer	Yes*	지급율 (%)
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Clawback Allowance (환수수당 조회)

GET /api/allowance/clawback

부서별 환수수당 구간을 조회합니다. 미유지차월 구간별 환수율을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Clawback Allowance (환수수당 일괄 저장)

POST /api/allowance/clawback

환수수당을 일괄 저장합니다. 미유지차월 구간별 환수율을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.min_month	integer	Yes*	미유지차월 시작
items.*.max_month	integer	No	미유지차월 끝 (미입력=무제한)
items.*.clawback_rate	integer	Yes*	환수율 (%)
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get MGM Allowance (MGM수당 조회)

GET /api/allowance/mgm

부서별 MGM수당을 조회합니다. 위촉차월별 최소금액, 지급금액을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save MGM Allowance (MGM수당 일괄 저장)

POST /api/allowance/mgm

MGM수당을 일괄 저장합니다. 위촉차월별 최소금액, 지급금액을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.commission_month	integer	Yes*	위촉차월
items.*.min_amount	integer	Yes*	최소금액
items.*.pay_amount	integer	Yes*	지급금액
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Education Allowance (교육비수당 조회)

GET /api/allowance/education

부서별 교육비수당을 조회합니다. 위촉차월별 지급기준일, 교육비환수 개월수, 지급금액을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Education Allowance (교육비수당 일괄 저장)

POST /api/allowance/education

교육비수당을 일괄 저장합니다. 위촉차월별 지급기준일, 교육비환수 개월수, 지급금액을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.commission_month	integer	Yes*	위촉차월
items.*.payment_base_date	integer	Yes*	지급기준일
items.*.refund_months	integer	Yes*	교육비환수 개월수
items.*.pay_amount	integer	Yes*	지급금액
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Long Service Allowance (장기근속수당 조회)

GET /api/allowance/long-service

부서별 장기근속수당을 조회합니다. 차월구간별 최소금액, 목표 대체율, 지급금액을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Long Service Allowance (장기근속수당 일괄 저장)

POST /api/allowance/long-service

장기근속수당을 일괄 저장합니다. 차월구간별 최소금액, 목표 대체율, 지급금액을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.min_month	integer	Yes*	차월구간 시작
items.*.max_month	integer	No	차월구간 끝 (미입력=무제한)
items.*.min_amount	integer	Yes*	최소금액
items.*.target_replacement_rate	integer	Yes*	목표 대체율(%)
items.*.pay_amount	integer	Yes*	지급금액
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Acquaintance Allowance (연고지인수당 조회)

GET /api/allowance/acquaintance

부서별 연고지인수당을 조회합니다. 유지회차별 직급별 지급율을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Acquaintance Allowance (연고지인수당 일괄 저장)

POST /api/allowance/acquaintance

연고지인수당을 일괄 저장합니다. 유지회차별 직급별 지급율을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.maintenance_round	integer	Yes*	유지회차
items.*.center_head_rate	integer	Yes*	센터장지급율(%)
items.*.manager_rate	integer	Yes*	실장지급율(%)
items.*.admin_rate	integer	Yes*	총무지급율(%)
items.*.planner_rate	integer	Yes*	설계사지급율(%)
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Leader Performance Allowance (팀장성과수당 조회)

GET /api/allowance/leader-performance

부서별 팀장성과수당을 조회합니다. 실적구간별 지급금액을 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Leader Performance Allowance (팀장성과수당 일괄 저장)

POST /api/allowance/leader-performance

팀장성과수당을 일괄 저장합니다. 실적구간별 지급금액을 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.min_amount	integer	Yes*	실적구간 시작금액
items.*.max_amount	integer	No	실적구간 끝금액 (미입력=무제한)
items.*.pay_amount	integer	Yes*	지급금액
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Get Leader Activity Allowance (팀장가동수당 조회)

GET /api/allowance/leader-activity

부서별 팀장가동수당을 조회합니다. 인원수당 금액과 팀장포함여부를 반환합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID

API 테스트

부서:

Request

Response

Save Leader Activity Allowance (팀장가동수당 일괄 저장)

POST /api/allowance/leader-activity

팀장가동수당을 일괄 저장합니다. 인원수당 금액과 팀장포함여부를 설정합니다.

Parameter	Type	Required	Description
team_id	integer	Yes	부서 ID
items	array	No	저장할 항목 배열
items.*.id	integer	No	항목 ID (수정 시)
items.*.pay_amount	integer	Yes*	인원수당 금액
items.*.include_leader	string	Yes*	팀장포함여부 (Y/N)
delete_ids	array	No	삭제할 항목 ID 배열

API 테스트

부서:

항목 목록 (items):

Request

Response

Allowance History (수당 히스토리 조회)

GET /api/allowance/{type}/history

수당 타입별 과거 히스토리를 조회합니다. 현재 적용중인 데이터(valid_to=null)는 제외하고, 과거 기간별로 그룹핑하여 반환합니다.

Parameter	Type	Required	Description
type	string	Yes	수당 타입 (URL path) - conversion-rate, performance, policy, maintenance, clawback, mgm, education, long-service, acquaintance, leader-performance, leader-activity
team_id	integer	Yes	부서 ID

API 테스트

수당 타입:

부서:

Request

Response

Contract API

계약 관리 API - 엑셀 임포트 설정

Method	Endpoint	Description	Auth
POST	`/api/contract/import-setting`	임포트 설정 저장	Required
GET	`/api/contract/import-setting/latest`	최신 설정 조회	Required
GET	`/api/contract/import-setting/list`	설정 이력 목록	Required
GET	`/api/contract/import-setting/{id}`	설정 상세 조회	Required
GET	`/api/contract/list`	계약관리 조회	Required
PUT	`/api/contract/{id}`	계약 수정	Required
POST	`/api/contract/import`	엑셀 파일 임포트	Required
GET	`/api/contract/registration-status`	등록 현황 (월별)	Required
GET	`/api/contract/registration-detail`	등록 상세 내역	Required

임포트 설정 저장

POST /api/contract/import-setting

엑셀 파일의 헤더 행, 데이터 시작 행, 컬럼 매핑 정보를 저장합니다. 저장할 때마다 새 이력이 누적됩니다.

Parameter	Type	Required	Description
excel_type	string	Yes	엑셀 타입 (contract, replacement, maintenance)
sheet_index	integer	No	시트 번호 (1부터 시작, 기본 1)
header_row	integer	Yes	메뉴(헤더)가 있는 행 번호
data_start_row	integer	Yes	실제 데이터 시작 행 번호
column_mapping	object	Yes	엑셀 컬럼명 → DB 컬럼 매핑

매핑 가능한 DB 컬럼

DB 컬럼	설명
policy_number	증권번호
contractor_name	계약자명
status	계약상태
product_name	보험명
product_code	보험코드
monthly_premium	월납금액
payment_period	납입기간
payment_count	납입회차
insurance_start_date	보험가입일
agent_name	설계사이름
agent_lp_code	설계사코드
lapse_type	이탈구분
churning_type	선후승환
last_payment_month	최종납월
converted_count	환산회차

API 테스트

excel_type:

sheet_index:

header_row:

data_start_row:

컬럼 매핑 설정

엑셀 컬럼명을 입력하고, 매핑할 DB 컬럼을 선택하세요.

→

Request

Response

임포트 설정 이력 목록

GET /api/contract/import-setting/list

저장된 임포트 설정 이력을 페이지네이션으로 조회합니다.

Parameter	Type	Required	Description
excel_type	string (query)	No	엑셀 타입 필터 (contract, replacement, maintenance)
page	integer	No	페이지 번호 (기본: 1)
per_page	integer	No	페이지당 건수 (기본: 20, 최대: 100)

API 테스트

excel_type:

page:

per_page:

Request

Response

임포트 설정 상세 조회

GET /api/contract/import-setting/{id}

특정 임포트 설정의 상세 정보를 조회합니다.

Parameter	Type	Required	Description
id	integer (path)	Yes	설정 ID

API 테스트

설정 ID:

Request

Response

엑셀 파일 임포트

POST /api/contract/import

엑셀 파일을 업로드하면 해당 엑셀 타입의 임포트 설정을 기반으로 계약 데이터를 일괄 등록합니다.

Parameter	Type	Required	Description
excel_type	string	Yes	엑셀 타입 (contract, replacement, maintenance)
file	file	Yes	엑셀 파일 (.xlsx, .xls / 최대 20MB)
year_month	string	No	계약 년월 (YYYY-MM) - 급여 계산 기준월

API 테스트

엑셀 타입:

계약 년월:

엑셀 파일:

Request

Response

계약관리 조회

GET /api/contract/list

계약 데이터를 검색 조건에 따라 조회합니다.

Parameter	Type	Required	Description
team_ids[]	array	No	소속 필터 (팀 ID 다중 선택)
date_from	string	No	보험가입일 시작 (YYYY-MM-DD)
date_to	string	No	보험가입일 종료 (YYYY-MM-DD)
product_group_ids[]	array	No	상품군 ID (다중 선택)
status	string	No	상태 (NEW, CANCEL, REVIVE, WITHDRAW, QUALITY)
replacement_yn	string	No	대체여부 (all, Y, N)
acquaintance_yn	string	No	연고지인여부 (all, Y, N)
search_type	string	No	검색유형 (all, agent_name, agent_lp_code, contractor_name, policy_number, product_name)
search_keyword	string	No	검색어
per_page	integer	No	페이지당 건수 (기본 20, 최대 100)
page	integer	No	페이지 번호

API 테스트

소속:

보험가입일: ~

상품군:

상태:

대체여부:

연고지인:

검색유형:

페이지당: 페이지:

Request

Response

계약 수정

PUT /api/contract/{id}

계약의 대체여부, 연고지인여부, 관계, 메모를 수정합니다. 변경 시 히스토리가 자동 저장됩니다.

API 테스트

계약 ID:

대체여부:

연고지인:

관계:

메모:

Request

Response

계약 자료 등록 현황

GET /api/contract/registration-status

월별 일자별 계약 자료 등록 현황을 조회합니다.

Parameter	Type	Required	Description
month	string	Yes	조회 월 (YYYY-MM 형식, 예: 2026-02)

API 테스트

조회 월:

Request

Response

계약 자료 등록 상세 내역

GET /api/contract/registration-detail

특정 일자의 등록 상세 내역을 타입별로 조회합니다.

Parameter	Type	Required	Description
date	string	Yes	조회 일자 (YYYY-MM-DD)
type	string	Yes	조회 타입 (contract / replacement / maintenance)

API 테스트

조회 일자:

타입:

Request

Response

증권번호		계약자명
설계사		상품명
상태		보험가입일

PAYZEN API

Login

보안 기능

API 테스트

Refresh (토큰 갱신)

API 테스트

Logout (로그아웃)

API 테스트

Me (내 정보)

API 테스트

Create (계정 생성)

계정 생성 규칙

API 테스트

Show (사용자 조회)

API 테스트

상품 관리

상품군 관리

납입기간 관리

Create (상품 생성)

API 테스트

Show (상품 조회)

API 테스트

List (상품 목록)

API 테스트

검색 조건

정렬 조건

Update (상품 수정)

API 테스트

History (상품 수정 이력 조회)

API 테스트

Download (상품 파일 다운로드)

API 테스트

List (상품군 목록)

API 테스트

Check Usage (상품군 사용 여부 체크)

API 테스트

Bulk Save (상품군 일괄 저장)

API 테스트

상품군 목록 편집

List (납입기간 목록)

API 테스트

Check Usage (납입기간 사용 여부 체크)

API 테스트

Bulk Save (납입기간 일괄 저장)

API 테스트

납입기간 목록 편집

센터 관리

부서 관리

List (센터 목록)

API 테스트

Bulk Save (센터 일괄 저장)

API 테스트

센터 목록 편집

List (부서 목록)

API 테스트

Create (부서 추가)

API 테스트

Update (부서 수정)

API 테스트

List (직급구분 목록)

API 테스트

List (직급 목록)

API 테스트

Bulk Save (직급구분 + 직급 통합 일괄 저장)

API 테스트

직급구분 목록 편집

Create (직원 추가)

API 테스트

기본 정보

계좌/기타 정보

첨부파일

소속 정보

List (직원 목록 조회)

API 테스트

검색 조건

검색어 / 정렬

Show (직원 상세 조회)

API 테스트

Unmask (민감정보 마스킹 해제)

API 테스트