1.           WEB API 개요

pushpia 사용상의 필요한 Data 획득 혹은 발송 등을 URL 통해서 가능하게 도와준다.

 

1.1.       사용방법 (기본 호출 규칙)

Method 호출, 입력 URL 따라 원하는 요청을 수행하니 규칙에 맞게 호출하도록 한다. 사용방법으로 크게 URL / Parameters / Return 4가지 용어에 대한 이해한다면, 요청 매뉴얼에 대한 이해를 하는데도 도움이 많이 것이다.

1.1.1.   입력 URL

실질적으로 원하는 요청을 수행하기 위해서 HTTP 이용한 URL 호출방식을 수행하고 있다. 요청 별로 그에 맞는 URL 호출규칙이 있으니, 해당 규칙을 준수하여 호출하도록 하자.

l  ASP 페이지의 기본호출 URL : 아래와 같은 URL뒤에 요청 별로 추가 URL 붙는다.

-      https://api.pushpia.com:444/~

1.1.2.   Parameters

부가적인 정보를 입력하기 위해서 사용한다. URL 뒷부분에 아래 예시와 같이 ‘?’ ‘&’ 이용하여 입력 값을 전달받는다. 기본 URL 호출시의  parameter 값의 규칙과 마찬가지로 ‘?’ parameter 시작됨을, ‘&’ 추가적인 parameter 시작됨을 의미한다.

l  Parameter 사용된 (JSON 배열로 BIZ ID 전달하는 경우)

-      https://api.pushpia.com:444/send/realtime?d={"bizId":"aaa0669e23ac415ca3a8b0e30062ca8c"}

1.1.3.   Return (결과반환)

URL 이용하여 요청을 하면 해당내용에 대한 결과도 필요하다. 이를 위해 결과를 반환하고 있으며, 발송요청을 수행한 경우 성공 실패여부를 반환하도록 하고 있다.

l  발송요청이 성공한 경우

{"bizId":"aaa0669e23ac415ca3a8b0e30062ca8c","reqUid":"pushpia_20150420094700",

"custId":"userid","code":"000","msg":"SUCCESS"}

l  발송요청이 실패한 경우 (파라미터가 부족한 경우)

{"code":"100","msg":"param is null"}

 

 

1.1.4.   필수

URL 상에는 요구에 따라 입력하는 Parameter 이외에도 필수입력 값이 필요한 경우도 있다. 필수 값은 Parameter 입력과는 다르게 {JSON array} 같은 형식으로 매뉴얼에 표현되었으니, 실제로는 JSON array 해당되는 실제 값을 넣어주면 된다. 헷갈린다면 아래예시를 참고하자.

l  매뉴얼상에 표시된 URL

https://api.pushpia.com:444/send/realtime?d={JSON array}

l  실제 호출 URL

https://api.pushpia.com:444/send/realtime?d={

    "bizId": "aaa0669e23ac415ca3a8b0e30062ca8c",

    "msgType": "T",

    "pushTime": 1800,

    "pushTitle": "title",

    "pushMsg": "push message",

    "pushKey": "l",

    "pushValue": "http://www.pushpia.com",

    "reserveTime": "20150417101700",

    "reqUid": "pushpia_20150417101700",

    "custId": "userid"

}

2.           API 가이드

전반적으로 정의된 URL 호출방식을 정의하고 있으며, 실제 사용시 알맞은 요청을 찾아 사용방법을 참고하면 된다.

2.1.       실시간(RealTime)

실시간 발송요청에 대한 상세내용을 정의한다.

2.1.1.   Push발송URL

실시간 발송을 이용하여 실질적인 Push 발송작업을 수행한다. 요청이 들어오는 순간, 해당 어플리케이션을 사용하고 있는 사용자 단일 사용자 혹은 다수의 사용자에게 Push 메시지를 전달한다.

실시간 Push 발송하기 위해 bizId, msgType, pushTime, pushMsg, reserveTime, reqUid, custId 필수 사항이며, inappContent pushKey, pushValue 추가정보로 입력할 있다. 또한, 동보 Push 메시지의 경우 infoNA, infoCP 추가정보로 입력할 있다.

