Ops Cloud — API Reference
마케팅 동의 인증 API
현대해상 포털의 마케팅 동의 본인인증 절차를 외부 시스템에서 연동할 수 있는 REST API입니다. 고객 정보를 전달하면 RPA가 자동으로 SMS 인증을 발송하고, 인증번호 검증까지 처리합니다.
BASE URL
https://ks-rpa-api-auth.nodeplug.com/api/v1/auth
Authentication Flow
1
SMS 발송 요청
POST /request
auth_id 반환
auth_id 반환
2
상태 폴링
GET /{auth_id}/status
2초 간격 반복
2초 간격 반복
3
인증번호 제출
POST /{auth_id}/verify
최종 결과 반환
최종 결과 반환
Step 2 폴링에서 signal == "waiting_for_auth_code" 를 수신하면 사용자에게 인증번호 입력창을 표시하세요.
이후 Step 3에서 인증번호를 제출합니다. 인증번호가 틀린 경우 attempt를 증가시켜 Step 3을 최대 3회까지 재호출할 수 있습니다.
POST
Step 1 — SMS 발송 요청
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
| Field | Type | Description |
|---|---|---|
| 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 발송을 시작합니다."
}
GET
Step 2 — 상태 폴링
Step 2
인증 진행 상태 조회
2초 간격으로 반복 호출하여 RPA 처리 상태를 확인합니다. signal == "waiting_for_auth_code" 수신 시 인증번호 입력창을 표시하세요.
GET
/api/v1/auth/{auth_id}/status
Path Parameters
| Field | Type | Description |
|---|---|---|
| auth_idrequired | string | Step 1에서 받은 auth_id |
Response
| Field | Type | Description |
|---|---|---|
| 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분). 처음부터 다시 시도해주세요."
}
POST
Step 3 — 인증번호 제출
Step 3
인증번호 제출 및 결과 반환
사용자가 입력한 인증번호를 제출합니다. RPA가 VDI에서 인증번호를 입력하고 결과를 확인합니다. 응답까지 최대 60초 소요될 수 있습니다.
POST
/api/v1/auth/{auth_id}/verify
Path Parameters
| Field | Type | Description |
|---|---|---|
| auth_idrequired | string | Step 1에서 받은 auth_id |
Request Body
| Field | Type | Description |
|---|---|---|
| auth_coderequired | string | SMS로 받은 인증번호 6자리. "123456" |
| attemptoptional | integer | 시도 횟수. 기본값 1. 재시도 시 2, 3으로 증가. 최대 3회 |
Response
| Field | Type | Description |
|---|---|---|
| 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 Reference
| 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 | 시스템 오류 | 오류 메시지 표시 |
HTTP Error Codes
400
Bad Request
입력값 유효성 오류.
detail 필드에 구체적인 원인이 담겨 있습니다.
404
Not Found
auth_id를 찾을 수 없습니다. 올바른 auth_id를 사용하세요.
422
Unprocessable Entity
요청 body 형식 오류. JSON 구조 및 필드 타입을 확인하세요.
500
Internal Server Error
서버 내부 오류. RPA 에이전트 상태를 확인하세요.
Integration Example
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회 실패")