문자 메시지 조회 API

문자 메시지 조회 API는 사용자가 옥토모 대표번호 1666-3538로 보낸 문자가 도착했는지 확인합니다. 휴대폰 번호와 문자 내용을 보내면 최근 5분(기본값) 안에 그 문자가 들어왔는지를 exists(true/false)로 답합니다.

POSThttps://api.octoverse.kr/octomo/v1/public/message/exists

최근 일정 시간(기본 5분) 동안 받은 문자 메시지 인증 요청 여부를 조회합니다. 조회 범위는 withinMinutes로 최대 60분까지 조정할 수 있습니다.

요청

기본 정보
메서드	URL	인증 방식
POST	https://api.octoverse.kr/octomo/v1/public/message/exists	API Key

요청 헤더
이름	값	필수 여부
Authorization	`Octomo {API_KEY}`	필수
Content-Type	`application/json`	필수
Accept	`application/json`	필수

요청 본문 (Request Body, JSON)
이름	타입	설명	필수 여부	기본값
mobileNum	string	인증 요청 여부를 확인할 휴대폰 번호 (예: 01012345678)	필수	없음
text	string	사용자의 휴대폰에서 전송된 문자 메시지 원문 데이터 값 (예: 3538)	필수	없음
withinMinutes	integer	최근 몇 분 이내에 들어온 메시지를 조회할지 지정합니다 (분 단위, 최대 60)	선택	5

withinMinutes는 선택값으로, 생략하면 기본값인 5분이 적용됩니다. 지정할 수 있는 범위는 1분에서 60분까지이며, 이 범위를 벗어난 값은 60으로 보정되지 않고 400 오류로 거절됩니다.

응답

응답 본문 (201 Created)
이름	타입	설명
exists	boolean	조회 범위(withinMinutes, 기본 5분) 이내에 인증 요청이 존재하면 true, 없으면 false

에러 코드

요청이 실패하면 해당 HTTP 상태 코드와 함께 아래 형태의 JSON이 반환됩니다. error 필드는 상황에 따라 생략될 수 있습니다.

JSON

{
  "statusCode": 401,
  "message": "Invalid API Key",
  "error": "Unauthorized"
}

문자 메시지 조회 API 에러 코드
HTTP 상태	발생 원인	message 예시
400Bad Request	요청 본문 검증 실패 — mobileNum이 010으로 시작하는 11자리 숫자가 아니거나, text가 비어 있거나, withinMinutes가 1~60 범위의 정수가 아니거나, 허용되지 않은 필드가 포함된 경우	`mobileNum은 010으로 시작하는 11자리 숫자여야 합니다.`
401Unauthorized	Authorization 헤더가 없거나 형식(Octomo {API_KEY})이 올바르지 않거나, 잘못되었거나 폐기된 API Key인 경우	`Invalid API Key`
403Forbidden	애플리케이션이 활성(ACTIVE) 상태가 아닌 경우 (구독 중단·정지 등)	`이 애플리케이션은 일시 중단되었습니다. 구독 상태를 확인하세요.`
404Not Found	API Key에 해당하는 사용자 또는 애플리케이션을 찾을 수 없는 경우	`존재하지 않는 유저입니다.`
429Too Many Requests	요청 속도 제한(10초당 100회)을 초과했거나, 플랜별 월 API 호출 한도를 초과한 경우	`월 API 호출 한도를 초과했습니다.`
500Internal Server Error	서버 내부 오류 또는 일시적인 장애가 발생한 경우 (요청을 다시 시도하거나 지속되면 문의)	`Internal server error`

샘플 코드

Node.js

import fetch from "node-fetch";


const url = "https://api.octoverse.kr/octomo/v1/public/message/exists";
const API_KEY = process.env.OCTOMO_API_KEY;


async function checkMobileVerified(mobileNum, text) {
  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "Content-Type": "application/json",
      "Authorization": `Octomo ${API_KEY}`,
    },
    body: JSON.stringify({ mobileNum, text }),
  });


  console.log(await res.json());
}


checkMobileVerified("01012345678", "3538");

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 OctomoExample {
  public static void main(String[] args) throws IOException, InterruptedException {
    String url = "https://api.octoverse.kr/octomo/v1/public/message/exists";
    String apiKey = System.getenv("OCTOMO_API_KEY");


    String jsonBody = "{\"mobileNum\":\"01012345678\",\"text\":\"3538\"}";


    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("Authorization", "Octomo " + apiKey)
        .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
        .build();


    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());


    System.out.println("HTTP " + response.statusCode());
    System.out.println(response.body());
  }
}

Python

import os
import requests


url = "https://api.octoverse.kr/octomo/v1/public/message/exists"
api_key = os.environ.get("OCTOMO_API_KEY")


res = requests.post(
    url,
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Octomo {api_key}",
    },
    json={"mobileNum": "01012345678", "text": "3538"},
)


print(res.status_code)
print(res.json())

cURL

curl -X POST \
  'https://api.octoverse.kr/octomo/v1/public/message/exists' \
  -H 'Accept: application/json' \
  -H 'Authorization: Octomo {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{ "mobileNum": "01012345678", "text": "3538" }'

API Key가 있다면 테스트 콘솔에서 직접 호출해 보세요 →