임직원

Knox Suite을 통한 임직원 및 조직 정보 조회 기능을 제공합니다.

[정책 및 제약사항]

1. 재직, 휴직 상태 임직원만 조회 가능합니다.
2. 연계 신청시 요청한 조회대상 회사의 임직원, 조직정보만 조회 가능합니다.
3. 연계 신청 시 파견 포함을 선택한 경우에만 파견된 임직원 정보까지 조회 가능합니다.
4. 회사코드를 이용한 조회 시, 해당 회사 정보만 조회 가능합니다.
5. 조직도 조회의 경우, 조회 대상 회사에 신청 회사 외 타사가 등록되어 있으면 일부 속성만 조회 가능합니다.
6. 부분이름 검색 시 검색어는 한국어 기준 2자, 영어 기준 4자 이상이어야 합니다.
7. 부분이름 검색 시 검색 기능 최적화를 위해 ¹⁾특정 영문명으로는 조회할 수 없습니다.
8. 모든 검색어에는 *, % 를 포함할 수 없습니다. 임직원 이름 검색 시 _ 도 포함할 수 없습니다.
9. 목록으로 검색 시 목록의 값은 중복될 수 없습니다.
10. 목록으로 검색 시 목록의 크기는 100을 넘을 수 없으며, 검색어의 길이는 100자를 넘을 수 없습니다.
11. 임직원 검색 결과는 2,000개, 조직 검색 결과는 5,000개로 제한합니다.
12. 분당 호출 횟수 1,000건 이하로 분산해야 합니다.
13. 대량 호출 시 야간(22시 이후) 수행을 권장합니다. (주간 수행 시 Knox Portal과 협의 필요)

¹⁾ kim, lee, park, choi, jung, kang, cho, yoon, jang, lim, han, shin, oh, seo, kwon, hwang, song, ahn, ryu, hong nguy, youn, young, hyun, sung, sang, jeon, dong, nguye, nguyen, jong, seun, seung, jeong, chan, yong, stre, stres, stress, nguyễn, nguyễn, chang, kyun, kyung, seon, jang, shin, yoon, yang, song, byun, seong, kwan, hwan, byung, chun, kwang, jaeh, hyung, hwang, wang, sangh, moon, kyou, mari, kuma, kwon, yeon, andr, thi, chen, zhan, zhang

[API 목록] 테스트 페이지로 이동(Swagger)_{*Chrome Browser만 이용 가능합니다.}

API	URI	Method	Description

임직원 조회	/employee/api/v2.0/employees	POST	임직원 정보를 조회한다.
조직도 조회	/employee/api/v2.0/organizations	GET	부서 정보를 조회한다.
직급정보 조회	/employee/api/v2.0/titles	GET	직급 정보를 조회한다.

임직원 조회

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 아이디	System-ID	Y	Header	String	C60REST0001
2	회사코드	companyCode	N	Query	String	C60	3~10번 속성 중 1개의 속성만 사용 가능
3	임직원 이름	fullName	Y	Query	String	김삼성	검색엔진 (검색 키워드 완전 일치 검색)
4	부서코드	departmentCode		Query	String	C60AH959
5	사번	employeeNumber		Query	String	123123
6	이름	name		Query	String	삼성	검색엔진 (검색 키워드 부분일치 검색)
7	epId	epIds		Query	String	D100118130308C600299
8	ID	userIds		Query	String	knoxportal
9	메일주소	emailAddresses		Query	String	knoxportal@samsung.com
10	직급코드	titleCode		Query	String	B3K	compCode, page 함께 받아야 함
11	페이지 번호	page	N	Query	String	1	- companyCode&departmentCode / companyCode&title / name 인 경우에만 paging 적용가능 - page 입력 시 500건씩 조회 - page 미입력 시 최대 2000건 조회
12	검색결과 타입	resultType	Y	Body	String	basic optional	- basic : 기본 속성 리턴 - optional : attributes 정의 속성만 리턴
13	조회할 임직원 속성	attributes	N	Body	String	["emailAddress","userId"]	지정한 속성에 대해서만 결과 값 리턴 resultType이 optional인 경우 필수

Response Parameter

resultType 쿼리 타입에 따라 리턴 항목이 다름.
- basic : 기본 속성만 리턴 (아래 * 표시된 30개 항목)
- optional : body에 보낸 attributes 데이터만 리턴

No.	Properties	Attribute	Data Type	Sample Data	Note

