# 5. 단일 건 발송

## 개요

특정 대상 즉 Token에 맵핑 될 단일 식별자(identity)에게 메시지를 보내는 방법입니다.

단, 과도한 단일건 발송 API 호출로 서비스의 트래픽을 발생시킬 경우 사전경고 없이 서비스의 제약을 받을 수 있습니다.

![](https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FNY2Z4SeJkacIqq6ujrqr%2Fimage4.png?alt=media\&token=150384b8-6ff1-4aeb-a959-130dbf9ca2b7)

{% hint style="info" %}
API Server URL: <https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp>
{% endhint %}

## 발송 방법 및 전송/수신 파라미터 정의

### HTTPS Parameters

SSL Protocol을 이용하여 파라미터들을 API Server에 전달합니다.

API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요.

#### \[표 4.1] 단일 건 발송 HTTPS, Parameters

<table><thead><tr><th width="150">파라미터명</th><th width="150">필수 여부</th><th width="150">Byte 수</th><th>설명</th></tr></thead><tbody><tr><td><mark style="color:red;">appkey</mark></td><td>필수</td><td>-</td><td>Application key</td></tr><tr><td><mark style="color:red;">appsecret</mark></td><td>필수</td><td>-</td><td>Application Secret</td></tr><tr><td><mark style="color:red;">customerkey</mark></td><td>필수</td><td>-</td><td>Customer key</td></tr><tr><td><mark style="color:red;">msg</mark></td><td>필수</td><td>1000</td><td>보낼 푸시 메시지</td></tr><tr><td><mark style="color:red;">identity</mark></td><td>필수</td><td>50</td><td>대상자 식별자 값</td></tr><tr><td>isa</td><td>선택</td><td>-</td><td><p>Y: 안드로이드 기기 대상 발송(default) </p><p>N: 안드로이드 기기를 전송 대상에서 제외 </p><p>※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리</p></td></tr><tr><td>asnd</td><td>선택</td><td>50</td><td><p>안드로이드 기기의 푸시 수신 사운드 </p><p>※ 핑거푸시 Android API 적용을 기준으로 효과음 지정</p></td></tr><tr><td>abdg</td><td>선택</td><td>-</td><td><p>안드로이드 푸시 배지 처리 파라미터, number type. ex) 1 ~ </p><p>※ 핑거푸시 Android API 적용을 기준으로 배지 효과 지정</p></td></tr><tr><td>isi</td><td>선택</td><td>1</td><td><p>Y: IOS 기기 대상 발송(default) </p><p>N: IOS 기기를 전송 대상에서 제외 </p><p>※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리</p></td></tr><tr><td>ibdg</td><td>선택</td><td>-</td><td><p>IOS 푸시 배지 처리 파라미터, number type. ex) 1 ~ </p><p>※ 핑거푸시 IOS API 적용을 기준으로 배지 효과 지정</p></td></tr><tr><td>isnd</td><td>선택</td><td>50</td><td><p>IOS 기기의 푸시 수신 사운드 </p><p>※ 핑거푸시 IOS API 적용을 기준으로 효과음 지정</p></td></tr><tr><td>ck1</td><td>선택</td><td>100</td><td><p>커스텀 키 1(App 개발 시 반영된 값) </p><p>deep link > app link > custom key 1 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값</p></td></tr><tr><td>ck2</td><td>선택</td><td>100</td><td><p>커스텀 키 2(App 개발 시 반영된 값) </p><p>deep link > app link > custom key 2 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값</p></td></tr><tr><td>ck3</td><td>선택</td><td>100</td><td><p>커스텀 키 3(App 개발 시 반영된 값) </p><p>deep link > app link > custom key 3 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값</p></td></tr><tr><td>cv1</td><td>선택</td><td>200</td><td><p>커스텀 값 1(App 개발 시 반영된 값) </p><p>deep link > app link > custom value 1 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값</p></td></tr><tr><td>cv2</td><td>선택</td><td>200</td><td><p>커스텀 값 2(App 개발 시 반영된 값) </p><p>deep link > app link > custom value 2 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값</p></td></tr><tr><td>cv3</td><td>선택</td><td>200</td><td><p>커스텀 값 3(App 개발 시 반영된 값) </p><p>deep link > app link > custom value 3 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값</p></td></tr><tr><td>link</td><td>선택</td><td>200</td><td><p>deep link > web link<br>ex) https://www.kissoft.co.kr </p><p>※ 해당 링크에 정의된 값이 있으면 푸시 메시지에 해당 링크 제공(핑거푸시 APP API가 적용되어 있어야 함)</p></td></tr><tr><td>fnm</td><td>선택</td><td>200</td><td><p>첨부 이미지 링크</p><p>-안드로이드 폰에서 첨부된 이미지 표현 가능</p><p>-도메인을 포함한 전체 경로 입력 </p><p>ex)http://www.kissoft.co.kr/images/img.jpg</p></td></tr><tr><td>send_state</td><td>선택</td><td>4</td><td><p>0001: 바로 발송(default) </p><p>0002: 예약발송</p></td></tr><tr><td>senddate</td><td>선택</td><td>12</td><td><p>send_stat 값이 0002(예약발송)으로 처리된 경우 예약 발송 날자 및 시간 입력 </p><p>ex) yyyymmdd24hmin -> 202109172113</p></td></tr><tr><td>title</td><td>선택</td><td>100</td><td>푸시 수신 시 메시지 제목</td></tr><tr><td>lcode</td><td>선택</td><td>10</td><td>라벨 코드</td></tr><tr><td>bgcolor</td><td>선택</td><td>7</td><td>배경색 ex) #FFFFFF</td></tr><tr><td>fcolor</td><td>선택</td><td>7</td><td>폰트 색상 ex) #000000</td></tr><tr><td>isetiquette</td><td>선택</td><td>-</td><td><p>에티켓 시간 적용 여부 </p><p>Y: 적용(default) </p><p>N: 적용 안함</p></td></tr><tr><td>etiquette_stime</td><td>선택</td><td>-</td><td><p>에티켓 적용 시작시간 </p><p>-Number type(1~ 24) </p><p>-default: 21(오후 9시)</p></td></tr><tr><td>etiquette_etime</td><td>선택</td><td>-</td><td><p>에티켓 적용 종료시간 </p><p>-Number type(1~24)<br>-default: 8(오전 8시)</p></td></tr><tr><td>and_priority</td><td>선택</td><td>-</td><td><p>안드로이드용 메시지 우선순위 </p><p>H: 높음 </p><p>M: 중간(default)</p></td></tr><tr><td>optagree</td><td>선택</td><td>-</td><td><p>0000: 광고 수신 동의 여부에 관계없이 푸시 수신자 모두에게 발송(default) </p><p>1000: 광고 수신 동의한 디바이스에만 메시지 발송</p></td></tr></tbody></table>

