全功能進階技術介接- 簡訊API

全功能進階技術介接- 簡訊API

2011-08-03

簡訊王數位媒體   API協定說明(HTTP)
版本: 2023/ 08/ 21 SSL/TLS 1.0 已提升至 SSL/TLS 1.2
版本：2022/06/22 更新錯誤代碼(新增五項常見錯代碼)
版本: 2021/ 10/ 28 移除教學文章連結(已失效)
版本: 2019/ 07/ 02 更新預約功能說明
版本: 2019/ 04/ 09 更新錯誤代碼 (新增境外IP限制錯誤代碼)
版本: 2019/ 03/ 29 移除kotapi.dll套件
版本: 2017/ 03/ 13 新增kotapi.dll套件下載(已失效)
版本: 2016/ 11/ 25 新增api金鑰功能及相關安全套用工具說明
版本: 2016/ 11/ 02 新增TLS1.2加密新錯誤代碼
版本: 2016/ 07/ 11 修正查詢點數&狀態加密語法
版本: 2016/ 07/ 09 API僅使用加密路由
版本: 2016/ 06/ 27 字數長度規範容錯機制碼
版本: 2015/ 12/ 09 支援SSL加密功能
版本: 2010/ 07/ 28
版本: 2010/ 03/ 08 補充response 說明
版本: 2010/ 01/ 06 BIG5、 url編碼、上修測試數據
版本: 2010/ 01/ 18 雙向api介接說明
版本: 2011/ 08/ 03 會員剩餘點數查詢說明
版本: 2011/ 08/ 03 會員發送簡訊狀態查詢說明

簡訊線路規格的選擇
API介接前請先評估您的簡訊發送狀況:
若您簡訊發送機制為單通不定時發送，例如:加入會員發送手機認證簡訊或訂單通知等...

一次一通的簡訊發送建議您可以使用即時API。
若您簡訊發送機制為大量發送，一次發送數百筆或數千筆甚至數萬筆時，則建議您使用大量API。
若您兩種發送需求都有，建議您將即時以及大量兩種路由都用上，以需求分配路由，這可以使您的簡訊發送效率大增。

※中文字一律使用BIG5編碼。
※利用api傳送資料時，請將”所有”傳送資料都以url編碼，可避免因特殊字元，使得傳送裁斷或顯示異常。
1.介面說明
即時api   http://api.kotsms.com.tw/kotsmsapi-1.php?Tag=Value&Tag=Value…
大量api   http://api.kotsms.com.tw/kotsmsapi-2.php?Tag=Value&Tag=Value…

即時api使用建議範圍：會員系統認證、單次發送低於100筆可使用，建議簡訊投遞時間間隔0.5sec
大量api使用建議範圍：單次發送超過500筆請使用，簡訊投遞時間間隔0.005sec

即時與大量的差別在於，即時api當主機接收到指令會立即執行發送作業，單筆之間均會有時差固發送多筆會需求更多的時間發送，大量簡訊系統會疊積3~5分鐘後系統將全數傳出(依系統繁忙度而定)。

加密版本

(TLS 1.2)(原TSL 1.0已於2023/8/21提升至TSL 1.2)

https://api.kotsms.com.tw/kotsmsapi-1.php?Tag=Value&Tag=Value…
https://api.kotsms.com.tw/kotsmsapi-2.php?Tag=Value&Tag=Value…

(TLS 1.2)

https://api2.kotsms.com.tw/kotsmsapi-1.php?Tag=Value&Tag=Value…
https://api2.kotsms.com.tw/kotsmsapi-2.php?Tag=Value&Tag=Value…

註：
TLS1.2會因系統安全性本身是否相容會造成無發送連線情況。
使用TLS加密連結必需使用IE10以上才可以測試。

※ 簡訊王以不同的”網址”區隔即時API 以及大量API 介接方式 ※
Tag清單如下:

Tag

意義

username

帳號

password

密碼

dstaddr

目的門號

smbody

簡訊內容(BIG5)
※利用api傳送資料時，請將所有傳送資料都以url編碼，可避免因特殊字元，使得傳送裁斷或顯示異常。

dlvtime