1	API 호출 성공 여부	result	String	success fail
2	현재 페이지	currentPage	int	1
3	총 결과 페이지 수	totalPage	int	3
4	검색된 임직원의 수	totalCount	int	30
5	임직원 정보	employees	JSON String
6	계정신청상태	accountStatus	String	A	A: 아이디 승인 W: 아이디 신청 M: 아이디 미발급
7	사업장코드	busiCode	String	C60B0001
8	사업장명	busiName	String	잠실동관
9	회사코드 *	companyCode	String	C60
10	회사명 *	companyName	String	삼성SDS
11	국가	country	String	KR
12	기본소속구분코드	defaultCompanyCode	String	O	O: 원소속 S: 파견소속
13	부서코드 *	departmentCode	String	C60AH959
14	부서명 *	departmentName	String	Knox개발그룹(솔루션개발)
15	담당업무 *	description	String	Knox Suite 개발
16	이메일 주소 *	emailAddress	String	knoxportal@samsung.com
17	사번 *	employeeNumber	String	123123
18	임직원 상태 *	employeeStatus	String	B	B: 재직 V: 휴직
19	임직원 구분	employeeType	String	N	N:정규직 (@samsung.com) U:협력직 C:자회사 T:임시직 (@partner.samsung.com) X:협력직 Y:자회사 Z:임시직 (@samsung.com)
20	영문 사업장명	enBusiName	String	SDS East Campus
21	영문 회사명 *	enCompanyName	String	SAMSUNG SDS
22	영문 부서명 *	enDepartmentName	String	Knox Development Group
23	영문 담당업무 *	enDiscription	String	Knox Portal User Mgmt.
24	영문 성명 *	enFullName	String	Samsung Kim
25	영문 이름 *	enGivenName	String	Samsung
26	영문 직위명 *	enGradeName	String	Manager
27	영문 회사주소	enOfficeAddress	String	123, Olympic-ro 35-gil, Songpa	우편번호로 구분되는 회사주소
28	영문 지역명	enRegionName	String	Jamsil
29	영문 파견 사업장명	enSendBusiName	String	Jamsil
30	영문 파견 회사명	enSendCompanyName	String	Samsung Electronics
31	영문 파견 부서명	enSendDepartmentName	String	IT Service
32	영문 파견 직위명	enSendGradeName	String	Lab Leader
33	영문 파견 지역명	enSendRegionName	String	Suwon
34	영문 파견 총괄명	enSendSubOrgName	String
35	영문 파견 직급명	enSendTitleName	String	E5
36	영문 성 *	enSirName	String	Kim
37	영문 총괄명	enSubOrgName	String
38	영문 직급명 *	enTitleName	String	Senior Engineer
39	epId *	epId	String	D100118130308C600299
40	임원여부	executiveYn	String	N	Y: 임원 N: 직원
41	외부 메일주소	externalEmailAddress	String	knoxportal@gmail.com
42	성명 *	fullName	String	김삼성
43	이름 *	givenName	String	삼성
44	직위명 *	gradeName	String	책임
45	직위직급 표시코드 *	gradeTitleIndiCode	String	B	G: 직위 T: 직급 B: 직위/직급 모두
46	내부 부서코드	inDepartmentCode	String	RE_KO41
47	내부 부서명	inDepartmentName	String	Samsung Research
48	직무명 *	jobName	String	AEB
49	직무코드	jobCode	String	SystemS/W
50	현채인 여부	localStaffYn	String	N	Y: 현채인 N: 현채인 아님
51	핸드폰	mobile	String	+82-10-1111-2222
52	닉네임	nickName	String	nick
53	근무지 주소	officeAddress	String	송파구 올림픽로35길 123
54	근무지 상세 주소	officeDetailAddress	String	동관 19층	상세 회사주소
55	근무지 팩스번호	officeFaxNumber	String	+82-2-2255-1999
56	근무지 우편번호	officeZipCode	String	138-240
57	근무지 전화번호	officeTelNumber	String	82-70-9999-9999
58	선호언어	preferredLanguage	String	ko
59	실명 여부 *	realNameYn	String	R	R:실명 V:가명
60	지역코드	regionCode	String
61	지역명	regionName	String
62	보안등급 *	securityLevel	String	5	1:회장단(회장,부회장,비서실장) 2:사장단(사장,부사장,전무) 3:임원진(상무,이사,고문,감사) 4:간부(부,차,과장) 5:사원(대리,사원) 9:협력사 임직원
63	파견 사업장코드	sendBusiCde	String
64	파견 회사코드	sendCompanyCode	String	C10
65	파견 회사명	sendCompanyName	String	삼성전자
66	파견 부서코드	sendDepartmentCode	String	C10CB04CB040060
67	파견 부서명	sendDepartmentName	String	IT Services
68	파견 직위명	sendGradeName	String
69	파견 직위직급 표시코드	sendGradeTitleIndiCode	String
70	파견 지역코드	sendRegionCode	String
71	파견 보안등급	sendSecurityLevel	String	5	1:회장단(회장,부회장,비서실장) 2:사장단(사장,부사장,전무) 3:임원진(상무,이사,고문,감사) 4:간부(부,차,과장) 5:사원(대리,사원) 9:협력사 임직원
72	파견 총괄코드	sendSubOrgCode	String
73	파견 총괄명	sendSubOrgName	String
74	파견 직급명	sendTitleName	String	책임
75	파견 직급코드	sendTitleCode	String	E5
76	파견 직급 정렬 순서	sendTitleSortOrder	String	309
77	거점 *	serverLocation	String	KR	KR: 한국 GB: 구주 US: 미주
78	성 *	sirName	String	김
79	총괄코드	subOrgCode	String
80	총괄명	subOrgName	String
81	직급명 *	titleName	String	책임
82	직급코드 *	titleCode	String	B2K
83	직급정렬순서 *	titleSortOrder	String	54
84	고유코드	openCode	String
85	로그인 아이디 *	userId	String	knoxportal
86	인터넷 전화번호	voipNumber	String
87	퇴직/휴직일	withdrawDate	String
88	ID 유효기간	epIdExpiryDate	String	20201231
89	타임존	timeZone	String	Asia/Seoul	이름으로 검색 시에는 제공하지 않음