### Response JSON

API서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다.

```json
{"result" : "200", "msgIdx" :  "A1DS33DDSQ2321", "processCode" : "20003", "message" : "정상 처리되었습니다.", "ratelimit-limit" : "20", "ratelimit-remaining" : "17"}
```

#### \[표 4.2] 발송 JSON 결과

<table><thead><tr><th width="150">값</th><th>설명</th></tr></thead><tbody><tr><td>result</td><td>결과 코드</td></tr><tr><td>msgIdx</td><td>메시지 번호</td></tr><tr><td>processCode</td><td>메시지 처리 단계</td></tr><tr><td>message</td><td>결과 메시지</td></tr><tr><td>ratelimit-limit</td><td>분당 허용되는 최대 요청 횟수</td></tr><tr><td>ratelimit-remaining</td><td>잔여 분(minute) 동안 가능한 요청 횟수</td></tr><tr><td>retry-after</td><td><p>요청 갱신 시간까지 남은 초(second)</p><p>- ratelimit를 초과한 경우에만 _code: 429와 함께 반환</p></td></tr></tbody></table>

처리결과에 따른 result 값은 아래와 같습니다.

#### \[표 4.3] 발송 JSON 결과의 result code 유형

<table><thead><tr><th width="150">코드</th><th>내용</th><th>비고</th></tr></thead><tbody><tr><td>200</td><td>정상처리 됨</td><td> </td></tr><tr><td>4031</td><td>유효하지 않은 appkey 혹은 appsecret</td><td> </td></tr><tr><td>4032</td><td>Server to Server 서비스 이용권한 없음</td><td> </td></tr><tr><td><mark style="color:red;">4040</mark></td><td><mark style="color:red;">존재하지 않는 식별자</mark></td><td><mark style="color:red;">수집되지 않았거나, 삭제된 식별자</mark></td></tr><tr><td>429</td><td>분당 호출 수 초과</td><td></td></tr><tr><td>500</td><td>서버 에러</td><td></td></tr><tr><td>503</td><td>필수 값이 누락됨</td><td>Message에 누락된 필수값 표시됨</td></tr><tr><td>504</td><td>발송 대상 처리 중 에러</td><td>발송 대상 데이터 확인</td></tr><tr><td>505</td><td>메시지 허용 byte 수 초과</td><td>1000 byte 제한</td></tr></tbody></table>