Dlvtime為簡訊預約發送時間，可使用,YYYY/MM/DD hh24:mm:ss,格式設定
建議設定為"0"即時發送。
若有預約簡訊需求請於發送時間到達時再傳入簡訊王主機，可解決無法修改預約內容以及預約時間限制等問題。
若不宣告此參數，系統將判定為即時發送，但發送效率速度較設定為"0"值時較慢。
※若使用預約發送YYYY/MM/DD hh24:mm:ss,格式設定時請將所有傳送資料都以url編碼傳送(“日”與”時”之間的空格須轉碼為%20否則無法預約時、分、秒)

vldtime

※vldtime為發送簡訊的有效期限:
當接收手機未開機時,系統會重複再次發送簡訊給接收門號，若您的簡訊內容有時效性，您可設定若超過設定時間後就不再重複發送。

有效期限可使用,YYYY/MM/DD hh24:mm:ss,格式設定或使用” 秒數”設定

可設定秒數為 1800秒(30分鐘)~28800秒(八小時) 最小值建議1800秒最大值最多為八小時，若超過八小時系統還是會將有效時間判定為八小時。

若vldtime設定為0秒時有效時間將依簡訊中心流量設定值配送約4~24小時。
若vldtime不宣告此參數時，有效期限為預設值8小時。

response

發送簡訊是否成功的狀態回報網址, 若不宣告此參數時為不回報。

Ftcode

容錯機制碼。

註記：
.1 所有含*的Tag表非必要,若未輸入,系統會帶內定值進去。
.2 dlvtime和vldtime只支援二種格式：秒數及YYYY/MM/DD hh24:mm:ss，其餘格式皆不支援。
.3 username,password 需加入簡訊王申請www.kotsms.com.tw 。
.4 \n為chr(10)
.5 多則簡訊的回覆格式同單則簡訊，但全部的簡訊手機皆接到才算成功，
有任一則傳遞不成功即會回覆失敗。(回覆狀態有DELIVRD和UNDELIV的情況)
.6 文字編碼為ASCII，則smbody最多為160個英文、數字混合字元。
.7 文字編碼為BIG5，則smbody最多為70~335個中英文混合字元。(若超過70字將以長簡訊計算)
.8 ftcode (容錯機制碼)：自訂英文或數字最多36 個字元，在12 小時內，若帶有相同的容錯機制碼，
此則簡訊將丟棄不傳送。

2.範例

範例條件	代入內容
username	api01(帳號)
password	api01(密碼)
dstaddr	0933853653 (十位數字門號或加國碼的國際門號)
smbody	【簡訊王api測試】70個中英數標點混合為一則簡訊。可使用enter 以及空格全形數字１２３以及長達335個字的長簡訊。
dlvtime	可不代入此參數(不設定參數時均為即時發送)
vldtime	可不代入此參數 (不設定有效期限將使用預設值28800秒 )
response	http://回報網址/response.php (可不代入此參數)

送出簡訊範例如下：
https://api.kotsms.com.tw/kotsmsapi-1.php?username=帳號&password=密碼&dstaddr=0933853653&
smbody=簡訊王api簡訊測試 &response=http://回報網址/response.php

※使用URL方式測試簡訊時，請以 IE 瀏覽器 10以上版本進行測試，使用非IE會造成文字亂碼情況發生

收到記錄編號：
Kmsgid=5091933 (如果有錯，值為負，請參考錯誤代碼。表一)

