인증 - 4대보험
1. 4대보험 EDI 세션 등록fourinsure. session. login
MCP 도구 이름 fourinsure__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
연동 계정 하나를 넣으면 그 계정에 등록된 공동인증서로 4대사회보험 정보연계센터에 로그인하고, 세션 저장 여부와 연동 계정 ID를 돌려줍니다.
- 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
- params 는 빈 객체로 보내도 호출됩니다. 콘솔에 등록한 공동인증서로 로그인하며, 사용할 인증서는 account_link_id 로 지정합니다.
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: login-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.session.login",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 작업이 성공하면 세션이 저장된 것입니다(저장에 실패하면 작업이 실패로 끝납니다). 이후 업무 API 는 같은 account_link_id 로 호출합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| auth_ | string | 인증 방식 — 로그인 작업은 등록한 공동인증서(npki_anysign) | |
| authenticated | boolean | 인증 완료 여부 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| cookie_ | number | 저장된 쿠키 수 | |
| generation_ | string | 세션 생성 상태 | |
| session_ | boolean | 세션 저장 여부 | |
| provider_ | boolean | 공급자 세션 저장 여부 |
// result.data
{
"success": true,
"API_KEY": "...",
"auth_provider": "npki_anysign",
"authenticated": true,
"csrf_token_present": true,
"cookie_count": 12,
"generation_status": "generated",
"session_registered": true,
"provider_session_registered": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 인증서 확인 — 콘솔에 등록한 공동인증서의 비밀번호가 비어 있거나 인증서 정보를 읽지 못한 경우입니다. 같은 인증서로는 다시 호출해도 결과가 같아 자동 재시도 대상이 아니니, error.message 안내대로 콘솔에서 인증서를 다시 등록한 뒤 호출합니다. | |
| PROVIDER_ | 로그인 인증 실패 — 등록한 공동인증서의 키를 열지 못했습니다. 인증서 비밀번호가 맞지 않거나 인증서 형식을 읽을 수 없는 경우입니다. 재시도 불가로 표시되니 같은 인증서로 되풀이하지 말고, error.message 안내대로 인증서 비밀번호를 확인하고 맞는데도 반복되면 콘솔에서 인증서를 다시 등록한 뒤 호출합니다. | |
| PROVIDER_ | 로그인 실패 — 로그인을 마치지 못했습니다. 인증서를 열지 못했거나, 기관에 연결하지 못했거나, 로그인이 끝나지 않았거나, 로그인 뒤 세션을 저장하지 못한 경우입니다. 재시도 가능으로 표시되지만 error.message 가 인증서 비밀번호를 확인하라고 안내하면 같은 인증서로 다시 호출해도 풀리지 않으니 콘솔에서 인증서를 다시 등록한 뒤 호출하고, 잠시 후 다시 시도하라고 안내하면 잠시 뒤 다시 호출하며, 서비스문의를 안내하면 문의합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| POLICY_ | 개인사업자 — 사업자등록번호가 개인사업자 번호이면 로그인 세션을 저장하지 않고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다. |