메인 콘텐츠로 바로가기

웹 SDK 백엔드 연동

고객사 서버가 옥토모 API 2개(인증 발급, 최종 확인)를 호출합니다.

인증 발급

POSThttps://api.octoverse.kr/octomo/v1/public/sdk/verifications

응답을 SDK에 그대로 돌려줍니다.

요청

기본 정보
메서드URL인증 방식
POSThttps://api.octoverse.kr/octomo/v1/public/sdk/verificationsAPI Key
요청 헤더
이름값필수 여부
AuthorizationOctomo {API_KEY}필수
Content-Typeapplication/json필수
요청 본문 (Request Body, JSON)
이름타입설명필수 여부
phoneNumberstring010으로 시작하는 숫자 11자리. 하이픈 없이 보냅니다필수

응답

응답 본문 (201 Created)
이름타입설명
verificationTokenstring인증 토큰. 최종 확인에 씁니다
verificationCodestring사용자가 보낼 문자 본문
receiverstring문자를 받을 옥토모 수신번호
expiresAtnumber문자 확인 기한 (밀리초 Unix time, 발급 후 10분). 최종 확인은 문자 확인 후 10분 안에 하면 됩니다
JSON
{
  "verificationToken": "Zk3...(43자)",
  "verificationCode": "OCTOMO-0123456789ABCDEF0123456789ABCDEF",
  "receiver": "16663538",
  "expiresAt": 1761900000000
}

최종 확인

POSThttps://api.octoverse.kr/octomo/v1/public/sdk/verifications/consume

업무를 처리하기 직전에 호출합니다. 한도는 차감되지 않고, 같은 토큰으로 재시도하면 같은 응답을 돌려줍니다.

요청

기본 정보
메서드URL인증 방식
POSThttps://api.octoverse.kr/octomo/v1/public/sdk/verifications/consumeAPI Key
요청 헤더
이름값필수 여부
AuthorizationOctomo {API_KEY}필수
Content-Typeapplication/json필수
요청 본문 (Request Body, JSON)
이름타입설명필수 여부
verificationTokenstring발급 응답의 verificationToken필수

응답

응답 본문 (200 OK)
이름타입설명
statusstring항상 consumed
phoneNumberstring인증된 휴대폰 번호
verificationIdstring인증 1건의 ID. 중복 처리 방지에 씁니다
JSON
{
  "status": "consumed",
  "phoneNumber": "01012345678",
  "verificationId": "6745f0..."
}

에러 코드

요청이 실패하면 해당 HTTP 상태 코드와 함께 아래 형태의 JSON이 반환됩니다. error 필드는 상황에 따라 생략될 수 있습니다. 분기는 HTTP 상태 코드로 하세요. 5xx와 네트워크 오류는 그대로 재시도할 수 있습니다.

JSON
{
  "statusCode": 401,
  "message": "Invalid API Key",
  "error": "Unauthorized"
}
인증 발급·최종 확인 API 에러 코드
HTTP 상태발생 원인message 예시
400Bad Request번호나 토큰의 형식이 올바르지 않음phoneNumber must match /^010\d{8}$/ regular expression
401UnauthorizedAuthorization 헤더가 없거나 형식(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);
OCTOMO

주식회사 옥토버스

대표 김종민

사업자 등록번호 803-88-02517

서울특별시 영등포구 국회대로36길 6-1, 2층 디599호

고객센터 1666-3538

이메일 hercules@octoverse.kr