processCode는 푸시 메시지 처리 단계를 표시하는 코드입니다. 단일 발송에서는 큰 의미가 없으나, 500건 이상의 메시지 발송에서는 각 단계별 처리를 위한 코드로 사용됩니다.

처리결과에 따른 result 값은 아래와 같습니다.

#### \[표 4.4] JSON 결과의 processCode code 유형

<table><thead><tr><th width="150">코드</th><th>내용</th><th>비고</th></tr></thead><tbody><tr><td>20001</td><td>푸시 메시지 등록 정상 처리</td><td> 메시지 아이디가 반환됨</td></tr><tr><td>20002</td><td>발송대상자 등록 정상 처리</td><td> </td></tr><tr><td>20003</td><td>푸시 메시지 등록 완료</td><td> </td></tr></tbody></table>

## 샘플 소스 설명

HTTPS로 미리 정의된 파라미터들을 전달하고 JSON으로 결과 데이터를 읽을 수 있도록 작업해 주시면 됩니다.

JAVA용 샘플의 경우 Apache common의 HttpClient(<http://hc.apache.org/)를> 이용하여 파라미터를 전송하도록 하였으므로 해당 library가 필요합니다. 샘플 소스는 GitHub를 통해 확인 가능 합니다.&#x20;

JSP 샘플의 경우, 샘플 메소드를 이용한 직접 발송이 가능합니다. 혹, 사용자 환경에 맞도록 수정이 필요하면 class(com.fingerpush.push.FingerpushDaoImpl)내에 구성되어 있는 메소드를 참조해 주시기 바랍니다.

해당 샘플에 대한 설명은 파라미터 전달 및 API URL에 대해 클래스 내에 구현되어 있는 로직 위주로 설명 드립니다.

### JAVA Version

Github에 올려져 있는 샘플소스는 아래 설명된 내용 중 중복된 부분들을 method화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.

1\) 파라미터를 담을 List 객체를 선언해 전달할 값들을 셋팅 합니다.

```java
List <BasicNameValuePair> params = new ArrayList<BasicNameValuePair>();
```

2\) 필수값들을 셋팅 합니다.

```java
List <BasicNameValuePair> params = new ArrayList<BasicNameValuePair>(); 

params.add (new BasicNameValuePair("appkey", 애플리케이션 키));             // (필수)	
params.add (new BasicNameValuePair("appsecret", 애플리케이션 시크릿));       // (필수)
params.add (new BasicNameValuePair("customerkey", 발급받은 커스터머키));     // (필수)
params.add (new BasicNameValuePair("msg", 푸시메시지 내용));                // 메시지 (필수)
```

