API 소개 및 요청방법문자메시지 조회API 주요 에러 코드 목록
API 소개 및 요청방법
API를 요청하는 방법과 제한 사항을 확인
옥토모 API는 옥토모의 대표전화(1666-3538)에 전송 한 문자메시지를 무료로 조회하고 다양한 어플리케이션에 활용할 수 있도록 제공하는 서비스입니다.
API를 요청하기 위해서는 먼저 API Key 발급을 받아야 합니다.
[옥토모 웹사이트 > 로그인 > 마이페이지]에서 서비스를 등록하고 발급을 받을 수 있습니다.
API Key 확인 하러 가기
API 요청하기
API는 POST method로 구성되어 있고, 아래와 같은 방식으로 호출이 가능합니다.
cURL
curl -X 'POST' \
'https://api.octoverse.kr/octomo/v1/message' \
-H 'accept: application/json' \
-H 'x-octomo-token: t4NC1xDPBfRMspCnR4PtlZk0CjfhtnoQQR72JdDmzuMfyNNY...' \
-H 'content-type: application/json' \
-d '{
"payload": "eyJtb2JpbGUiOiAiMDEwMTIzNDU2NzgifQ",
"signature": "ad3f6751fcaefef6fca86ca403487a348bf4939412a2de65..."
}'
API 요청을 위한 준비
발급 받은 Secret Key와 API Key를 이용해 옥토모 API 사용이 가능합니다.
Python
import base64
import hashlib
import hmac
import json
import requests
SECRET = bytes('SecretKeySampleOctoverse', 'utf-8')
APIKEY = 't4NC1xDPBfRMspCnR4PtlZk0CjfhtnoQQR72JdDmzuMfyNNY...'
req = { 'mobile': '01012345678' }
payload = base64.b64encode(bytes(json.dumps(req), 'utf-8'))
print(payload)
print(payload.decode('utf-8'))
signature = hmac.new(SECRET, payload, hashlib.sha512).hexdigest()
print(signature)
url = 'https://api.octoverse.kr/octomo/v1/message'
res = requests.post(url, headers={'x-octomo-token': APIKEY}, json={'payload': payload.decode('utf-8'), 'signature': signature})
print(res)
  • HTTP Method: POST 메서드로 구성되어 있습니다.
  • HTTP Content-Type: 콘텐트 타입은 json입니다. 'application/json'
  • HTTP Header: x-octomo-token에 발급받은 API Key를 입력해야 하며, 이 값은 모든 요청에서 반드시 필요합니다.
    • Payload 생성하기
    요청할 객체를 JSON 문자열로 변환 후, Base64 encode 합니다.
    Python
    import base64
    import json
    req = { 'mobile': '01012345678', 'recv': '16663538' }
    payload = base64.b64encode(bytes(json.dumps(req), 'utf-8'))
    print(payload)
    print(payload.decode('utf-8'))
    Signature 생성하기
    생성한 payload와 발급 받은 Secret Key를 이용하여, SHA512 알고리즘을 통한 해시 기반 메시지 인증 코드(HMAC-SHA512)를 생성합니다.
    Python
    import hashlib
    import hmac
    SECRET = bytes('SecretKeySampleOctoverse', 'utf-8')
    signature = hmac.new(SECRET, payload, hashlib.sha512).hexdigest()
    print(signature)
    HTTP Request
    요청에 필요한 객체를 이용해 만든 payload, signature를 JSON body로 설정하고 발급 받은 API Key를 x-octomo-token에 설정합니다.
    Python
    import requests
    APIKEY = 't4NC1xDPBfRMspCnR4PtlZk0CjfhtnoQQR72JdDmzuMfyNNY...'
    url = 'https://api.octoverse.kr/octomo/v1/message'
    res = requests.post(url, headers={'x-octomo-token': APIKEY}, json={'payload': payload.decode('utf-8'), 'signature': signature})
    print(res)
    문자메시지 조회
    POST
    https://api.octoverse.kr/octomo/v1/message
    메시지에 서비스 명이 포함 된 최근 5분 동안 받은 메시지 리스트를 조회합니다.
    예) 서비스명: octomo, 문자메시지: [octomo] 3538
    Request Header
    HeadersRequired/OptionalDescription
    x-octomo-tokenrequired사용자의 API Key
    Payload
    FieldTypeRequired/OptionalDescription
    mobilestringrequired문자 메시지를 조회할 휴대폰 번호, 예) 01012345678
    recvstringoptional문자 메시지를 수신한 대표번호, 예) 16663538
    * 해당 번호는 옥토모에 등록 되어 있어야 합니다.
    Request Body
    FieldRequired/OptionalDescription
    payloadrequiredbase64 string (JSON string (payload object))
    signaturerequiredHMAC(payload, Secret Key, SHA512).hexdigest()
    API 주요 에러 코드 목록
    개요
    API 요청값이 유효하지 않거나 처리 중 오류가 발생한 경우, HTTP 상태 코드와 함께 다음과 같은 형태의 JSON body가 리턴됩니다.
    { "error": "<오류에 대한 설명>" }
    주요 오류 코드는 다음과 같습니다.
    400 Bad Request
    클라이언트의 잘못된 요청으로 서버가 요청을 처리할 수 없거나 처리하지 않습니다.
    에러 메시지설명
    invalid payloadpayload가 올바르지 않습니다.
    invalid signaturesignature가 올바르지 않습니다.
    required parameter (?) in payload is not found.파싱 된 payload에 (?) 항목이 없습니다.
    401 Unauthorized
    클라이언트는 요청된 응답을 얻기 위해서는 인증을 받아야 합니다.
    에러 메시지설명
    access token is requiredhttp 헤더에 [x-octomo-token] 값이 없습니다.
    invalid tokentoken 값이 올바르지 않습니다.
    invalid hashhash 값이 올바르지 않습니다.
    authentication time expired인증 유효기간이 끝났습니다. 재인증을 받아야 합니다.
    octoverse

    대표 김종민

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

    서울 영등포구 국회대로 36길 6-1

    help@octoverse.kr