웹 SDK 백엔드 연동
고객사 서버가 옥토모 API 2개(인증 발급, 최종 확인)를 호출합니다.
인증 발급
POST
https://api.octoverse.kr/octomo/v1/public/sdk/verifications응답을 SDK에 그대로 돌려줍니다.
요청
| 메서드 | URL | 인증 방식 |
|---|---|---|
| POST | https://api.octoverse.kr/octomo/v1/public/sdk/verifications | API Key |
| 이름 | 값 | 필수 여부 |
|---|---|---|
| Authorization | Octomo {API_KEY} | 필수 |
| Content-Type | application/json | 필수 |
| 이름 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| phoneNumber | string | 010으로 시작하는 숫자 11자리. 하이픈 없이 보냅니다 | 필수 |
응답
| 이름 | 타입 | 설명 |
|---|---|---|
| verificationToken | string | 인증 토큰. 최종 확인에 씁니다 |
| verificationCode | string | 사용자가 보낼 문자 본문 |
| receiver | string | 문자를 받을 옥토모 수신번호 |
| expiresAt | number | 문자 확인 기한 (밀리초 Unix time, 발급 후 10분). 최종 확인은 문자 확인 후 10분 안에 하면 됩니다 |
JSON
{
"verificationToken": "Zk3...(43자)",
"verificationCode": "OCTOMO-0123456789ABCDEF0123456789ABCDEF",
"receiver": "16663538",
"expiresAt": 1761900000000
}최종 확인
POST
https://api.octoverse.kr/octomo/v1/public/sdk/verifications/consume업무를 처리하기 직전에 호출합니다. 한도는 차감되지 않고, 같은 토큰으로 재시도하면 같은 응답을 돌려줍니다.
요청
| 메서드 | URL | 인증 방식 |
|---|---|---|
| POST | https://api.octoverse.kr/octomo/v1/public/sdk/verifications/consume | API Key |
| 이름 | 값 | 필수 여부 |
|---|---|---|
| Authorization | Octomo {API_KEY} | 필수 |
| Content-Type | application/json | 필수 |
| 이름 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| verificationToken | string | 발급 응답의 verificationToken | 필수 |
응답
| 이름 | 타입 | 설명 |
|---|---|---|
| status | string | 항상 consumed |
| phoneNumber | string | 인증된 휴대폰 번호 |
| verificationId | string | 인증 1건의 ID. 중복 처리 방지에 씁니다 |
JSON
{
"status": "consumed",
"phoneNumber": "01012345678",
"verificationId": "6745f0..."
}에러 코드
요청이 실패하면 해당 HTTP 상태 코드와 함께 아래 형태의 JSON이 반환됩니다. error 필드는 상황에 따라 생략될 수 있습니다. 분기는 HTTP 상태 코드로 하세요. 5xx와 네트워크 오류는 그대로 재시도할 수 있습니다.
JSON
{
"statusCode": 401,
"message": "Invalid API Key",
"error": "Unauthorized"
}| HTTP 상태 | 발생 원인 | message 예시 |
|---|---|---|
| 400Bad Request | 번호나 토큰의 형식이 올바르지 않음 | phoneNumber must match /^010\d{8}$/ regular expression |
| 401Unauthorized | Authorization 헤더가 없거나 형식(Octomo {API_KEY})이 올바르지 않거나, 잘못되었거나 폐기된 API Key인 경우 | Invalid API Key |
| 403Forbidden | 애플리케이션이 활성(ACTIVE) 상태가 아닌 경우 (구독 중단·정지 등) | 이 애플리케이션은 일시 중단되었습니다. 구독 상태를 확인하세요. |
| 404Not Found | 인증을 찾을 수 없음 (만료 후 정리, 다른 애플리케이션의 토큰). 처음부터 다시 시작합니다 | Verification not found |
| 409Conflict | 아직 문자가 도착하지 않음. 사용자에게 다시 확인을 요청합니다 | Verification pending |
| 410Gone | 발급 후 10분 안에 문자가 확인되지 않았거나, 문자 확인 후 10분 안에 최종 확인하지 않음. 처음부터 다시 시작합니다 | Verification expired |
| 429Too Many Requests | 요청 속도 제한(10초당 100회)을 초과했거나, 플랜별 월 API 호출 한도를 초과한 경우 | 월 API 호출 한도를 초과했습니다. |
| 500Internal Server Error | 서버 내부 오류 또는 일시적인 장애가 발생한 경우 (요청을 다시 시도하거나 지속되면 문의) | Internal server error |
샘플 코드
Node.js
import express from 'express';
const API_KEY = process.env.OCTOMO_API_KEY;
// 예시라서 메모리에 저장합니다. 운영에서는 DB나 Redis에 저장하세요.
const verifications = new Map(); // verificationToken → { phoneNumber }
async function callOctomo(path, body) {
const res = await fetch(`https://api.octoverse.kr/octomo/v1${path}`, {
method: 'POST',
headers: { Authorization: `Octomo ${API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
if (!res.ok) throw Object.assign(new Error(`OCTOMO ${res.status}`), { status: res.status });
return res.json();
}
const app = express();
app.use(express.json());
// 인증 발급: SDK onPhoneSubmit에서 호출합니다.
app.post('/verifications', async (req, res) => {
const { phoneNumber } = req.body;
const issued = await callOctomo('/public/sdk/verifications', { phoneNumber });
verifications.set(issued.verificationToken, { phoneNumber });
res.status(201).json(issued); // 응답을 그대로 SDK에 돌려줍니다
});
// 최종 확인: SDK onComplete에서 호출합니다. 이 결과로만 인증 성공을 판단합니다.
app.post('/verifications/consume', async (req, res) => {
const { verificationToken } = req.body;
const saved = verifications.get(verificationToken);
if (!saved) return res.status(404).json({ message: '인증을 다시 시작해주세요.' });
const result = await callOctomo('/public/sdk/verifications/consume', { verificationToken });
if (result.phoneNumber !== saved.phoneNumber) return res.status(403).json({ message: '번호가 일치하지 않아요.' });
// 여기서 가입 등 업무를 처리합니다. result.verificationId당 한 번만 처리하세요.
res.json({ message: '휴대폰 번호 인증 완료' });
});
app.use((error, req, res, next) => {
res.status(error.status === 409 ? 409 : 500).json({ message: '요청을 처리하지 못했어요.' });
});
app.listen(3000);Java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class OctomoSdkExample {
private static final String BASE_URL = "https://api.octoverse.kr/octomo/v1";
private static final String API_KEY = System.getenv("OCTOMO_API_KEY");
private static final HttpClient CLIENT = HttpClient.newHttpClient();
static String callOctomo(String path, String jsonBody) throws IOException, InterruptedException {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + path))
.header("Authorization", "Octomo " + API_KEY)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
// 발급은 201, 최종 확인은 200이므로 2xx 전체를 성공으로 봅니다
if (response.statusCode() / 100 != 2) throw new IOException("OCTOMO " + response.statusCode());
return response.body();
}
// 인증 발급: 응답 JSON을 그대로 SDK에 돌려줍니다. 토큰과 입력 번호는 DB나 Redis에 저장하세요.
static String issue(String phoneNumber) throws IOException, InterruptedException {
return callOctomo("/public/sdk/verifications", "{\"phoneNumber\":\"" + phoneNumber + "\"}");
}
// 최종 확인: 응답의 phoneNumber를 저장한 번호와 대조하고, verificationId당 한 번만 업무를 처리하세요.
static String consume(String verificationToken) throws IOException, InterruptedException {
return callOctomo("/public/sdk/verifications/consume", "{\"verificationToken\":\"" + verificationToken + "\"}");
}
}Python
import os
import requests
BASE_URL = "https://api.octoverse.kr/octomo/v1"
HEADERS = {"Authorization": f"Octomo {os.environ['OCTOMO_API_KEY']}"}
def call_octomo(path, body):
res = requests.post(f"{BASE_URL}{path}", json=body, headers=HEADERS, timeout=10)
res.raise_for_status() # 분기는 res.status_code로 합니다
return res.json()
# 인증 발급: 응답을 그대로 SDK에 돌려줍니다. 토큰과 입력 번호는 DB나 Redis에 저장하세요.
def issue(phone_number):
return call_octomo("/public/sdk/verifications", {"phoneNumber": phone_number})
# 최종 확인: 응답의 phoneNumber를 저장한 번호와 대조하고, verificationId당 한 번만 업무를 처리하세요.
def consume(verification_token):
return call_octomo("/public/sdk/verifications/consume", {"verificationToken": verification_token})cURL
# 인증 발급
curl -X POST \
'https://api.octoverse.kr/octomo/v1/public/sdk/verifications' \
-H 'Authorization: Octomo {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{ "phoneNumber": "01012345678" }'
# 최종 확인
curl -X POST \
'https://api.octoverse.kr/octomo/v1/public/sdk/verifications/consume' \
-H 'Authorization: Octomo {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{ "verificationToken": "{발급 토큰}" }'