3\) 선택 값들을 셋팅 합니다. (선택)\
해당 내용들은 Application 개발 시 반영된 내용을 기준으로 처리합니다.

```java
params.add (new BasicNameValuePair("isa", "Y"));           // 안드로이드를 사용하는 대상폰 발송 Y/N (필수)
params.add (new BasicNameValuePair("asnd", ""));           // 푸시 수신 시 안드로이드 사운드 (선택)
params.add (new BasicNameValuePair("abdg", ""));           // 안드로이드 푸시 배지 처리용(선택)
params.add (new BasicNameValuePair("isi", "Y"));           // IOS를 사용하는 대상폰 발송 Y/N(필수)
params.add (new BasicNameValuePair("ibdg", ""));           // IOS 푸시 배지 처리(선택)
params.add (new BasicNameValuePair("isnd", ""));           // IOS 푸시 사운드 처리(선택)
params.add (new BasicNameValuePair("ck1", ""));            // custom key 1(선택)
params.add (new BasicNameValuePair("ck2", ""));            // custom key 2(선택)
params.add (new BasicNameValuePair("ck3", ""));            // custom key 3(선택)
params.add (new BasicNameValuePair("cv1", ""));            // custom value 1(선택)
params.add (new BasicNameValuePair("cv2", ""));            // custom value 2(선택)
params.add (new BasicNameValuePair("cv3", ""));            // custom value 3(선택)
params.add (new BasicNameValuePair("fnm", ""));            // 첨부이미지 파일 링크 경로(선택)
params.add (new BasicNameValuePair("title", push.getTitle()));  // 제목
params.add (new BasicNameValuePair("bgcolor", "#FF0000"));  // 배경 컬러 RGB 값. ex) #FF0000
params.add (new BasicNameValuePair("fcolor", "#4374D9"));   // 폰트 컬러 RGB 값. ex) #4374D9
params.add (new BasicNameValuePair("lcode",""));            // 메시지 라벨코드: 메시지 라벨관리에서 발급받은 10자리 난수
params.add (new BasicNameValuePair("isetiquette", "Y"));    // 에티켓 시간 적용 여부 Y: 적용, N: 적용 안함
params.add (new BasicNameValuePair("etiquette_stime", "20"));   // 에티켓 적용 시작 시간 0~23
params.add (new BasicNameValuePair("etiquette_etime", "8"));    // 에티켓 적용 해제 시간 0~23
params.add (new BasicNameValuePair("and_priority","H"));    // 안드로이드 우선순위 H: 높음 / M: 중간(default)
params.add (new BasicNameValuePair("optagree", "0000"));    // 옵션 동의, 0000: 광고수신 비동의 여부에 관계없이 발송, 1000: 광고 수신 동의한 사람에게만 발송
```

4\) 해당 메시지를 받은 대상자를 셋팅 합니다.

```java
params.add (new BasicNameValuePair("identity", 식별자));        // 대상자 식별자 (필수)
```

5\) 기존 HttpClient의 DefaultHttpClient를 이용한 원격 접속 방식이 deprecated 된    이유로 HttpsURLConnection을 이용하여 접속합니다. 물론 deprecated 되었다고 해서 DefaultHttpClient 방식이 동작하지 않는 것은 아닙니다. 해당 방식 역시 github에 올려져 있는 샘플 소스에 구현되어 있습니다.

* 예제: FingerpushDaoImpl.sendHttpsExe(String callUrl, List \<BasicNameValuePair> params))

&#x20;전달하는 파라미터는 UTF-8로 인코딩 하여 전달해야 합니다.

