API SPEC 및 연동예제 안내

문자보내기 및 관련 API 사용시 아래내용을 반드시 참고하여 주시기 바랍니다. 현재 제공되는 문자연동 API는 다음과 같습니다.

• 문자보내기 - 동일내용을 1천명에게 동시전송
• 전송내역조회 - 최근발송된 전송내역조회
• 전송결과조회(상세) - 전화번호별 성공유무 조회
• 발송가능건수 - 잔여건수 조회
• 예약문자 취소 - 예약대기중 문자 취소요청

문자보내기

동일한 내용의 문자를 컴마(,)로 분기하여 동시 1천명에게 전송하실 수 있습니다. 발신번호는 사이트내에서 미리 등록된 번호만 사용하실 수 있습니다. 발송타입을 지정하지 않으시면 90byte를 초과하는 메시지 발송 시 LMS(첨부파일 없는 MMS) 형태로 자동 전환됩니다. (단, 시스템별 개행문자등의 Byte가 다를 수 있으므로 전송전 90Byte 체크를 하여 발송타입을 지정하시는것을 권장합니다.)

[ Request ]

							
POST/front/api/rest/send/ HTTP/1.1
	Host: www.ssorago.com
	Service Port: 443

						

HTTPS 프로토콜을 사용하여 POST로 요청합니다. 예약설정을 통해 예약문자로 등록이 가능하며, 파일첨부를 통해 MMS 전송이 가능합니다.

키	설명	필수	타입
key	API Key	O	String
sender	발신번호	O	String
adYn	광고여부	O	String
bizName	상호명	O	String
msg	메시지 내용(치환기능: #이름#, #항목1#, #항목2#, #항목3#, #항목4#)	O	String (1~2,000Byte)
receiver	받는사람(01012341234$이름1$항목1,01012341235$이름2$항목1)	O	String
interYn	국제발송여부	X	String
st	발송타입(SMS,LMS,MMS)	X	String
title	문자제목(LMS,MMS만 허용)	X	String (1~44Byte)
reserve	예약일시	X	yyyyMMddHHmm
time	분할 간격	X	String
cnt	분할 건수	X	String
attFile	첨부이미지	X	JPG

예를 들면,

							
curl -X POST "https://www.ssorago.com/front/api/rest/send/" \
	--data-urlencode "key=xxxxx" \
	--data-urlencode "sender=01012341234" \
	--data-urlencode "adYn=Y" \
	--data-urlencode "bizName=SSORAGO" \
	--data-urlencode "msg=#이름#님! 안녕하세요." \
	--data-urlencode "receiver=01012341234$홍길동,01012341235$홍길순" \
	--data-urlencode "interYn=N" \
	--data-urlencode "st=MMS" \
	--data-urlencode "title=API테스트" \
	--data-urlencode "reserve=202012071800" \
	--data-urlencode "time=10" \
	--data-urlencode "cnt=1" \
	--form attFile=@localfilename
							

[Response]

응답 바디는 JSON 객체로 구성됩니다.

JSON

키	설명	타입
resultCode	결과코드(API 수신유무)	Integer
resultMessage	결과 메세지( result_code 가 0 보다 작은경우 실패사유 표기)	String
mid	메세지 ID	String
successCnt	요청성공 건수	String
errorCnt	요청실패 건수	String

위 2건의 수신번호를 ,로 분기하여 전송한 경우를 예로들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "resultCode": 1
    "resultMessage": ""
    "mid": "123456789"
    "successCnt": "2"
    "errorCnt": "0"
}

전송요청이 실패한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "resultCode": -101
    "resultMessage": "유효하지 않은 Key입니다."
}
							
						

 

전송내역조회

최근 요청및 처리된 전송내역을 조회하실 수 있습니다. 사이트내 전송결과조회 페이지와 동일한 내역이 조회되며, 날짜기준으로 조회가 가능합니다. 발신번호별 조회기능은 제공이 되지 않습니다. 조회시작일을 지정하실 수 있으며, 시작일 이전 몇일까지 조회할지 설정이 가능합니다. 조회시 최근발송내역 순서로 소팅됩니다.

[ Request ]

							
POST /front/api/rest/list/ HTTP/1.1
	Host: www.ssorago.com
	Service Port: 443
							

HTTPS 프로토콜을 사용하여 POST로 요청합니다.

키	설명	필수	타입
key	API Key	O	String
sender	발신번호	X	String
sd	검색 시작일자	X	yyyyMMdd
ed	검색 종료일자	X	yyyyMMdd
interYn	국제발송여부	X	String
st	발송타입(SMS,LMS,MMS)	X	String
page	페이지	X(기본 1)	Integer
unit	페이지 당 갯수	X(기본 10)	Integer

