개발자 문서
개발자 문서

자격증명 등록

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

XBOSS 는 고객을 대신해 기관에 로그인합니다. 그래서 로그인에 쓸 자격증명(공동인증서, 기관 아이디와 비밀번호, Google 동의 화면 승인, 또는 블로그 연결)을 먼저 등록해야 합니다.

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

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

  1. STEP 01
    콘솔에서 등록

    자격증명 등록 화면에서 공동인증서나 기관 아이디를 올립니다.

  2. STEP 02
    연동 ID 발급

    자격증명마다 account_link_id 가 생깁니다.

  3. STEP 03
    작업에 사용

    자격증명이 하나뿐이면 생략해도 그것이, 지정하면 그 자격증명이 쓰입니다.

콘솔에서 자격증명을 등록하면 account_link_id 가 발급되고, 작업 제출 때 그 값으로 어떤 자격증명을 쓸지 정합니다.

기관별 자격증명

자격증명기관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.codeVALIDATION_INVALID_FIELD — 본문 값 오류에도 쓰이는 코드입니다. 자격증명이 필요한 작업을 account_link_id 없이 보냈다면, 먼저 등록한 자격증명이 있는지 확인합니다.
error.message문구는 바뀔 수 있어 분기에 쓰지 않습니다.
해결콘솔에서 자격증명을 등록한 뒤 다시 제출합니다.

계좌 자격증명은 한 연동에 계좌가 여러 개일 수 있습니다.

콘솔에서 공동인증서를 한 번 등록하면 같은 인증서를 쓰는 다른 기관에도 함께 연결됩니다.

등록은 콘솔에서 합니다

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

  • 공동인증서는 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

기관 사이트 비밀번호

일부 사업장은 인증서 비밀번호와 별도로 기관 사이트 비밀번호를 요구합니다.

  • 인증서를 등록할 때 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)

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 가 오고, 콘솔 기본정보에서 다시 동의하면 풀립니다.