용어
가이드와 콘솔에서 쓰는 말을 한 곳에 모았습니다.
키와 인증
| 용어 | 뜻 |
|---|---|
| API 키 | 콘솔에서 발급하는 client_id 와 client_secret 한 쌍입니다. |
| client_id | 키를 가리키는 공개 식별자입니다. cli_ 로 시작합니다. |
| client_secret | 키의 비밀 값입니다. csk_ 로 시작하고 발급 직후 한 번만 보입니다. |
| Basic 인증 | client_id:client_secret 을 Base64 로 인코딩해 Authorization 헤더에 넣는 방식입니다. |
환경
| 용어 | 뜻 |
|---|---|
| 환경(env_scope) | 요청을 어디서 실행할지 정하는 값입니다. X-Env-Scope 헤더로 보냅니다. |
| 샌드박스(sandbox) | 실제 기관을 부르지 않고 모의 응답을 주는 환경입니다. |
| 데모(real_test) | 실제 기관에 접속하는 시험 환경입니다. 하루 100 사용 토큰까지 쓸 수 있습니다. |
| 정식(production) | 서비스 운영 환경입니다. 유료 플랜에서 쓸 수 있습니다. |
작업
| 용어 | 뜻 |
|---|---|
| 작업(Job) | 기관 호출 한 건입니다. 제출하면 아이디를 받고, 끝나면 결과를 가져옵니다. |
| job_id | 작업 식별자입니다. job_ 으로 시작합니다. |
| provider | 데이터를 가져올 기관입니다. 현재 홈택스 · 국민연금공단 · 국민건강보험공단 · 4대보험 · 고용24 · 근로복지공단 · KB국민카드 · 신한은행 · IBK기업은행 · KB국민은행 · 우리은행 · Google 마케팅 · 공공데이터 을(를) 다룹니다. |
| action | 어떤 업무를 실행할지 가리키는 값입니다. 예: hometax.etax.invoice.search_list |
| params | 그 작업에 필요한 값입니다. 필요한 항목은 작업마다 다릅니다. |
| encrypted_fields | params 중 민감한 값을 암호화해 보내는 자리입니다. |
| 폴링 | 작업이 끝났는지 상태를 주기적으로 확인하는 방식입니다. |
| Idempotency-Key | 같은 요청을 다시 보낼 때 작업이 두 번 생기지 않게 하는 키입니다. |
자격증명
| 용어 | 뜻 |
|---|---|
| 자격증명 | 기관에 로그인할 때 쓰는 공동인증서나 기관 아이디·비밀번호입니다. 구글은 계정 연결 동의(OAuth)로 대신합니다. |
| 공동인증서 | 기관 로그인에 쓰는 인증서입니다. 예전에는 공인인증서라고 불렀습니다. |
| 연동 ID(account_link_id) | 등록한 자격증명 하나를 가리키는 UUID 입니다. 비밀번호가 아닙니다. |
| 대표 자격증명 | 같은 기관에 여러 개를 등록했을 때 기본으로 쓰는 것입니다. |
| 공개키 | 민감한 값을 암호화할 때 쓰는 서버 공개키입니다. GET /v1/crypto/public-key 로 받습니다. |
기관 용어
| 용어 | 뜻 |
|---|---|
| EDI | 기관과 자료를 주고받는 전자문서 창구입니다. 건강보험·국민연금 업무에서 씁니다. |
| 사업장관리번호 | 기관이 사업장을 구분하는 번호입니다. 기관마다 부르는 이름이 다릅니다. |
| 정보연계센터 | 4대보험 업무를 한곳에서 처리하는 포털입니다. |
AI 연동
| 용어 | 뜻 |
|---|---|
| MCP | AI 앱이 외부 도구를 부르는 표준 방식입니다. XBOSS 는 /mcp 주소로 제공합니다. |
| 도구(tool) | MCP 에서 AI 가 부를 수 있는 기능 하나입니다. XBOSS 의 action 과 짝을 이룹니다. |