Sample

Request	Response

(1)
/employees?departmentCode=C60AH959
{"resultType" :"basic"}


(2)
/employees?companyCode=C60&userIds=es.jen.cho,ye.chang
{"resultType" :"optional",
 "attributes":["emailAddress","userId"]
}

(1)
* 기본 값으로 설정된 attributes값만 리턴
{"result":"success",
 "currentPage":1,
 "totalPage":2,
 "totalCount":612,
 "employees":[
       {"fullname":"조은성",
       "departmentname":"개발그룹(SC_인트라넷)",
       "departmentcode":"C60AH959",...},
       {"fullName":"김민정","departmentname".....}]
}



(2)
* body에 설정된 attributes값만 리턴
{"result":"success",
 "currentPage":1,
 "totalPage":1,
 "totalCount":2,
 "employees":[{"emailAddress":"es.jen.cho@stage.samsung.com","userId":"es.jen.cho"},
              {"emailAddress":"ye.chang@stage.samsung.com","userId":"ye.chang"}]
}

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	EM0001	Search request with more than 100 list can not be proceeded.	조회건수 100건 초과하여 에러 발생. Parameter 추가하여 조회 건수 축소
400	EM0004	Please insert the search keyword.	Parameter 누락 확인
400	EM0005	Search keyword length is not valid.	Parameter 길이 확인
400	EM0006	Search keyword should be no longer than 100 characters.	Parameter 길이 100자 이하로 작성
400	EM0007	Search keyword can not include the caracter.	Parameter에 *, % 이 포함되어 있는지 확인
500	EM0010	EPWebservice.{} Abnormal.	Parameter 누락 또는 잘못된 형식인지 확인
400	EM0014	Please enter {} as required.	{} 필수값 누락
400	EM0015	Please enter {} according to the specified format.	잘못된 형식으로 인한 오류
400	EM0016	Only one of {} can be selected.	{} 중 한 개만 선택하여 검색 가능
400	EM0017	For the requested search conditions, paging is not possible.	페이징 지원 불가
400	EM0018	Please remove the {} keyword from the requested search conditions and try again.	요청한 검색조건 중, {} 조건 제거 후 다시 시도 바랍니다.

조직도 조회

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 아이디	System-ID	Y	Header	String	C60REST0001
2	회사코드	companyCode	Y	Query	String	C60	2번 항목 단독 검색 또는 3~5번 항목 중 하나와 결합하여 검색
3	상위부서코드	uprDepartmentCode	N	Query	String	C60AI572	companyCode 쿼리와 함께 사용 (3~5번 중 한 가지만 선택 가능)
4	부서코드	departmentCode		Query	String	C60AH959	companyCode 쿼리와 함께 사용
5	부서명	departmentName		Query	String	123123	companyCode 쿼리와 함께 사용
6	페이지 번호	page	N	Query	String	1	companyCode로만 조회하는 경우에만 paging 적용가능 page 입력 시 500건씩 조회 page 입력하지 않을 경우 최대 2,000건 조회 (companyCode로만 검색 시 필수)

Response Parameter

- 조회대상 회사의 조직정보만 리턴
- 조회대상 회사에 신청 회사 외 타사 등록 시 일부 속성(아래 * 표시한 11개 항목)만 조회 가능

