API 문서 v3.9 — IONE NETWORKS

API 개요

아이원네트웍스 API v3.9는 RESTful 방식으로 SMS, LMS, MMS, 카카오 알림톡/친구톡, RCS 등 다양한 메시징 채널을 단일 인터페이스로 발송할 수 있는 통합 메시징 API입니다.

Base URL

https://api.ionenet.kr/v3.9

인증 방식

모든 API 요청에는 Authorization 헤더에 Bearer 토큰을 포함해야 합니다. 토큰은 계정 발급 시 제공되며, 만료 시 갱신 API를 통해 재발급합니다.

POST /v3.9/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

공통 응답 형식

{
  "code": "1000",
  "message": "성공",
  "data": { ... }
}

파라미터	타입	필수	설명
code	String	필수	응답 코드 (1000: 성공)
message	String	필수	응답 메시지
data	Object	선택	응답 데이터

SMS / LMS / MMS 발송

단문(SMS), 장문(LMS), 멀티미디어(MMS) 메시지를 발송합니다. 메시지 유형은 msg_type 파라미터로 구분합니다.

POST /v3.9/message/send

파라미터	타입	필수	설명
msg_type	String	필수	메시지 유형 (SMS, LMS, MMS)
from	String	필수	발신번호 (사전 등록 필수)
to	String	필수	수신번호 ('-' 제외, 예: 01012345678)
subject	String	선택	제목 (LMS/MMS 시 사용)
content	String	필수	메시지 본문
image	String	선택	이미지 URL (MMS 시 필수, 최대 3장)
ref_key	String	선택	고객 참조 키 (중복 방지)
send_time	String	선택	예약발송 시간 (yyyyMMddHHmmss)

요청 예시

{
  "msg_type": "SMS",
  "from": "15881234",
  "to": "01012345678",
  "content": "안녕하세요. 아이원네트웍스입니다."
}

응답 예시

{
  "code": "1000",
  "message": "성공",
  "data": {
    "msg_id": "M20260223150000001",
    "ref_key": null
  }
}

카카오 알림톡 / 친구톡

카카오톡 채널을 통해 알림톡(정보성) 및 친구톡(광고성) 메시지를 발송합니다.

POST /v3.9/kakao/send

파라미터	타입	필수	설명
kakao_type	String	필수	발송 유형 (AT: 알림톡, FT: 친구톡)
sender_key	String	필수	카카오 발신 프로필 키
template_code	String	선택	알림톡 템플릿 코드 (AT 필수)
to	String	필수	수신번호
content	String	필수	메시지 본문 (템플릿 변수 치환)
button	Array	선택	버튼 목록
failover	Object	선택	발송 실패 시 대체 발송 (SMS/LMS)

요청 예시 (알림톡)

{
  "kakao_type": "AT",
  "sender_key": "abcdef1234567890",
  "template_code": "IONE_ORDER_01",
  "to": "01012345678",
  "content": "주문이 완료되었습니다.\n주문번호: #{orderNo}",
  "button": [
    {
      "type": "WL",
      "name": "주문 확인",
      "url_mobile": "https://example.com/order"
    }
  ],
  "failover": {
    "msg_type": "SMS",
    "content": "[아이원네트웍스] 주문이 완료되었습니다."
  }
}

RCS 메시지

RCS(Rich Communication Services) 메시지를 발송합니다. 리치카드, 캐러셀, 템플릿 등 다양한 형태를 지원합니다.

POST /v3.9/rcs/send

파라미터	타입	필수	설명
rcs_type	String	필수	RCS 유형 (STANDALONE, CAROUSEL, TEMPLATE)
from	String	필수	발신번호
to	String	필수	수신번호
brand_key	String	필수	RCS 브랜드 키
body	Object	필수	메시지 본문 (텍스트, 이미지, 버튼)
failover	Object	선택	대체 발송 설정

요청 예시

{
  "rcs_type": "STANDALONE",
  "from": "15881234",
  "to": "01012345678",
  "brand_key": "BR.abcdef123456",
  "body": {
    "title": "아이원네트웍스 안내",
    "description": "새로운 메시징 서비스를 확인하세요.",
    "media": "https://example.com/image.jpg",
    "buttons": [
      { "type": "URL", "label": "자세히 보기", "url": "https://ionenet.kr" }
    ]
  }
}

발송 결과 조회

발송된 메시지의 전송 결과를 조회합니다.

GET /v3.9/report/{msg_id}

파라미터	타입	필수	설명
msg_id	String	필수	메시지 ID (Path Parameter)

응답 예시

{
  "code": "1000",
  "message": "성공",
  "data": {
    "msg_id": "M20260223150000001",
    "status": "DELIVERED",
    "sent_at": "2026-02-23T15:00:00+09:00",
    "delivered_at": "2026-02-23T15:00:02+09:00",
    "carrier": "SKT",
    "error_code": null
  }
}

콜백 방식

콜백 URL을 사전 등록하면 발송 결과가 실시간으로 POST 요청됩니다.

잔액 조회

현재 계정의 잔액 및 사용량 정보를 조회합니다.

GET /v3.9/balance

응답 예시

{
  "code": "1000",
  "message": "성공",
  "data": {
    "balance": 1250000,
    "currency": "KRW",
    "monthly_usage": {
      "sms": 45200,
      "lms": 12300,
      "mms": 3400,
      "kakao_at": 28900,
      "kakao_ft": 5600,
      "rcs": 8100
    }
  }
}

발신번호 관리

등록된 발신번호 목록을 조회합니다.

GET /v3.9/sender

응답 예시

{
  "code": "1000",
  "message": "성공",
  "data": {
    "senders": [
      {
        "number": "15881234",
        "type": "대표번호",
        "status": "ACTIVE",
        "registered_at": "2024-01-15"
      },
      {
        "number": "021234567",
        "type": "일반번호",
        "status": "ACTIVE",
        "registered_at": "2025-06-20"
      }
    ]
  }
}

에러 코드

API 응답에 포함되는 주요 에러 코드입니다.

코드	메시지	설명
1000	성공	정상 처리
2000	인증 실패	토큰이 만료되었거나 유효하지 않음
2001	권한 부족	해당 API 사용 권한이 없음
3000	파라미터 오류	필수 파라미터 누락 또는 형식 오류
3001	발신번호 미등록	사전 등록되지 않은 발신번호
3002	수신번호 오류	유효하지 않은 수신번호 형식
4000	잔액 부족	충전 잔액이 부족함
4001	발송 한도 초과	일일/월별 발송 한도 초과
5000	서버 오류	내부 서버 오류, 재시도 필요
5001	서비스 점검	시스템 점검 중