Push 메시지 발송을 위한 파라미터는 변수 d JSON 형식으로 전달하게 되는데, 개인화 메시지 혹은 동보 메시지 여부에 따라 JSON 배열의 구성이 달라지게 된다.

l  URL

https://api.pushpia.com:444/send/realtime?d={JSON array}

l  Method

GET/POST

l  Parameters

파라미터명

파라미터의 의미

필수/선택 여부

bizId

발송하려는 실시간 Push BIZ ID

필수

msgType

Push 메시지 타입 (T : Text, H : HTML)

필수

pushTime

발송 유효시간

필수

pushTitle

수신 Push 제목

필수

popupContent

수신 Push 팝업 메시지

선택

pushMsg

수신 Push 상태창 메시지

필수

inappContent

메시지함에서 보여줄 메시지 내용

선택

pushKey

고정 (소문자 l 고정되어야 하며 변경 발송 불가)

선택

pushValue

페이로드에 넘겨줄 주소

선택

reserveTime

예약발송시간

필수

reqUid

발송 식별

필수

custId

메시지 수신자

필수

infoNA

수신자 이름

선택

infoCP

수신자 휴대전화번호

선택

mktFlag

마케팅 푸시 여부 ( Y : 마케팅용 푸시, N : 정보용 푸시 )

선택

l  Examples

[개인화 Push 메시지의 경우]

{

     "bizId":"aaa0669e23ac415ca3a8b0e30062ca8c",

     "msgType":"T",

     "pushTime":1800,

     "pushTitle":"title",

     "pushMsg":"push message",

     "inappContent":"inapp content",

     "pushKey":"l",

     "pushValue":"http://www.pushpia.com",

     "reserveTime":"20150417101700",

     "reqUid" : "pushpia _20150417101700",

     "custId" : "userid"

}

 

[동보 Push 메시지의 경우]

{

     "bizId":"aaa0669e23ac415ca3a8b0e30062ca8c",

     "msgType":"T",

     "pushTime":1800,

     "pushTitle":"title",

     "pushMsg":"push message",

     "inappContent":"inapp content",

     "pushKey":"l",

     "pushValue":"http://www.pushpia.com",

     "reserveTime":"20150417202800",

     "list":[

          {

               "reqUid" : "pushpia_20150417202800",

               "custId" : "userid"

               "infoNA" : "username",

               "infoCP" : "01012345678"

          }

     ]

}

 

l  Return

코드

결과메시지

상태

000

SUCCESS

성공

100

param is null

request is null

파라미터 부족

파라미터 없음

101

Wrong size {paramName}

잘못된 파라미터 크기

102

Invalid BizId

잘못된 데이터 입력

110

occured error, to update app user

내부오류

120

executeInternal error

기타오류

 

[참고사항]

- 개인화 메시지는 수신자별로 메시지 내용을 다르게 하여 발송하고 싶은 경우 사용한다.

- 동보 메시지는 같은 내용의 메시지를 다수의 수신자에게 발송하고 싶은 경우 사용한다.

- 개인화 동보 Push 메시지의 pushKey pushValue, 그리고 동보 Push 메시지의 infoNA, infoCP 항목은 선택 입력사항이다.

- 동보 Push 발송 수신자로 지정하고 싶은 만큼 list 항목을 추가하면 된다.

- reqUid 테이블에 삽입되는 레코드마다(발송 건마다) 모두 달라야 한다.

- 발송 유효시간은 전원이 꺼져있거나 네트워크에 연결되지 않아 Push 메시지를 받지 못한 경우, 재발송을 위해 메시지를 보관하는 시간을 말한다.

- pushKey 필수 값인 "l" 소문자 L 이다.

- pushValue 넘겨주는 값은 멀티 푸시 작성 버튼링크 항목에 넘겨주는 값과 같은 역할을 한다.

- 코드 101 대한 실제 결과메시지에는 해당 파라미터의 최대 크기도 함께 나타낸다.

- 코드 110 대한 결과메시지는 대표사례 하나에 대해 표기한 것이며, 상황에 따라 메시지 내용이 달라질 있다.