내부 인사 사용자 정보 수정

이 가이드는 외부 인사 도구에서 기존 SSO 사용자의 사번·이름·전화번호를 수정하는 절차입니다. 사용자 연결에는 SSO의 userId를 사용합니다. 사번이나 이메일을 고유 사용자 키로 사용하지 않습니다.

정확한 요청·응답은 OpenAPI를 따릅니다. 구현과 검증 기록은 #2506에 있습니다. 기존 Directory API의 외부 사용자 생성·소속 변경과 별도 경로입니다.

연결 준비

AdminFront의 API 키 관리에서 내부 인사 연동을 선택합니다.
한맥가족의 대상 조직을 선택합니다.
내부 인사 사용자 조회 키와 내부 인사 사용자 수정 키를 각각 발급합니다.
도구에 키를 별도로 보관하고 브라우저 코드·로그·CSV에 넣지 않습니다.
외부 인사 사용자와 SSO userId의 연결을 확인합니다.

조회 키는 hr.user.profile.read, 수정 키는 hr.user.profile.update를 사용합니다. 현재 대표 소속이 키의 조직 범위 안에 있어야 합니다. Stealth와 시스템 관리자 계정은 이 경로에서 처리하지 않습니다. 기존 일반 Directory 키를 대신 사용할 수 없습니다.

전체 대상의 userId가 필요하면 기존 조직 조회 API의 members[].id를 사용합니다. 이 조회에는 별도의 baron.org-context.read 키와 허용된 조직 범위가 필요합니다. 외부 인사 자료와 연결할 때 여러 사용자가 같은 이름을 쓰거나 사번이 비어 있으면 자동으로 일치시킨 것으로 처리하지 않습니다.

조회와 수정

아래 요청의 호스트는 사용 중인 SSO 주소로 지정합니다. userId에는 SSO 사용자 UUID를 넣습니다. 먼저 조회 키로 현재 정보를 읽습니다.

GET /api/v1/integrations/hr/users/{userId}/profile
X-Baron-Key-ID: <read-client-id>
X-Baron-Key-Secret: <read-secret>

응답의 revision은 조회한 사용자 정보의 버전입니다. 이 값을 expectedRevision에 넣고 수정 키로 변경을 요청합니다. 사번 앞자리의 0을 보존하려면 JSON 문자열로 전달합니다.

PATCH /api/v1/integrations/hr/users/{userId}/profile
X-Baron-Key-ID: <update-client-id>
X-Baron-Key-Secret: <update-secret>
Idempotency-Key: <unique-source-event-id>
Content-Type: application/json

{
  "expectedRevision": "<revision-from-get>",
  "employeeNumber": "001234"
}

필드를 생략하면 기존 값은 유지됩니다. 사번에 null 또는 빈 문자열을 보내면 사번을 삭제합니다. 이름은 비어 있지 않은 문자열이며, 전화번호는 +821012345678처럼 국가번호를 포함한 E.164 문자열입니다. 이름·전화번호의 null과 빈 문자열은 거절됩니다.

이 경로는 employeeNumber, name, phone만 수정합니다. 부서·직급·직책·입퇴사 상태·비밀번호·권한 변경을 같은 요청에 넣지 않습니다. 기존 사번 호환 키는 서버가 함께 맞춥니다.

결과 확인과 재시도

수정 응답의 operationId와 statusUrl을 저장합니다. 200은 SSO 저장 결과이며 WORKS 반영 완료를 뜻하지 않습니다. 202이면 저장 결과 확인이 필요하므로 조회 키로 statusUrl을 조회합니다.

GET /api/v1/integrations/hr/users/{userId}/operations/{operationId}
X-Baron-Key-ID: <read-client-id>
X-Baron-Key-Secret: <read-secret>

응답은 SSO 저장 상태, 저장 후 처리 상태, WORKS 작업 상태를 구분합니다. worksmobileStatus=verified는 해당 작업의 원격 검증 완료를 뜻합니다. pending과 processing은 대기 상태입니다. failed와 not_enqueued는 원격 반영 완료가 아니므로 원인을 확인합니다. superseded는 더 최신 변경으로 교체된 작업이므로 이전 작업의 반복 조회를 끝내고 최신 작업을 확인합니다. 자세한 WORKS 작업 처리는 WORKS 연동 Runbook을 따릅니다.

상태 필드	값과 처리
`storageStatus`	`committed`는 SSO 저장 확정입니다. `unknown`은 결과 미확정이며 새 작업으로 중복 요청하지 않습니다. `not_committed`는 저장 확정 전 상태입니다.
`projectionStatus`	`pending`은 조회용 사본 반영 대기, `applied`는 반영 완료, `failed`는 반영 실패입니다.
`postCommitStatus`	`pending`은 후속 처리 대기, `applied`는 처리 완료, `failed`는 재처리 대상, `blocked`는 운영 확인이 필요한 중단 상태입니다.

도구는 대기 중인 작업의 ID를 보존하고 제한된 간격으로 상태를 조회합니다. 대기 시간이 도구의 제한을 넘으면 작업을 대기 목록에 남깁니다. unknown을 실패로 단정하거나 새 키로 같은 변경을 다시 보내지 않습니다.

결과	도구의 처리
응답을 받지 못함	같은 본문과 같은 `Idempotency-Key`로 재시도합니다.
`409` revision 충돌	현재 정보를 다시 조회하고 변경 내용을 비교한 뒤 새 작업으로 요청합니다.
`409` 재시도 내용 충돌	기존 작업 키에 다른 본문을 사용했는지 확인합니다.
`409` 식별자 충돌	다른 계정이 해당 로그인 식별자를 사용하는지 확인합니다.
`401` 또는 `403`	키의 상태·Operation·현재 조직 범위를 확인합니다.
`503`	조회 또는 저장소 장애를 확인하고 기존 작업 결과부터 확인합니다.

전체 사번 갱신 도구도 사용자마다 조회·수정·결과 확인을 수행합니다. 각 사용자 변경에 별도 작업 키를 사용하고 성공·실패·대기 결과를 따로 남깁니다. 이 API에는 일괄 수정 endpoint가 없습니다.

사용자 편집 화면에서 비교

사용자 정보 편집 화면에서 WORKS 정보 비교를 선택합니다. 저장된 SSO 정보와 현재 WORKS 값을 비교하며, 다른 항목 아래에 WORKS: 값을 표시합니다. 이 버튼은 값을 수정하지 않습니다.

비교 대상은 이름·이메일·전화번호·사번·보조 이메일·대표 소속의 부서·직급·직책·직무입니다. 원격 API가 반환하지 않은 필드는 조회 불가로 표시합니다. 미연결 계정·연동 비대상·조회 실패는 값 불일치와 구분합니다. SSO 보조 전화번호와 계정 상태는 이 필드 비교 대상이 아닙니다.

화면을 수정하면 이전 비교 결과를 숨깁니다. 변경을 저장한 뒤 다시 비교합니다. WORKS 반영은 비동기 처리이므로 저장 직후에는 이전 WORKS 값이 표시될 수 있습니다.

6.7 KiB Raw Blame History

내부 인사 사용자 정보 수정

연결 준비

조회와 수정

결과 확인과 재시도

사용자 편집 화면에서 비교

6.7 KiB

Raw Blame History