오늘기준 7일전 날짜의(10월 23일 0시 ~ 24시) 전송내역 조회를 예로 들면,

							
curl -X POST "https://www.ssorago.com/front/api/rest/list/" \
	--data-urlencode "key=xxxxx" \
	--data-urlencode "sender=123456789" \
	--data-urlencode "sd=20201023" \
	--data-urlencode "ed=20201023" \
	--data-urlencode "interYn=N" \
	--data-urlencode "st=SMS,LMS,MMS" \
	--data-urlencode "page=1" \
	--data-urlencode "unit=20"
							
						

[Response]

응답 바디는 JSON 객체로 구성됩니다.

JSON

키	설명	타입
resultCode	결과코드(API 수신유무)	Integer
resultMessage	결과 메세지( result_code 가 0 보다 작은경우 실패사유 표기)	String
list	목록 배열	Array
nextYn	다음조회목록 유무	String

list 배열

키	설명	타입
mid	메세지 ID	Integer
st	발송타입	String
status	발송상태	String
sendDate	발송날짜	yyyy-MM-dd HH:mm:ss
title	문자제목	Integer
msg	메시지 내용	String
totalCnt	총 발송 건수	Integer
waitCnt	대기 건수	Integer
successCnt	성공 건수	Integer
failCnt	실패 건수	Integer

최근 발송된 2건을 조회한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "result_code": 1
    "message": "success"
    "list": [{
		"mid": "123456789",
		"st": "LMS",
		"status": "대기",
		"sendDate": "2020-12-08 16:00:00",
		"title": "[API 테스트]",
		"msg": "(광고)SSORAGO\n#이름#님! 안녕하세요. LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다\n무료거부 0800000000",
		"totalCnt": "2",
		"waitCnt": "2",
		"successCnt": "0",
		"failCnt": "0"
		}, {
		"mid": "123456788",
		"st": "LMS",
		"status": "대기",
		"sendDate": "2020-12-08 15:50:00",
		"title": "[API 테스트]",
		"msg": "(광고)SSORAGO\n#이름#님! 안녕하세요. LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다\n무료거부 0800000000",
		"totalCnt": "2",
		"waitCnt": "2",
		"successCnt": "0",
		"failCnt": "0"
	} ]
    "next_yn": "Y"
}

전송요청이 실패한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
	"resultCode": -101
	"resultMessage": "유효하지 않은 Key입니다."
}

 

전송결과조회(상세)

send에서 리턴되는 mid 또는 list API에서 조회되는 mid를 사용하여 수신번호별 상태를 조회하실 수 있습니다. 수신전화번호별 전송상태를 조회하실 수 있으며 목록에 없거나 전송중인 문자는 만24시간동안 전송시도중인것입니다. 최종 24시간이 경과 후 조회하셔야 완료된 내역을 확인하실 수 있습니다.

[ Request ]

							
POST /front/api/rest/sms_list/ HTTP/1.1
	Host: www.ssorago.com
	Service Port: 443
							

HTTPS 프로토콜을 사용하여 POST로 요청합니다. 통신사에 전달 후 전송결과가 통보되지 않은 경우에는 목록에 나오지 않거나, 전송중으로 나올 수 있습니다. 24시간 후 최종 결과를 확인하시기 바랍니다.

키	설명	필수	타입
key	API Key	O	String
mid	메세지 ID	O	String
interYn	국제발송여부	X	String
receiver	수신번호	X	String
status	발송상태(W,S,F)	X	String
page	페이지	X(기본 1)	Integer
unit	페이지 당 갯수	X(기본 10)	Integer

mid 123456789 의 전송결과 상세 조회를 예로 들면,

							
curl -X POST "https://www.ssorago.com/front/api/rest/sms_list/" \
	--data-urlencode "key=xxxxx" \
	--data-urlencode "mid=123456789" \
	--data-urlencode "interYn=N" \
	--data-urlencode "receiver=01012341234" \
	--data-urlencode "status=W" \
	--data-urlencode "page=1" \
	--data-urlencode "page_size=20"
							

[Response]

응답 바디는 JSON 객체로 구성됩니다.

JSON

키	설명	타입
resultCode	결과코드(API 수신유무)	Integer
resultMessage	결과 메세지( result_code 가 0 보다 작은경우 실패사유 표기)	String
list	목록 배열	Array
nextYn	다음조회목록 유무	String

list 배열