No.	Properties	Attribute	Data Type	Sample Data	Note

1	API 호출 성공 여부	result	String	success fail
2	현재 페이지	currentPage	int	1
3	총 결과 페이지 수	totalPage	int	3
4	검색된 조직정보의 수	totalCount	int	30
5	조직 정보 리스트	organizations	JSON String
6	회사코드 *	companyCode	string	C60
7	회사명 *	companyName	string	삼성SDS
8	부서코드 *	departmentCode	string	C60AH959
9	부서레벨	departmentLevel	string	3
10	부서명 *	departmentName	string	Knox개발그룹(솔루션개발)
11	부서간 순위	departmentOrder	string	2
12	영문 회사명 *	enCompanyName	string	SAMSUNG SDS
13	영문 부서명 *	enDepartmentName	string	Knox Development Group
14	영문 부서장 직급	enManagerTitle	string	Principal Engineer/Group Leader
15	영문 총괄명 *	enSubOrgCode	string
16	내부부서 코드 *	inDepartmentCode	string
17	하위 부서존재 유무	lowDepartmentYn	string	T	T: 존재함 F: 존재하지 않음
18	부서장 아이디	managerId	string	kch.jung
19	부서장 성명	managerName	string	정기철
20	부서장 직급	managerTitle	string	Principal Engineer/그룹장(Sr. SCP)
21	표현언어 *	preferredLanguage	string	ko
22	총괄코드 *	subOrgCode	string
23	총괄명 *	subOrgName	string
24	상위 부서코드	uprDepartmentCode	string	C60AJ336
25	영문 상위 부서명	enUprDepartmentName	string	Solution Development Team
26	상위 부서명	uprDepartmentName	string	솔루션개발팀
27	부서 숨김 여부	hiddenDepartmentYn	string	F	T: 비노출 F: 노출
28	법인코드	corpCode	string	A001
29	법인명	corpName	string	영국법인
30	영문법인명	enCorpName	string	UK CORP

Sample

Request	Response

/organizations?companyCode=C60&departmentCode=C60AH959

{
 "currentPage":"1",
 "totalPage":"1",
 "totalCount":"1",
 "organizations":[{"companyCode":"C60",
                   "departmentname":"knox개발그룹",
                   "enDepartmentName":"Knox Development Group ",
                   ...}]
}

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ORG0003	Please insert the search keyword.	Parameter 확인
400	ORG0004	Search keyword must be larger than 4 bytes.	Parameter 길이 4자 이상으로 작성
400	ORG0005	Search keyword should be no longer than 100 characters.	Parameter 길이 100자 이내로 작성
400	ORG0006	Search keyword can not include the caracter.	Parameter에 *, % 이 포함되어 있는지 확인
500	ORG0010	ORGWebservice. {} Abnormal.	Parameter 누락 또는 잘못된 형식인지 확인
400	ORG0011	Please enter {} as required.	{} 필수값 누락
400	ORG0012	Please enter {} according to the specified format.	잘못된 형식으로 인한 오류
400	ORG0013	Only one of {} can be selected.	{} 중 한 개만 선택하여 검색 가능
400	ORG0014	For the requested search conditions, paging is not possible.	페이징 지원 불가

직급정보 조회

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 아이디	System-ID	Y	Header	String	C60REST0001
2	회사코드	companyCode	Y	Query	String	C60

Response Parameter

No.	Properties	Attribute	Data Type	Sample Data	Note

1	API 호출 성공 여부	result	String	success fail
2	직급정보 배열	titles	JSON String
3	회사코드	companyCode	String	C60
4	직급코드	titleCode	String	B3K
5	직급명	titleName	String	책임
6	영문직급명	enTitleName	String	Senior Engineer
7	직급정렬 순서	sortOrder	String	1

Sample

Request	Response

/titles?companyCode=C60

{
 "result":"success",
 "titles":[{"companyCode":"C60",
            "titleCode":"J8",
            "titleName":"사장",
            "enTitleName":"CEO",
            "sortOrder":"1"},
           {"companyCode":"C60",
           "titleCode":"J7",
           "titleName":"상무",
           "enTitleName":"상무",
           "sortOrder":"2"},
	...]
}

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ORG0003	Please insert the search keyword.	Parameter 확인
400	ORG0005	Search keyword should be no longer than 100 characters.	Parameter 길이 100자 이내로 작성
400	ORG0006	Search keyword can not include the caracter.	Parameter에 *, % 이 포함되어 있는지 확인
500	ORG0010	ORGWebservice. {} Abnormal.	Parameter 누락 또는 잘못된 형식인지 확인