본문으로 건너뛰기

소개

쿨에스엠에스의 REST API Reference 내용을 담고 있습니다.

참고 REST는 Representational State Transfer의 약자로 API 연동 규격을 명확하게 정의되고 쉽게 구현 할 수 있습니다. https://ko.wikipedia.org/wiki/REST

쿨에스엠에스 SMS REST API 서버로 Request를 보내기 위해서 인증을 거쳐야 합니다.
API Key 를 이용한 방법과 소셜로그인으로 불리우는 OAuth 2.0 을 지원하고 있습니다.

Resource URL 구성

https://api.coolsms.co.kr/<ServiceName>/<Version>/<ResourcePath>

<ServiceName>

  • 메시지
  • 잔액
  • 이미지

<Version>

  • 서비스 버전

<ResourcePath>

  • 필요시 특정 리소스 경로를 나타냅니다

API 요청

API Request 시 파라메터 값과 Response 의 데이터 값은 JSON 형식으로 합니다. 모든 Request 에 Content-type 을 application/json 으로 설정하여 주세요.

Operator

Operator(이하 오퍼레이터)는 COOLSMS에서 제공하는 고급 기능으로써 특정 정보를 검색하고자 URL Query Parameter를 사용할 때 자세하고 질 높은 Query를 작성할 수 있도록 도와줍니다. 또한 API를 통해 COOLSMS 서비스를 이용하고자 할 경우 숙지해야 될 기능입니다.

오퍼레이터의 종류와 예시

종류

오퍼레이터는 eq, ne, like, gte, lte, gt, lt 총 7가지 종류가 있습니다.

이름설명
어떤 오퍼레이터도 사용하지 않았다면 eq를 사용했을 때와 같은 일을 수행합니다.
eqEqual의 약자입니다. 값과 동일한 대상을 찾을 때 사용됩니다.
neNot Equal의 약자입니다. 값과 동일하지 않은 대상을 찾을 때 사용됩니다.
like값을 포함하는 대상을 찾을 때 사용됩니다.
gte값을 포함하거나 높은 대상을 찾을 때 사용됩니다. 대부분은 날짜를 검색할 때 사용됩니다.
lte값을 포함하거나 낮은 대상을 찾을 사용됩니다. 대부분은 날짜를 검색할 때 사용됩니다.
gt값보다 높은 대상을 찾을 사용됩니다. 대부분은 날짜를 검색할 때 사용됩니다.
lt값보다 낮은 대상을 찾을 사용됩니다. 대부분은 날짜를 검색할 때 사용됩니다.
in값과 동일한 대상 여러개를 찾을 때 사용됩니다.
위험

eq 오퍼레이터가 사용 불가능 하다면 아무 오퍼레이터를 쓰지 않는 것도 불가능합니다.

예시

https://api.coolsms.co.kr/getList?title[like]=걸리버&title[ne]=걸리버여행기&author=스위프트&dateCreated[gte]=2017-06-24&dateCreated[lt]=2017-07-12&dateUpdated[gt]=2018-02-19&dateUpdated[lte]=2018-03-20&

위의 내용을 요약하자면 아래와 같습니다.

URL & QueryOperator설명
https://api.coolsms.co.kr/getList특정 목록을 불러온다
title[like]=걸리버like'title'은 '걸리버'를 포함한다
title[ne]=걸리버여행기ne'title'은 '걸리버여행기'가 아니다
author=스위프트eq'author'는 '스위프트'이다.
dateCreated[gte]=2017-06-24gte'dateCreated'는 2017년 6월 24일 이후 (당일 포함)
dateCreated[lt]=2017-07-12lt'dateCreated'는 2017년 7월 12일 이전 (당일 미포함)
dateUpdated[gt]=2018-02-19gt'dateUpdated'는 2018년 2월 19일 이후 (당일 미포함)
dateUpdated[lte]=2018-03-20lte'dateUpdated'는 2018년 3월 20일 이전 (당일 포함)
type[in]=["SMS", "LMS"]in'type'이 SMS 혹은 LMS인 경우

오류 핸들링

Response 의 HTTP Status Code 값이 200 일 때 API 는 정상적으로 호출되었고 Response 의 Body 에 적절한 데이터가 리턴됩니다.

HTTP Status Code 200 이외의 값의 경우 오류로써 보통의 경우 errorCode 와 errorMessage 이 함께 리턴됩니다. 각 API 마다 정의된 오류코드는 다르지만 공통적으로 리턴될 수 있는 코드는 Message Status Codes 를 참고하세요.