키	설명	타입
title	메세지 제목	Integer
msg	메세지 내용	String
receiver	수신번호	String
status	발송상태	String
requestDate	발송요청날짜	yyyy-MM-dd HH:mm:ss
sendDate	발송날짜	yyyy-MM-dd HH:mm:ss

최근 발송된 2건을 조회한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
	"result_code": 1
	"message": "success"
	"list": [{
			"title": "[API 테스트]",
			"msg": "(광고)SSORAGO\n홍길동님! 안녕하세요. LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다\n무료거부 0800000000",
			"receiver": "01111111111",
			"status": "대기",
			"requestDate": "2020-12-08 15:15:19",
			"sendDate": "2020-12-08 18:00:00"
			}, {
			"title": "[API 테스트]",
			"msg": "(광고)SSORAGO\n홍길순님! 안녕하세요. LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다LMS 전환 테스트입니다다다다\n무료거부 0800000000",
			"receiver": "01111111112",
			"status": "대기",
			"requestDate": "2020-12-08 15:15:19",
			"sendDate": "2020-12-08 18:00:00"
		} ]
	"next_yn": "N"
}

전송요청이 실패한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
	"resultCode": -101
	"resultMessage": "유효하지 않은 Key입니다."
}

 

발송가능건수

보유한 충전금 잔액으로 발송가능한 잔여건수를 문자구분(유형)별로 조회하실 수 있습니다. SMS, LMS, MMS로 발송시 가능한 잔여건수이며 남은 충전금을 문자유형별로 보냈을 경우 가능한 잔여건입니다. 예를들어 smsCnt : 11 , lmsCnt : 4 인 경우 단문전송시 11건이 가능하고, 장문으로 전송시 4건이 가능합니다.

[ Request ]

							
POST /front/api/rest/remain/ HTTP/1.1
	Host: www.ssorago.com
	Service Port: 443
							

HTTPS 프로토콜을 사용하여 POST로 요청합니다.

키	설명	필수	타입
key	API Key	O	String

예를 들면,

							
curl -X POST "https://www.ssorago.com/front/api/rest/remain/" \
	--data-urlencode "key=xxxxx"
							

[Response]

응답 바디는 JSON 객체로 구성됩니다.

JSON

키	설명	타입
resultCode	결과코드(API 수신유무)	Integer
resultMessage	결과 메세지( resultCode 가 0 보다 작은경우 실패사유 표기)	String
smsCnt	단문전송시 발송가능한건수	Integer
lmsCnt	장문전송시 발송가능한건수	Integer
mmsCnt	그림(사진)전송시 발송가능한건수	Integer
interCnt	국제 발송가능한건수	Integer

조회에 성공한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "resultCode": 1
    "resultMessage": ""
    "smsCnt": 5555
    "lmsCnt": 1930
    "mmsCnt": 833
    "interCnt": 24750
}

전송요청이 실패한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "resultCode": -101
    "resultMessage": "유효하지 않은 Key입니다."
}

send API 호출시 1만원이하 보유시 1회, 잔액소진으로 발송중지전 1회의 문자통보가 자동발송되고 있습니다. 그외 특정건수 이하 보유시 통보를 원하시는 경우 remain API를 사용하여 조회하신 후 send API로 통보되도록 구축하시기 바랍니다.

 

예약문자 취소

send API를 통해 예약한 내역을 전송취소할 수 있습니다. 예약취소는 발송전 5분이전의 문자만 가능합니다.

[ Request ]

							
POST /front/api/rest/cancel/ HTTP/1.1
	Host: www.ssorago.com
	Service Port: 443
							

HTTPS 프로토콜을 사용하여 POST로 요청합니다.

키	설명	필수	타입
key	API Key	O	String
mid	메세지 ID	O	Integer

예를 들면,

							
curl -X POST "https://www.ssorago.com/front/api/rest/cancel/" \
	--data-urlencode "key=xxxxx" \
	--data-urlencode "mid=123456789"
							

[Response]

응답 바디는 JSON 객체로 구성됩니다.

JSON

키	설명	타입
resultCode	결과코드(API 수신유무)	Integer
resultMessage	결과 메세지( resultCode 가 0 보다 작은경우 실패사유 표기)	String

정상취소가 완료된 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "resultCode": 1
    "resultMessage": ""
    
}

전송요청이 실패한 경우를 예로들면,

							
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "resultCode": -217
    "resultMessage": "예약 발송시간으로부터 1분 이전에는 취소가 불가능합니다."
}

연동형 API로 처리 실패시 message 항목의 안내문구를 참고하여 주시기 바랍니다.