인증 - 교통민원24

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

법인 공동인증서로 로그인해 과태료와 범칙금 조회에 쓸 세션을 만듭니다. 인증서는 보관하지 않고 호출할 때 받아 쓰며, 만들어진 세션은 이후 조회가 함께 씁니다.

이 작업은 샌드박스를 지원하지 않습니다. 샌드박스로 보내면 거절되므로 데모나 정식 환경으로 호출합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `efine`이 API 고정값 (기본값) 예시 : efine
action	string	-	Y	호출할 작업입니다. `efine.session.login`이 API 고정값 (기본값) 예시 : efine.session.login
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	business_registration_no	string	Y	로그인할 법인의 사업자등록번호입니다. 붙임표 없이 숫자 10자리만 받고 그 밖의 모양은 거절합니다. 공동인증서와 비밀번호는 이 칸이 아니라 연동에 등록한 인증서에서 가져옵니다
	company_name	string	Y	로그인할 법인의 상호(법인명)입니다. 공백만으로 된 값은 거절하고 앞뒤 공백은 지워 보내며, 인증서에서 읽어 채우지 않으므로 직접 보내야 합니다

bash

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: demo-login-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "efine",
  "action": "efine.session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "business_registration_no": "<필수>",
    "company_name": "<필수>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
provider	string	기관 상품의 식별자입니다. 이 상품에서는 항상 efine 입니다.
env_scope	string	로그인을 실행한 환경입니다. 요청에 지정한 환경이고, 지정하지 않았으면 기본 환경입니다.
account_link_id	string	로그인에 쓴 연동 계정의 ID 입니다.
session_saved	boolean	기관 세션을 저장했는지 여부입니다. 저장하지 못하면 작업이 실패하므로 성공 응답에서는 항상 true 입니다.
login_confirmed_at	string	기관 로그인을 확인한 시각입니다. UTC 기준 ISO 8601 문자열이고 응답의 finished_at(KST)과 시간대가 다릅니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "efine",
    "action": "efine.session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	PROVIDER_AUTH_FAILED	연결된 공동인증서를 확인하지 못했습니다. 인증서를 다시 연결해 주세요.
	INTERNAL_ERROR	지금은 이 상품을 처리할 수 없습니다. 서버 구성 문제로 요청을 실행하지 못했습니다. 서비스문의로 알려 주세요.
	VALIDATION_INVALID_FIELD	사업자등록번호(business_registration_no)는 숫자 열 자리로 보내 주세요.
	VALIDATION_INVALID_FIELD	상호(법인명)를 입력해 주세요.
	VALIDATION_INVALID_FIELD	연결된 공동인증서 정보를 불러오지 못했습니다. 인증서를 다시 연결해 주세요.
	PROVIDER_AUTH_FAILED	연결된 공동인증서의 개인키를 열지 못했습니다. 인증서 비밀번호와 인증서를 다시 연결해 주세요.
	PROVIDER_UPSTREAM_ERROR	지금은 로그인을 진행할 수 없습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	보안 로그인 준비 단계에서 올바르지 않은 응답을 받았습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	로그인 처리가 끝나지 않았습니다. 잠시 후 다시 시도해 주세요.
	PROVIDER_UNAVAILABLE	로그인은 됐지만 세션을 저장하지 못했습니다. 잠시 후 다시 시도해 주세요.
	PROVIDER_UPSTREAM_ERROR	로그인 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.

인증 - 교통민원24

1. 교통민원24 로그인efine.session.login

Request

Response