Ops Cloud — API Reference

마케팅 동의 인증 API

현대해상 포털의 마케팅 동의 본인인증 절차를 외부 시스템에서 연동할 수 있는 REST API입니다. 고객 정보를 전달하면 RPA가 자동으로 SMS 인증을 발송하고, 인증번호 검증까지 처리합니다.

Base URL https://ks-rpa-api-auth.nodeplug.com
Auth None (IP whitelist 권장)
Format JSON / UTF-8
BASE URL https://ks-rpa-api-auth.nodeplug.com/api/v1/auth
1
SMS 발송 요청
POST /request
auth_id 반환
2
상태 폴링
GET /{auth_id}/status
2초 간격 반복
3
인증번호 제출
POST /{auth_id}/verify
최종 결과 반환
Step 2 폴링에서 signal == "waiting_for_auth_code" 를 수신하면 사용자에게 인증번호 입력창을 표시하세요. 이후 Step 3에서 인증번호를 제출합니다. 인증번호가 틀린 경우 attempt를 증가시켜 Step 3을 최대 3회까지 재호출할 수 있습니다.
Step 1
마케팅 동의 인증 SMS 발송
고객 정보를 전달하면 RPA가 현대해상 포털에서 SMS 인증번호를 발송합니다. 응답으로 받은 auth_id를 Step 2, 3에서 사용하세요.
POST /api/v1/auth/request
Request Body
Field Type Description
resident_numberrequired string 주민번호 13자리 (숫자만, 하이픈 없이)
"9001011234567"
phone_numberrequired string 휴대폰번호 11자리 (숫자만, 하이픈 없이)
"01012345678"
telecomrequired string 이동통신사.
일반: "SKT" | "KT" | "LGU+"
알뜰폰: "SKT알뜰" | "KT알뜰" | "LGU+알뜰"
기타: "모름"
Response
FieldTypeDescription
auth_id string 인증 세션 고유 ID. 이후 모든 요청에 사용
status string 항상 "pending" 반환
message string 처리 안내 메시지
JSON // POST /api/v1/auth/request { "resident_number": "9001011234567", "phone_number": "01012345678", "telecom": "KT" }
JSON // HTTP 200 OK { "auth_id": "job-3938bee6-5fc6-47f8-8b47-57ccef6ec58a", "status": "pending", "message": "인증 요청이 접수되었습니다. RPA가 SMS 발송을 시작합니다." }
Step 2
인증 진행 상태 조회
2초 간격으로 반복 호출하여 RPA 처리 상태를 확인합니다. signal == "waiting_for_auth_code" 수신 시 인증번호 입력창을 표시하세요.
GET /api/v1/auth/{auth_id}/status
Path Parameters
FieldTypeDescription
auth_idrequired string Step 1에서 받은 auth_id
Response
FieldTypeDescription
signal string 현재 상태 신호. Signal Reference 참조
poll_again boolean false이면 폴링 중단
ready_for_auth boolean true이면 인증번호 입력창 표시 타이밍
elapsed_seconds integer 요청 생성 후 경과 시간(초). 420초(7분) 초과 시 timeout
message string 사용자에게 표시할 안내 메시지
agent_id string | null 담당 RPA 에이전트 ID. 내부 라우팅용 — 외부 연동 시 무시해도 됩니다
JSON // RPA가 처리 중 — 2초 후 재폴링 { "auth_id": "job-3938bee6-...", "signal": "processing", "poll_again": true, "ready_for_auth": false, "elapsed_seconds": 8, "message": "RPA가 처리 중입니다. 잠시 기다려주세요..." }
JSON // SMS 발송 완료 — 인증번호 입력창 표시 { "auth_id": "job-3938bee6-...", "signal": "waiting_for_auth_code", "poll_again": false, "ready_for_auth": true, "elapsed_seconds": 28, "message": "인증번호가 발송되었습니다. SMS를 확인하고 인증번호를 입력해주세요." }
JSON // 7분 초과 — 처음부터 재시도 { "auth_id": "job-3938bee6-...", "signal": "timeout", "poll_again": false, "ready_for_auth": false, "elapsed_seconds": 421, "message": "인증 시간이 만료되었습니다(7분). 처음부터 다시 시도해주세요." }
Step 3
인증번호 제출 및 결과 반환
사용자가 입력한 인증번호를 제출합니다. RPA가 VDI에서 인증번호를 입력하고 결과를 확인합니다. 응답까지 최대 60초 소요될 수 있습니다.
POST /api/v1/auth/{auth_id}/verify
Path Parameters
FieldTypeDescription
auth_idrequired string Step 1에서 받은 auth_id
Request Body
FieldTypeDescription
auth_coderequired string SMS로 받은 인증번호 6자리. "123456"
attemptoptional integer 시도 횟수. 기본값 1. 재시도 시 2, 3으로 증가. 최대 3회
Response
FieldTypeDescription
status string "success" | "auth_wrong" | "auth_max_retries" | "error"
message string 처리 결과 메시지
attempt integer 요청한 시도 횟수 그대로 반환
인증번호가 틀린 경우(auth_wrong) attempt를 1 증가시켜 Step 3을 재호출하세요. 3회 실패(auth_max_retries) 시 해당 auth_id는 사용 불가하며 Step 1부터 다시 시작해야 합니다.
JSON // 인증 성공 { "status": "success", "message": "본인인증이 완료되었습니다.", "attempt": 1 }
JSON // 인증번호 불일치 — attempt 증가 후 재시도 { "status": "auth_wrong", "message": "인증번호가 일치하지 않습니다. 다시 입력해주세요. (1/3회)", "attempt": 1 }
JSON // 3회 초과 실패 — Step 1부터 재시작 { "status": "auth_max_retries", "message": "3회 인증 실패 - 처음부터 다시 시도해주세요", "attempt": 3 }
Signal Endpoint Description Action
processing GET /status RPA가 SMS 발송 작업 중 2초 후 재폴링
waiting_for_auth_code GET /status SMS 발송 완료, 인증번호 대기 중 입력창 표시
completed GET /status 인증 완료 (정상 종료) 완료 처리
timeout GET /status 7분 인증 시간 초과 Step 1 재시작
already_consented GET /status 인증유효기간 내 재동의 제한 (이미 동의 완료된 고객) 안내 메시지 표시
failed GET /status RPA 처리 오류 오류 메시지 표시
success POST /verify 인증번호 일치, 인증 성공 완료 처리
auth_wrong POST /verify 인증번호 불일치 attempt+1 재시도
auth_max_retries POST /verify 3회 연속 실패 Step 1 재시작
error POST /verify 시스템 오류 오류 메시지 표시
400
Bad Request 입력값 유효성 오류. detail 필드에 구체적인 원인이 담겨 있습니다.
404
Not Found auth_id를 찾을 수 없습니다. 올바른 auth_id를 사용하세요.
422
Unprocessable Entity 요청 body 형식 오류. JSON 구조 및 필드 타입을 확인하세요.
500
Internal Server Error 서버 내부 오류. RPA 에이전트 상태를 확인하세요.
JavaScript const BASE = 'https://ks-rpa-api-auth.nodeplug.com/api/v1/auth'; async function runAuth(residentNo, phoneNo, telecom, authCodeFn) { // Step 1 — SMS 발송 요청 const r1 = await fetch(`${BASE}/request`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ resident_number: residentNo, phone_number: phoneNo, telecom: telecom, }), }); const { auth_id } = await r1.json(); // Step 2 — SMS 발송 완료까지 폴링 let signal; do { await new Promise(r => setTimeout(r, 2000)); const r2 = await fetch(`${BASE}/${auth_id}/status`); const data = await r2.json(); signal = data.signal; if (!data.poll_again) break; } while (true); if (signal !== 'waiting_for_auth_code') throw new Error(signal); // Step 3 — 인증번호 제출 (최대 3회) for (let attempt = 1; attempt <= 3; attempt++) { const authCode = await authCodeFn(); // 사용자 입력 대기 const r3 = await fetch(`${BASE}/${auth_id}/verify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ auth_code: authCode, attempt }), }); const result = await r3.json(); if (result.status === 'success') return result; if (result.status === 'auth_max_retries') throw new Error('3회 실패'); } }
Python import time, requests BASE = "https://ks-rpa-api-auth.nodeplug.com/api/v1/auth" def run_auth(resident_no, phone_no, telecom, get_code_fn): # Step 1 — SMS 발송 요청 r1 = requests.post(f"{BASE}/request", json={ "resident_number": resident_no, "phone_number": phone_no, "telecom": telecom, }) auth_id = r1.json()["auth_id"] # Step 2 — SMS 발송 완료까지 폴링 while True: time.sleep(2) r2 = requests.get(f"{BASE}/{auth_id}/status") data = r2.json() if not data["poll_again"]: break if data["signal"] != "waiting_for_auth_code": raise RuntimeError(data["signal"]) # Step 3 — 인증번호 제출 (최대 3회) for attempt in range(1, 4): code = get_code_fn() # 사용자 입력 수신 r3 = requests.post(f"{BASE}/{auth_id}/verify", json={"auth_code": code, "attempt": attempt}) result = r3.json() if result["status"] == "success": return result if result["status"] == "auth_max_retries": raise RuntimeError("3회 실패")