如果Vender有於簡訊的request中的response欄位填入Vender接收回報程式的URL
(即response= http://回報網址/response.php)

那麼收到回報內容參數舉例如下：
kmsgid=5091933&dstaddr=0961000001&dlvtime=20070101120000&donetime=
20070101120010&statusstr=DELIVRD (不限於只有這些Tag，擴充用，詳見表二)

response.php接收回報程式範例：(此檔案不需額外製作己附於壓縮檔內 )
$res="kmsgid=".$_REQUEST[“kmsgid”]."\tdstaddr=".$_REQUEST[“dstaddr”]."\tdlvtime=".
$_REQUEST[“dlvtime”]."\tdonetime=".$_REQUEST[“donetime”]."&\tstatusstr=".$_REQUEST[“statusstr”];
$fp = fopen("retccmoapi.txt","a+");
fwrite( $fp, $res);
fclose($fp);
?>

response.asp接收回報程式範例：(此檔案不需額外製作己附於壓縮檔內 )
<%
res="kmsgid="&Request("kmsgid")&" dstaddr="&Request("dstaddr")&" dlvtime="&Request("dlvtime")&
" donetime="&Request("donetime")&" statusstr="&Request("statusstr")

FimeName=server.mappath("retccmoapi.txt")
set fso = server.CreateObject("Scripting.FileSystemObject")

If (fso.FileExists(FimeName)) Then
Set f = fso.OpenTextFile(FimeName, 1)
ReadAllTextFile = f.ReadAll
end if

Set f = fso.CreateTextFile(FimeName,True,False)
f.Write ReadAllTextFile & res & vbcrlf

set fso = nothing
set f = nothing
%>
※請注意當您發送api簡訊後 response.php 資料夾旁將會自動產生response.txt 檔案，此檔案內容為
『簡訊發送狀態』所接收的SMSC訊息狀況，也是您網站上發送狀態顯示所需呼叫的SMSC訊息狀況。
※須將檔案寫入功能開啟設定為777 (權限全開)

( 回覆狀態顯示:將依系統商現在回覆狀態自動更新 )

response 內文說明:
kmsgid= 簡訊發送編號 (請以此編號核對發送結果)
dstaddr= 接收門號
dlvtime= 電信系統發出時間
donetime= 手機用戶端回報狀態時間(包含成功發送,無法投遞….等狀態)
3.錯誤代碼（kmsgid）表一

-1	CGI string error ，系統維護中或其他錯誤 ,帶入的參數異常,伺服器異常
-2	授權錯誤(帳號/密碼錯誤)
-4	A Number違反規則發送端 870短碼VCSN 設定異常
-5	B Number違反規則接收端門號錯誤 -
-6	Closed User 接收端的門號停話異常090 094 099 付費代號等
-20	Schedule Time錯誤預約時間錯誤或時間已過
-21	Valid Time錯誤有效時間錯誤
-1000	發送內容違反NCC規範
-59999	帳務系統異常簡訊無法扣款送出
-60002	您帳戶中的點數不足
-60014	該用戶已申請拒收簡訊平台之簡訊 ( 2010 NCC新規)
-999949999	境外IP限制(只接受台灣IP發送，欲申請過濾請洽簡訊王客服)
-999959999	在12 小時內，相同容錯機制碼
-999969999	同秒, 同門號, 同內容簡訊
-999979999	鎖定來源IP
-999989999	簡訊為空
3	無法投遞，簡訊無法送達對方
12	拒收簡訊，該用戶無法接受簡訊
41	發送內容違反NCC規範
43	無法投遞，該用戶號碼為空號
48	拒收廣告，該用戶要求拒收企業簡訊

※無備註說明kmsgid之錯誤訊息，請連絡簡訊王

4.常見SMSC訊息狀況摘錄－表二

Message State	Final Message States	Description
DELIVERED	DELIVRD	成功發送確定該手機已收到簡訊且回應狀態。
EXPIRED	EXPIRED	逾時未達該門號手機一直未開機、或收不到訊號，系統已重複發送8~24小時，仍然無法傳送簡訊給該門號。
DELETED	DELETED	刪除簡訊指該簡訊違反台灣現有法規(禁用字)，此簡訊已被系統刪除，將不再發送。
UNDELIVERABLE	UNDELIV	無法投遞可能是簡訊收件夾已滿或無法於8~24小時內重複發送…等問題。
ACCEPTED	ACCEPTD	發送失敗電信業者回覆告知發送失敗。此狀態為該簡訊送達門號有異常，例如:空號、停話、號碼不存在…等。※簡訊內容出現NCC規定【禁用字】時,將造成『全數發送失敗』※
UNKNOWN	UNKNOWN	未知情形此狀態為系統商與系統商之間資料交換失敗皆統稱未知情形。
REJECTED	REJECTD	拒收簡訊該接收門號拒收簡訊。
SYNTAXERROR	SYNTAXE	語法錯誤發送簡訊語法錯誤，編碼錯誤或發送號碼為付費手機門號(0948)…等。

註記：發送狀態"紅色字樣" 皆不予計費
Final Message States為Phase II中statusstr的值

簡訊發送點數計算方式
70個字以內-----扣1點
134個字以內----扣2點
201個字以內----扣3點
268個字以內----扣4點
335個字以內----扣5點
若使用長簡訊發送時，當其中一則發送失敗時，該筆簡訊將判定為發送失敗，點數全部補回。
國際簡訊以3倍計點 (70個字以內------扣3點….依此類推)

簡易api發送範例: ( 請自行下載解壓縮後檢視程式原始碼 )
http://kotsms.com.tw/0000/api-1.zip

完整版API文件下載點 http://kotsms.com.tw/0000/smsking%20api.zip