* 예제: 샘플의 FingerpushDaoImpl.sendHttpsUrlConExe(String callUrl, List \<BasicNameValuePair> params)

{% hint style="info" %}
API Server URL: [https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp](https://api-v2.fingerpush.com/rest/sts/v3/setSTSpush.jsp)
{% endhint %}

```java
URL url = new URL(callUrl);
trustAllHosts();
HttpsURLConnection httpsURLConnection = (HttpsURLConnection) url.openConnection();
httpsURLConnection.setHostnameVerifier(new HostnameVerifier() {
    @Override
    public boolean verify(String s, SSLSession sslSession) {
    return true;
    }
});
HttpURLConnection connection = httpsURLConnection;
connection.setRequestMethod("POST");
connection.setUseCaches(false);           
connection.setDoInput(true);
connection.setDoOutput(true);

UrlEncodedFormEntity entity = new UrlEncodedFormEntity(params, "utf-8");
OutputStream post = connection.getOutputStream();
entity.writeTo(post);
 
post.flush();
connection.connect();
```

6\) 받은 결과는 JSON 타입의 String 이므로 결과에 맞게 변환하여 사용하시는 UI에 적용하시면 됩니다. \
받은 jsonString은 앞서 설명한 ‘[Response JSON](#response-json)’ 부분을 참조해 주세요.

```java
StringBuilder responseStringBuilder = new StringBuilder();
logger.debug("contentType : "+connection.getContentType());
if (connection.getResponseCode() == HttpURLConnection.HTTP_OK){
        
        BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream(), "UTF-8"));
        for (;;){
                String stringLine = bufferedReader.readLine();
                if (stringLine == null ) break;
                responseStringBuilder.append(stringLine + '\n');
        }
        bufferedReader.close();
}
connection.disconnect();

jsonString = responseStringBuilder.toString(); 
```

#### ※ JAVA Version 단일 건 발송 샘플

<table data-header-hidden><thead><tr><th width="150"></th><th></th></tr></thead><tbody><tr><td>소스 주소</td><td><a href="https://github.com/kissoft/FingerPushSTSinJava">https://github.com/kissoft/FingerPushSTSinJava</a></td></tr><tr><td>class</td><td><p>com.fingerpush.push.FingerpushDao</p><p>com.fingerpush.push.FingerpushDaoImpl</p><p>com.fingerpush.push.PushVO</p></td></tr><tr><td>jsp</td><td>JSP/sendTargetOne.jsp</td></tr></tbody></table>

### PHP Version

Github에 올려져 있는 샘플 소스는 아래 설명된 내용 중 중복된 부분들을 method화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.

&#x20;

1\) 기본 앱 정보를 세팅합니다.

```php
// 공통 필수 
$key = array(
    'appkey'            => '[발급받은 appkey]',
    'appsecret'         => '[발급받은 appsecret]',
    'customerkey'       => '[발급받은 customerkey]',
);
```

2\) 메시지 발송에 사용되는 필수값과 선택값을 세팅합니다.

