인증 - 근로복지공단
1. 고용산재 NPKI 세션 로그인comwel. auth. npki_ session. login
MCP 도구 이름 comwel__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
사업자 공동인증서로 근로복지공단 토탈서비스에 로그인해 이후 조회에 쓸 연결을 만듭니다.
- 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
- 콘솔에 공동인증서를 등록하지 않았거나 account_link_id 가 이 키를 만든 사용자가 등록한 것이 아니면 제출이 400 VALIDATION_INVALID_FIELD 로 거절되고 작업이 만들어지지 않습니다.등록하거나 값을 고친 뒤 다시 제출합니다.
- 사업자등록번호(business_registration_no)는 필수입니다.하이픈을 뺀 10자리여야 합니다. 별칭 businessRegistrationNo · business_no · businessNo · saeopja_drno 도 받습니다.사업장관리번호(business_management_no)는 선택이며, 그 사업자등록번호에 사업장이 둘 이상일 때 로그인할 사업장의 번호(숫자 11자리)를 보냅니다. 사업장이 하나면 보내지 않아도 됩니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| business_ | string | N | 선택 입력. 사업자등록번호에 사업장이 둘 이상일 때 로그인할 사업장의 사업장관리번호(숫자 11자리)를 넣습니다. 사업장이 하나면 넣지 않아도 됩니다. 넣은 번호가 그 사업자번호의 사업장 목록에 없으면 로그인하지 않습니다 | |
| business_ | string | Y | 사업자등록번호 10자리(예: 1234567890). 별칭 businessRegistrationNo / business_no / businessNo / saeopja_drno / SAEOPJA_DRNO |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: login-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "comwel",
"action": "comwel.auth.npki_session.login",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_registration_no": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 authenticated 로 로그인 성공 여부를, cookie_count 로 확보한 쿠키 수를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| auth_ | string | 인증 방식 - 등록한 공동인증서(npki_anysign) | |
| authenticated | boolean | 세션 인증 완료 여부 | |
| live_ | boolean | 이후 조회에 쓸 인증 재료 준비 여부 | |
| missing_ | array | 누락된 인증 재료 키 목록 | |
| cookie_ | number | 저장된 쿠키 수 | |
| business_ | string | 사업자등록번호 | |
| business_ | string | 사업장관리번호 | |
| business_ | string | 사업장관리번호 - 000-00-00000-0 표기 | |
| generation_ | string | 세션 생성 상태 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "comwel",
"action": "comwel.auth.npki_session.login",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 로그인 인증 실패 — 근로복지공단이 로그인을 인증하지 않았거나 등록한 인증서의 개인키를 열지 못한 경우입니다(인증서 비밀번호가 틀렸을 수 있습니다). 같은 인증서로는 다시 호출해도 결과가 같아 재시도 불가로 표시되니, error.message 안내대로 공동인증서와 비밀번호를 확인해 콘솔에서 인증서를 다시 등록한 뒤 호출합니다. | |
| PROVIDER_ | 로그인 실패 — 그 밖의 이유로 근로복지공단 로그인을 마치지 못했습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. 다만 error.provider_error_ref 가 comwel.login_anysign_ 으로 시작하면 등록한 인증서가 서명 단계에서 거절된 경우라 같은 인증서로는 풀리지 않으니, 콘솔에서 인증서를 확인해 다시 등록한 뒤 호출합니다. | |
| PROVIDER_ | 기관 연결 실패 — 근로복지공단에 연결하지 못해 로그인 요청을 보내지 못했습니다. error.provider_error_ref 는 comwel.connection_error 입니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 연결 지연 — 근로복지공단 접속 자체가 시간 안에 되지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 응답 지연 — 로그인 요청은 보냈지만 근로복지공단의 응답이 시간 안에 오지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 기관 일시 오류 — 근로복지공단이 서버 오류(500 번대) 상태로 답했습니다. error.provider_error_ref 끝의 숫자가 그 상태 코드입니다(예: comwel.upstream_http_503). 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 기관 요청 거절 — 근로복지공단이 로그인 요청을 400 번대 오류 상태로 거절했습니다(401 은 「로그인 실패」, 403 과 429 는 「접근 제한」 행입니다). 재시도 불가로 표시되니 사업자등록번호와 등록한 인증서를 확인하고, 계속되면 서비스문의로 알립니다. | |
| PROVIDER_ | 접근 제한 — 근로복지공단이 접근을 제한했습니다(403 이나 429 상태로 답했거나 접속을 끊음). 재시도 가능으로 표시되니 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다. | |
| POLICY_ | 개인사업자 — 사업자등록번호가 개인사업자 번호이면 로그인 세션을 저장하지 않고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다. | |
| PROVIDER_ | 세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 사업자등록번호 오류 — 사업자등록번호가 빠졌거나 하이픈을 뺀 10자리가 아닙니다. 재시도 불가로 표시되며, 값을 고치지 않으면 계속 실패합니다. | |
| VALIDATION_ | 사업장관리번호 오류 — 사업장관리번호(business_management_no)가 숫자 11자리가 아니면 근로복지공단에 로그인하기 전에 이 코드로 끝나며 error.message 는 「사업장관리번호는 숫자 열한 자리로 입력해 주세요.」 입니다. 자릿수는 맞지만 그 사업자등록번호의 사업장 목록에 없는 번호이면 로그인 뒤 목록을 보고 같은 코드로 끝나며 error.message 는 「입력한 사업장관리번호가 그 사업자번호의 사업장 목록에 없습니다. 사업장관리번호를 다시 확인해 주세요.」 입니다. 재시도 불가로 표시되니 번호를 고쳐 다시 호출합니다. | |
| VALIDATION_ | 사업장 정하기 실패 — 로그인 뒤 근로복지공단이 준 사업장 목록에서 로그인할 사업장을 하나로 정하지 못한 경우입니다. 그 사업자등록번호로 조회되는 사업장이 없으면 error.message 는 「그 사업자번호로 조회되는 사업장이 없습니다. 사업자등록번호를 다시 확인해 주세요.」 이고, 사업장이 둘 이상인데 사업장관리번호를 보내지 않았으면 「그 사업자번호에 사업장이 둘 이상이라 하나를 정하지 못했습니다. 사업장관리번호를 함께 입력해 주세요.」 입니다. 재시도 불가로 표시되니 사업자등록번호를 확인하거나 사업장관리번호를 함께 보내 다시 호출합니다. |
2. 고용산재 세션 상태 조회comwel. auth. session. status
MCP 도구 이름 comwel__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
저장된 근로복지공단 연결 정보로 어느 사업장의 연결인지와 인증이 끝났는지를 확인합니다.
- 선행 호출이 없어도 됩니다. 로그인 전에 불러도 실패하지 않고 exists:false 로 답합니다. params 는 빈 객체로 보냅니다. [근로복지공단 로그인]
- params 는 빈 객체로 보내도 호출됩니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: status-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "comwel",
"action": "comwel.auth.session.status",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 exists · authenticated 로 세션이 있는지, 인증됐는지 확인합니다. 세션이 없어도 작업은 실패하지 않고 exists: false 로 응답합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| exists | boolean | 세션 존재 여부(false 이면 로그인 필요) | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| authenticated | boolean | 인증 완료 여부 | |
| live_ | boolean | 이후 조회에 쓸 인증 재료 준비 여부 | |
| missing_ | array | 누락된 인증 재료 키 목록 | |
| cookie_ | number | 저장된 쿠키 수 | |
| business_ | string | 사업자등록번호 | |
| business_ | string | 사업장관리번호 | |
| business_ | string | 사업장관리번호 - 000-00-00000-0 표기 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "comwel",
"action": "comwel.auth.session.status",
"submitted_at": "2026-05-27T12:34:56+09:00"
}