# 6. 타겟 발송 실패 시 식별자 조회

## 개요

핑거푸시 사이트에서 제공하는 타겟 발송에 이용된 식별자에 대한 유효성 조회 기능입니다.

![](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/getResultTgMess.jsp>
{% endhint %}

Server to Server 타겟 발송 후 푸시 수신 대상자로 전송한 식별자들에 대한 유효성 여부를 조회하는 기능입니다.&#x20;

Server to Server 타겟 발송 기능을 이용하여 Fingerpush server에 푸시 메시지를 전송하고 이에 대한 결과 값으로 수신한 msgIdx를 이용하여 <mark style="color:blue;">발송에 실패한 식별자 목록을 paging 처리하여 조회</mark>할 수 있습니다.

해당 API는 기본적으로 메시지를 모두 발송한 후에 조회가 가능합니다.

또한, 발송 후 발송 대상 카운트 기준으로 페이지가 설정되나, 실패한 식별자에 대해서만 결과에 표시되기에, 특정 페이지에는 결과값이 없을 수도 있습니다. (해당 페이지에 속한 대상자의 메시지 발송이 성공한 경우에는 결과페이지에 표시되지 않습니다.)

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

### HTTPS Parameters

SSL Protocol을 이용하여 파라미터들을 API Server에 전달합니다.\
필수 값을 제외한 값들에 대해서는 별도 처리가 없을 경우 API 서버 측에서 기본값으로 처리됩니다.

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

#### \[표 5.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;">msgidx</mark></td><td>필수</td><td>-</td><td><p>Server to server API를 통해 메시지를 발송하고 받은 JSON 결과 값 중 메시지 일련번호에 해당하는 값.</p><p>※ 해당 API(타겟 발송 후 발송에 실패한 식별자들에 대한 결과 조회)를 사용하기 위해서는 메시지 발송 후 수신 받은 메시지 일련번호를 고객사 DB 별도로 보관할 필요가 있습니다.</p></td></tr><tr><td><mark style="color:red;">source</mark></td><td>필수</td><td>-</td><td><mark style="color:red;">API / AGENT(처리 방식)</mark><br>※ Source 값 미지정 시 대량 발송에 따른 페이징 처리에 시간이 걸리게 됩니다.</td></tr><tr><td>page</td><td>선택</td><td>-</td><td>페이지 번호, number type, default: 1</td></tr></tbody></table>

### Response JSON

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

```json
{
  msg_state: "발송 완료",
  totalpage: "3",
  total: "268",
  result: "200",
  msgidx: "EWsEdfG2FA1555",
: "",
  identityList: 
  [ {
    identity: "kissoft2",
    err_txt : "수신 불가(앱삭제) 처리된 식별자",
    err_code : "2401"
  }, 
   … 중략 …
  {
    identity: "bada2013"
    err_txt : "존재하지 않는 식별자",
    err_code : "2404"
  }
 ]}
```

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

<table><thead><tr><th width="150">값</th><th>설명</th></tr></thead><tbody><tr><td>result</td><td>결과 코드</td></tr><tr><td>message</td><td>결과 메시지</td></tr><tr><td>msgIdx</td><td><p>등록된 메시지 번호. 결과 조회 시 사용 </p><p>ex) DEF_40213134</p></td></tr><tr><td>total</td><td>조회 결과 전체 식별자 개수</td></tr><tr><td>msgStep</td><td>메시지 상태 (T: 메시지 입력 중, R: 발송대기, C: 성공, F: 실패, P: 발송중 일시정지)</td></tr><tr><td>msg_state</td><td>메시지 상태 메시지</td></tr><tr><td>totalpage</td><td>조회 결과 페이지 수</td></tr><tr><td>identityList</td><td>식별자 조회 결과 그룹</td></tr><tr><td>identity</td><td>식별자명</td></tr><tr><td>err_code</td><td>식별자에 대한 결과 코드</td></tr><tr><td>err_txt</td><td>식별자에 대한 결과 메시지</td></tr></tbody></table>

1\) 처리결과에 따른 result 값은 아래와 같습니다.\
조회 결과 identity와 쌍으로 출력되는 err\_txt를 확인하시고, 존재하지 않는 식별자(2404) 등에 대해서는 추후 API 서버로의 호출이 안되도록 조치해 주시면 됩니다.

#### \[표 5.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>4033</td><td>해당 메시지에 대한 접근 권한 없음</td><td></td></tr><tr><td>4034</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></tbody></table>

4044코드의 경우 현재 발송 대기 중이거나 발송 중 혹은 여타 문제 등으로 인한 발송 오류인 메시지 이므로 해당 메시지가 발송 완료된 경우에 대해서 API호출이 될 수 있도록 처리해 주셔야 합니다.

각각의 identity 결과 코드에 대한 설명은 아래와 같습니다.

#### \[표 5.4] JSON 결과의 result code 유형

<table><thead><tr><th width="150">코드</th><th>내용</th><th>비고</th></tr></thead><tbody><tr><td>2401</td><td>수신 불가(앱 삭제) 처리된 식별자</td><td> </td></tr><tr><td>2402</td><td>관리자에 의해 수신 거부된 식별자</td><td> </td></tr><tr><td>2403</td><td>사용자에 의해 수신 거부된 식별자</td><td> </td></tr><tr><td>2404</td><td>존재하지 않는 식별자</td><td>핑거푸시 Server 내에 존재하지 않음</td></tr><tr><td>2405</td><td>광고 푸시 동의 사용자가 아님</td><td>광고 메시지 푸시로 발송한 경우</td></tr></tbody></table>

결과 조회 시 ‘존재하지 않는 식별자‘(code: 2404)인 경우 추후 Fingerpush server로 재호출 되지 않도록 조치하시면, 불필요한 server delay 시간을 줄이실 수 있으며, 효율적인 발송을 하실 수 있습니다.

## 샘플 소스 설명

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화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.

&#x20;

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("msgidx", 푸시메시지 번호));                // 메시지 번호(필수)        
params.add (new BasicNameValuePair("page", 조회할 페이지번호));                // 페이지 번호(선택) 
```

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

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

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

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

{% hint style="info" %}
API Server URL: [https://api-v2.fingerpush.com/rest/sts/v4/getResultTgMess.jsp](https://api-v2.fingerpush.com/rest/sts/v3/getResultTgMess.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();
```

4\) 받은 결과는 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/getResultTargetMess.jsp</td></tr></tbody></table>

### PHP Version

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

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

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

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

```php
$option = array(
	"msgidx" 	=> $msgidx,		// message idx (필수)
	"source" 	=> "API",		// vAPI / AGENT(처리 방식)※ Source 값 미지정 시 대량 발송에 따른 페이징 처리에 시간이 걸리게 됩니다.
	"page" 		=> "",			// 페이징number type, default: 1
);
```

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/getResultTgMess.jsp>

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

```php
$url = 'https://api-v2.fingerpush.com/rest/sts/v4/getResultTgMess.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);                                        // 결과 값 출력
```