```php
$option = array(
	"identity" 		=> "[수신자 식별자]",
	"msg" 			=> "단건 푸시메시지",		// 메시지 (필수)
	"isa" 			=> "Y",				// 안드로이드를 사용하는 대상폰 발송 Y/N 
	"abdg" 			=> "",				// 안드로이드 푸시 배지 처리 용 
	"asnd" 			=> "",				// 푸시 수신 시 안드로이드 사운드 
	"isi" 			=> "Y",				// IOS를 사용하는 대상폰 발송 Y/N
	"ibdg" 			=> "",				// IOS 푸시 배지 처리
	"isnd" 			=> "",				// IOS 푸시 사운드 처리
	"ck1" 			=> "",				// custom key 1
	"ck2" 			=> "",				// custom key 2
	"ck3" 			=> "",				// custom key 3
	"cv1" 			=> "",				// custom value 1
	"cv2" 			=> "",				// custom value 2
	"cv3" 			=> "",				// custom value 3
	"fnm" 			=> "",				// 첨부이미지 파일 링크 경로
	"link" 			=> "",				// 링크 URL
	"mode" 			=> "DEFT",			// DEFT: 일반 푸시 메시지 / LNGT: long text push
	"lngt_message" 		=> "",				// long text message
	"send_state" 		=> "0001",			// 0001: 바로 발송 / 0002: 예약발송
	"senddate" 		=> "",				// 예약발송인 경우 예약 발송일 ex) 202109172113
	"tag" 			=> "",				// 발송 tag. 쉼표(, )로 구분. ex) 서울,대전,대구,부산
	"beschmode" 		=> "0001",			// 태그 발송 시 조건. 0001: or / 0002: and
	"title" 		=> "",				// 제목
	"bgcolor" 		=> "#FFFFFF",			// 배경 컬러
	"fcolor"		=> "#4374D9",			// 폰트 컬러
	"lcode" 		=> "",				// 메시지 라벨관리에서 발급받은 10자리 난수
	"isetiquette" 		=> "Y",				// 에티켓 시간 적용 여부 Y 적용, N 적용 안함.
	"etiquette_stime" 	=> "20",			// 에티켓 적용 시작 시간 0~23
	"etiquette_etime" 	=> "8",				// 에티켓 적용 해제시간 0~23
	"and_priority" 		=> "M",				// 안드로이드 우선순위 H: 높음 / M: 중간(default)
	"optagree" 		=> "0000",			// 옵션 동의 : 0000  광고수신 비동의 여부에 관계없이 발송, 1000 광고수신 동의 한 사람에게만 발송
);
```

3\) 앱 기본정보와 옵션값을 URL 인코드 한 쿼리 문자열로 생성합니다.

```php
$data = array_merge($key, $option);
$param = http_build_query($data);
```

4\) PHP cURL 라이브러리를 이용하여 핑거푸시 API와 통신합니다.

* PHP cURL 라이브러리: <https://www.php.net/manual/en/book.curl.php>
* 일괄발송 API URL: [https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp](https://api-v2.fingerpush.com/rest/sts/v3/setSTSpush.jsp)

cURL을 아래와 같이 HTTPS 통신으로 세팅합니다.

```php
$url = 'https://api-v2.fingerpush.com/rest/sts/v4/setSTSpush.jsp';   // 핑거푸시 단일발송 API URL

$ch = curl_init (); 			                        // cURL 선언
curl_setopt ( $ch, CURLOPT_URL, $url ); 		        // URL 세팅
curl_setopt ( $ch, CURLOPT_SSL_VERIFYPEER, false ); 	        // 인증서 체크
curl_setopt ( $ch, CURLOPT_SSLVERSION, 1 ); 		        // SSL 버전 -> 1만 된다.
curl_setopt ( $ch, CURLOPT_HEADER, 0 ); 		        // 헤더 출력 여부
curl_setopt ( $ch, CURLOPT_POST, 1 ); 		                // POST, GET 접속 여부
curl_setopt ( $ch, CURLOPT_TIMEOUT, 30 ); 		        // Time Out 세팅
curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1 ); 	        // 결과값 리턴 여부
curl_setopt ( $ch, CURLOPT_POSTFIELDS, $param ); 	        // parameter
$res = curl_exec ( $ch ); 			                // cURL 실행하고 결과 저장

/* cURL 에러검출 */
$cErrno = curl_errno($ch);

if ($cErrno == 0) $response = $res;
else $response = exit;
curl_close ( $ch );                                     // cURL을 닫고 자원 반환
```

5\) 전달 받은 JSON 문자열 결과값을 PHP 변수로 변환합니다.

```php
// 1. json 처리시
echo $response;

// 2. object 처리시
$result = json_decode ( $response, true );                // 결과값 JSON 디코드
print_r($result);                                        // 결과값 출력
```