자격증명 등록

기관에 로그인할 공동인증서나 아이디를 등록하고, 작업이 어떤 자격증명을 쓸지 정하는 방법입니다.

XBOSS 는 고객을 대신해 기관에 로그인합니다. 그래서 로그인에 쓸 자격증명(공동인증서 또는 기관 아이디·비밀번호)을 먼저 등록해야 합니다.

등록하면 자격증명마다 account_link_id(UUID)가 발급됩니다. 비밀번호가 아니라, 작업에서 어떤 자격증명을 쓸지 가리키는 식별자입니다.

자격증명은 등록한 사용자에게 묶입니다. API 키로 작업을 제출할 때는 그 키를 만든 사용자가 등록한 자격증명만 쓸 수 있습니다.

STEP 01
콘솔에서 등록
자격증명 등록 화면에서 공동인증서나 기관 아이디를 올립니다.
STEP 02
연동 ID 발급
자격증명마다 account_link_id 가 생깁니다.
STEP 03
작업에 사용
생략하면 대표 자격증명이, 지정하면 그 자격증명이 쓰입니다.

기관별 자격증명

자격증명	기관	account_link_id 생략
공동인증서	홈택스 · 국민건강보험공단 · 국민연금공단 · 4대보험 · 근로복지공단 · 고용24 · KB국민카드	가능 — 아래 자동 선택 규칙을 따릅니다.
기관 아이디·비밀번호	신한은행 · IBK기업은행 · KB국민은행 · 우리은행	불가 — 항상 직접 지정합니다.

자동 선택 규칙

상황	결과
대표로 지정한 자격증명이 있음	그 자격증명으로 로그인합니다.
대표가 없고 사용 중인 자격증명이 1건	그 1건으로 로그인합니다.
대표가 없고 2건 이상	400 VALIDATION_INVALID_FIELD — 어느 것을 쓸지 정할 수 없으므로 account_link_id 를 직접 보냅니다.
등록한 자격증명이 하나도 없음	제출은 접수되지만(202) 작업이 기관에 닿기 전에 FAILED 로 끝납니다. 오류의 모습과 해결은 아래 표에 있습니다. 샌드박스의 EDI 기관은 모의 응답으로 처리되지만, 홈택스는 샌드박스에서도 자격증명이 필요합니다.
지정한 account_link_id 가 없거나 이 키를 만든 사용자가 등록한 것이 아님	400 VALIDATION_INVALID_FIELD — 없는 것 · 다른 사용자가 등록한 것 · 다른 상품의 것 · 사용을 중단한 것 모두 같은 400 입니다. 남의 연결이 있다는 사실이 드러나지 않게 한 문장으로 답합니다.
account_link_id 형식이 잘못됨	400 VALIDATION_INVALID_FIELD

자격증명 없이 제출하면

확인할 곳	값
제출 응답	202 — 접수만 되고, 실패는 작업 상태에서 알게 됩니다.
작업 상태	FAILED — 기관에는 요청이 나가지 않았습니다.
error.code	VALIDATION_INVALID_FIELD — 본문 오류에도 쓰이는 코드라, 이 경우는 아래 provider_error_ref 로 가립니다.
error.provider_error_ref	상품이름.missing_account_link_id 꼴입니다. 홈택스라면 hometax.missing_account_link_id 입니다.
error.message	영문 기술 문구로 올 수 있습니다. 문구는 바뀔 수 있어 분기에 쓰지 않습니다.
해결	콘솔에서 자격증명을 등록한 뒤 새 Idempotency-Key 로 다시 제출합니다. 기관에 닿기 전에 멈춘 실패라 원인을 고친 뒤의 제출은 새 요청이고, 기관에서 두 번 처리되지 않습니다.

공동인증서를 한 번 등록하면 같은 인증서를 쓰는 다른 기관에도 함께 연결됩니다. 등록할 때 제외할 기관을 고를 수 있습니다.

등록은 콘솔에서 합니다

콘솔 자격증명 등록에서 등록합니다. 인증서 파일과 비밀번호는 브라우저에서 암호화되어 전송됩니다.

공동인증서는 Windows PC 에 XBOSS PKI Agent 를 처음 한 번 설치해야 등록할 수 있습니다. macOS 와 Linux 에서는 공동인증서를 등록할 수 없습니다. 기관 아이디와 계좌 자격증명은 설치 없이 등록합니다.

일반 API 키로 POST /v1/credentials/link 를 호출하면 403 입니다. 여러 고객사의 자격증명을 서버에서 등록해야 한다면 콘솔 멀티계정 연동에서 신청합니다. 운영자 승인 뒤 전용 키가 발급되고, 그 키로 연결하는 방법은 멀티계정 SDK 안내(미리보기)에 있습니다.

기능	경로	호출할 수 있는 주체
자격증명 등록	POST /v1/credentials/link	콘솔 로그인 · 멀티계정 연동 키
연동 해제	POST /v1/credentials/{account_link_id}/unlink	콘솔 로그인 · 멀티계정 연동 키
목록 조회	GET /v1/credentials	콘솔 로그인
사용 가능 여부 확인	GET /v1/credentials/{account_link_id}	멀티계정 연동 키 — 사용 중이면 200, 아니면 404

같은 계정을 다시 등록하면

등록 방식	같은 값으로 다시 등록	다른 값으로 다시 등록
공동인증서	200 — 아무것도 바꾸지 않고, 열어 둔 기관 세션도 그대로입니다.	다른 인증서라 새 연동으로 등록됩니다(201, 새 account_link_id).
기관 아이디·비밀번호	200 — 아무것도 바꾸지 않습니다.	같은 아이디에 다른 비밀번호를 보내면 confirm 이 true 가 아닐 때 409 RESOURCE_CONFLICT 이고 error.reason 은 material_replacement_not_confirmed 입니다. confirm: true 로 다시 보내면 200 으로 비밀번호가 바뀌고, 그 연동으로 열어 둔 기관 세션이 모두 끊어집니다.

confirm 은 등록 요청 본문의 선택 필드(true/false, 기본 false)이고 기관 아이디·비밀번호 등록에서만 뜻이 있습니다 — 바꾸려는 것이 맞다는 명시 확인입니다. 옛 비밀번호로 되돌릴 수 없고 기관 세션도 함께 끊어지기 때문에, 값이 다른데 확인이 없으면 요청을 거절합니다. 동의 화면으로 연결하는 서비스는 동의를 다시 거치면 기존 연동이 갱신되고(200) 그 과정이 확인을 겸하므로 confirm 이 필요 없습니다.

확인 없이 비밀번호를 바꾸려 할 때 (HTTP 409)

json

{
  "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 가 오고, 콘솔 기본정보에서 다시 동의하면 풀립니다. 자세한 내용은 약관 동의를 봅니다.