자격증명 등록
기관에 로그인할 공동인증서나 아이디를 등록하고, 작업이 어떤 자격증명을 쓸지 정하는 방법입니다.
XBOSS 는 고객을 대신해 기관에 로그인합니다. 그래서 로그인에 쓸 자격증명(공동인증서, 기관 아이디와 비밀번호, Google 동의 화면 승인, 또는 블로그 연결)을 먼저 등록해야 합니다.
등록하면 자격증명마다 account_link_id(UUID)가 발급됩니다. 비밀번호가 아니라, 작업에서 어떤 자격증명을 쓸지 가리키는 식별자입니다.
자격증명은 등록한 사용자에게 묶입니다. API 키로 작업을 제출할 때는 그 키를 만든 사용자가 등록한 자격증명만 쓸 수 있습니다.
- STEP 01콘솔에서 등록
자격증명 등록 화면에서 공동인증서나 기관 아이디를 올립니다.
- STEP 02연동 ID 발급
자격증명마다 account_link_id 가 생깁니다.
- STEP 03작업에 사용
자격증명이 하나뿐이면 생략해도 그것이, 지정하면 그 자격증명이 쓰입니다.
기관별 자격증명
| 자격증명 | 기관 | account_link_id 생략 |
|---|---|---|
| 공동인증서 | 홈택스 · 국민건강보험공단 · 국민연금공단 · 4대보험 · 근로복지공단 · 고용24 · KB국민카드 · 위택스 · 사회보험통합징수포털 · 정부24 · 교통민원24 | 가능 — 아래 자동 선택 규칙을 따릅니다. |
| 기관 아이디·비밀번호 | 신한은행 | 불가 — 항상 직접 지정합니다. |
| 계좌번호와 계좌 비밀번호 | IBK기업은행 · KB국민은행 · 우리은행 · 하나은행 · NH농협은행 | 불가 — 항상 직접 지정합니다. |
| API 키(광고계정 번호, API 라이선스 키, 비밀키) | 네이버 검색광고 | 가능 — 아래 자동 선택 규칙을 따릅니다. |
| Google 동의 화면 승인 | Google 마케팅 | 가능 — 아래 자동 선택 규칙을 따릅니다. |
| 블로그 연결(콘솔 연결 창에서 블로그에 직접 로그인) | 티스토리 · 네이버 마케팅 | 가능 — 아래 자동 선택 규칙을 따릅니다. |
자동 선택 규칙
| 상황 | 결과 |
|---|---|
| 사용 중인 자격증명이 1건 | 그 1건을 씁니다. |
| 사용 중인 자격증명이 2건 이상 | 400 VALIDATION_INVALID_FIELD — 대표로 지정한 자격증명이 있어도 어느 것을 쓸지 고르지 않으므로 account_link_id 를 직접 보냅니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. |
| 등록한 자격증명이 하나도 없음 | 400 VALIDATION_INVALID_FIELD — 제출이 거절되고 작업이 만들어지지 않습니다. 자격증명이 필요 없는 작업은 그대로 접수됩니다. 거절된 응답의 모습과 해결은 아래 표에 있습니다. |
| 지정한 account_link_id 가 없거나 이 키를 만든 사용자가 등록한 것이 아님 | 400 VALIDATION_INVALID_FIELD — 없는 것 · 다른 사용자가 등록한 것 · 다른 상품의 것 · 사용을 중단한 것 모두 같은 400 입니다. 남의 연결이 있다는 사실이 드러나지 않게 한 문장으로 답합니다. |
| account_link_id 형식이 잘못됨 | 400 VALIDATION_INVALID_FIELD |
자격증명 없이 제출하면
| 확인할 곳 | 값 |
|---|---|
| 제출 응답 | 400 — 접수 단계에서 거절됩니다. 작업이 만들어지지 않으므로 작업 아이디가 없고, 하루 한도도 줄지 않으며, 기관에도 요청이 나가지 않습니다. |
| error.code | VALIDATION_INVALID_FIELD — 본문 값 오류에도 쓰이는 코드입니다. 자격증명이 필요한 작업을 account_link_id 없이 보냈다면, 먼저 등록한 자격증명이 있는지 확인합니다. |
| error.message | 문구는 바뀔 수 있어 분기에 쓰지 않습니다. |
| 해결 | 콘솔에서 자격증명을 등록한 뒤 다시 제출합니다. |
계좌 자격증명은 한 연동에 계좌가 여러 개일 수 있습니다.계좌를 고르는 칸(bank_account_credential_id)이 선택인 조회를 그 칸 없이 보냈는데 연동한 계좌가 여러 개면 서버가 대신 고르지 않고 작업이 RESOURCE_CONFLICT 로 실패합니다.그 실패의 다음 행동 안내(REST 는 error.next, MCP 는 xdata.kr/next)가 choose_bank_account 단계로 고를 수 있는 계좌 목록을 주니, 하나를 골라 그 bank_account_credential_id 를 넣어 다시 요청합니다.자세한 칸은 MCP 오류 코드에 있습니다.
콘솔에서 공동인증서를 한 번 등록하면 같은 인증서를 쓰는 다른 기관에도 함께 연결됩니다.등록할 때 제외할 기관을 고를 수 있습니다. 멀티계정 연동 키로 등록하면 지정한 기관 하나만 연결되므로 기관마다 등록합니다.
등록은 콘솔에서 합니다
콘솔 자격증명 등록에서 등록합니다. 인증서 파일과 비밀번호는 브라우저에서 암호화되어 전송됩니다.
- 공동인증서는 Windows PC 에 XBOSS 연결 프로그램을 처음 한 번 설치해야 등록할 수 있습니다.
- macOS 와 Linux 에서는 공동인증서를 등록할 수 없습니다.
- 기관 아이디, 계좌 자격증명, API 키, 블로그 연결은 설치 없이 등록합니다.
- 블로그 연결은 콘솔에 로그인한 본인만 할 수 있고(API 키로는 할 수 없습니다), 시작할 때 연결 정보 수집, 보관 안내에 동의합니다.
일반 API 키로 POST /v1/credentials/link 를 호출하면 403 입니다.
여러 고객사의 자격증명을 서버에서 등록해야 한다면 콘솔 멀티계정 연동에서 신청합니다.
운영자 승인 뒤 전용 키가 발급되고, 그 키로 연결하는 방법은 멀티계정 SDK 안내(미리보기)에 있습니다.
그 키로 보내는 요청은 위 자동 선택에 기대지 말고 어느 고객사의 요청인지 항상 지정합니다.
관련 API
| 기능 | 경로 | 호출할 수 있는 주체 |
|---|---|---|
| 자격증명 등록 | POST /v1/credentials/link | 콘솔 로그인 · 멀티계정 연동 키 |
| 연동 해제 | POST /v1/credentials/{account_link_id}/unlink | 콘솔 로그인 · 멀티계정 연동 키 |
| 목록 조회 | GET /v1/credentials | 콘솔 로그인 |
| 사용 가능 여부 확인 | GET /v1/credentials/{account_link_id} | 콘솔 로그인, 멀티계정 연동 키 — 사용 중이면 200, 아니면 404, 아이디 형식이 틀리면 400 |
| 기관 사이트 비밀번호 저장, 변경, 삭제 | PUT /v1/credentials/{account_link_id}/site-password | 콘솔 로그인, 멀티계정 연동 키 — 200 이면 저장돼 있는지(has_site_password)만 돌려주고, 받지 않는 기관이면 400, 내 연동이 아니면 404 |
기관 사이트 비밀번호
일부 사업장은 인증서 비밀번호와 별도로 기관 사이트 비밀번호를 요구합니다.받는 기관은 기관 입력 규격(멀티계정 개발 규격)의 input_contract.optional 에 site_password 가 있는 기관입니다.
- 인증서를 등록할 때 encrypted_site_pw 칸에 함께 보낼 수 있습니다(선택). 인증서 비밀번호와 같은 방식으로 암호화합니다.
- 함께 연결되는 기관 가운데 받는 기관에만 저장됩니다. 받는 기관이 하나도 없는 요청에 실으면 400 VALIDATION_INVALID_FIELD 입니다.
- 이미 연동한 인증서에는 위 PUT 경로로 넣거나 바꿉니다. 본문의 encrypted_site_pw 를 null 로 보내면 저장된 값을 지웁니다.
- 응답과 조회 어디에도 값은 돌아오지 않습니다.
같은 계정을 다시 등록하면
| 등록 방식 | 같은 값으로 다시 등록 | 다른 값으로 다시 등록 |
|---|---|---|
| 공동인증서 | 200 — 같은 연동을 돌려주고, 열어 둔 기관 세션도 그대로입니다. 서버가 이번 요청의 개인키에서 VID(random_enc)를 읽었다면 저장된 VID 를 그 값으로 바로잡습니다. 인증서 이름(cert_name)을 함께 보냈으면 그 연동의 이름이 그 값으로 바뀝니다. | 같은 기관에 등록한 인증서를 새 인증서로 바꾸는 경우는 둘입니다. 첫째, 등록 요청에 사업자번호(biz_number)를 함께 보냈고 같은 기관에 사업자번호가 같은 인증서가 이미 연동돼 있을 때입니다. 멀티계정 키로 보낸 요청은 옛 인증서와 인증서에 적힌 이름(요청의 cert_name 이 아니라 인증서 자체의 이름)까지 같아야 하고, 다르면 바꾸지 않고 400 VALIDATION_INVALID_FIELD 입니다. 둘째, 사업자번호 없이 보냈고(콘솔 등록과 0.1.2 SDK 는 이 칸을 보내지 않습니다) 같은 기관에 주체와 발급기관이 같은 인증서가 정확히 하나 등록돼 있을 때입니다. 사업자번호를 넣어 등록한 연동과 멀티계정 키로 등록하거나 다시 등록한 적이 있는 연동은 이 비교에서 빠집니다. 바꾸면 같은 account_link_id 로 200 UPDATED 를 돌려주고, 연동 수는 늘지 않으며 대표 여부도 그대로이고, 옛 인증서로 열어 둔 기관 세션은 닫힙니다. 이 두 경우 모두 새 인증서의 유효기간이 이미 지났으면 바꾸지 않고 400 VALIDATION_INVALID_FIELD 입니다. 그 밖(사업자번호가 다르거나, 바꿀 연동이 없거나 둘 이상이거나, 사업자번호 없이 보냈는데 비교할 인증서가 다섯을 넘거나 옛 인증서를 확인하지 못한 경우)은 새 연동입니다(201, 새 account_link_id). |
| 기관 아이디·비밀번호 | 200 — 아무것도 바꾸지 않습니다. | 같은 아이디에 다른 비밀번호를 보내면 confirm 이 true 가 아닐 때 409 RESOURCE_CONFLICT 이고 error.reason 은 material_replacement_not_confirmed 입니다. confirm: true 로 다시 보내면 200 으로 비밀번호가 바뀌고, 그 연동으로 열어 둔 기관 세션이 모두 끊어집니다. |
| 계좌번호와 계좌 비밀번호 | 200 — 아무것도 바꾸지 않습니다. | 같은 계좌번호에 다른 값(계좌 비밀번호 등)을 보내면 기관 아이디와 비밀번호와 같이 confirm 이 true 가 아닐 때 409 RESOURCE_CONFLICT(material_replacement_not_confirmed)이고, confirm: true 로 다시 보내면 200 으로 값이 바뀌고 그 연동으로 열어 둔 기관 세션이 모두 끊어집니다. |
| API 키(네이버 검색광고) | 200 — 아무것도 바꾸지 않습니다. | 같은 광고계정 번호에 다른 키 값을 보내면 기관 아이디와 비밀번호와 같이 confirm 이 true 가 아닐 때 409 RESOURCE_CONFLICT(material_replacement_not_confirmed)이고, confirm: true 로 다시 보내면 200 으로 키 값이 바뀝니다. |
confirm 은 값을 바꾸려는 것이 맞다는 명시 확인입니다.
- 등록 요청 본문의 선택 필드(true/false, 기본 false)로, 기관 아이디와 비밀번호 등록, 계좌번호와 계좌 비밀번호 등록, API 키(네이버 검색광고) 등록에서만 뜻이 있습니다.
- 값이 다른데 확인이 없으면 요청을 거절합니다. 옛 값으로 되돌릴 수 없고 기관 세션도 함께 끊어지기 때문입니다.
- 동의 화면으로 연결하는 서비스는 confirm 이 필요 없습니다. 동의를 다시 거치면 기존 연동이 갱신되고(200) 그 과정이 확인을 겸합니다.
확인 없이 비밀번호를 바꾸려 할 때 (HTTP 409)
{
"error": {
"code": "RESOURCE_CONFLICT",
"message": "이미 등록된 계정과 같은 아이디인데 비밀번호가 다릅니다. 그대로 진행하면 저장된 비밀번호가 이번에 보낸 값으로 바뀌고, 이 연동으로 열어 둔 기관 세션도 모두 끊어집니다. 바꾸려는 것이 맞다면 confirm 을 true 로 주고 다시 요청해 주세요.",
"retryable": false,
"provider_error_ref": null,
"trace_id": "trc_5f0c2a9e8d7b4c1f9a3e6b2d4c8f1a07",
"reason": "material_replacement_not_confirmed"
}
}자격증명 등록과 작업 호출 전에 이용약관과 개인정보 처리방침 동의가 필요합니다.
동의하지 않았거나 약관이 바뀌면 403 COMPLIANCE_TOS_VERSION_OUTDATED 가 오고, 콘솔 기본정보에서 다시 동의하면 풀립니다.자세한 내용은 약관 동의를 봅니다.