帳號
密碼
.................(忘記密碼?

簡訊王FB粉絲專頁



 

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

簡訊王數位媒體   API協定說明(HTTP)
版本: 2024/ 02/ 07 新增 觸及詐騙常用關鍵字預防性停權代碼-9999799998
版本: 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.0)

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
以及空格 全形數字123以及長達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 拒收廣告,該用戶要求拒收企業簡訊
-9999799998 常用關鍵字預防性停權


※無備註說明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介接需申請”雙向簡訊專屬簡訊門號”(3600元/年)
介接測試期間您可使用測試帳號api01所配置的專屬門號,暫不需申請。
介接方式有如上述的”response”成功、失敗接收機制,您只需登入簡訊王網頁設定回報位置以及安裝接收檔案,
即可產生接收檔案,並可接收客戶所回覆的簡訊內容以及時間。

※雙向API服務僅提供收發機制,若需其他自動判斷、回覆機制需由API工程師自行撰寫※
srcaddr=傳訊來源門號
dstaddr=傳訊目的門號
smbody=簡訊內文
encoding=簡訊內文編碼格式
ctime=接收時間

登入帳密後的雙向設定畫面:

雙向簡訊接收程式:
<?
$ctime=date("Y-m-d H:i:s"); $res="srcaddr=".$_REQUEST["srcaddr"]."\tdstaddr="
.$_REQUEST["dstaddr"]."\tsmbody=".$_REQUEST["smbody"]."\tencoding=".$_REQUEST
["encoding"]."\tctime=".$ctime;
$FileName=date("Y-m-d").'.txt';
$fh=fopen($FileName,"a+");
fwrite($fh,$res);
fclose($fh);
?>

會員剩餘點數查詢說明(HTTP)
1.介面說明

利用HTTP協定中Get Method來發送簡訊,其參數如下:
URL格式為https://api.kotsms.com.tw/memberpoint.php?Tag=Value&Tag=Value…

Tag清單如下:


Teg 義義
username 會員帳號
password 會員密碼

2.範例
條件
帳號 TesterId
密碼 TesterPassword

送出需求:

https://api.kotsms.com.tw/memberpoint.php?username= TesterId &password= TesterPassword
收到數值:
12345
(如果有錯,值為負,請參考錯誤代碼。表一)
3.錯誤代碼 (表一) 
-2 授權錯誤(帳號/密碼錯誤)
※無備註說明負值之錯誤訊息,請連絡本系統之負責人 
會員發送簡訊狀態查詢說明(HTTP)
1.介面說明 
利用HTTP協定中Get Method來發送簡訊,其參數如下: 
URL格式為: 
https://api.kotsms.com.tw/msgstatus.php?Tag=Value&Tag=Value… 
Tag清單如下: 
Tag 意義
username: 帳號
password: 密碼
kmsgid: 傳送簡訊時收到的記錄編號
   
 

2.範例
條件
帳號 TesterId
密碼 TesterPassword
記錄編號 28915004
送出查詢: 
https://api.kotsms.com.tw/msgstatus.php?username= TesterId &password= TesterPassword &kmsgid= 28915004 
收到回覆: 
statusstr=SUCCESSED   
 
API安全機制說明
1 API金鑰說明(apikey)
2 固定IP申請鎖定


  API金鑰說明(apikey)
1.介面說明 
 
 
與簡訊王客服申請後簡訊王前台功能會新增API金鑰功能
 
按下變更金鑰後系統將產生特殊金鑰更新
 
API端的調整部份
 
原語法下列為API運用範例
 
password
更換為 
 
apikey
 
即可使用
 
註:api金鑰的功能僅運用在保護api被攔裁不會讓密碼直接被竊取

【各電信業者客服電話】
1.中華
市話客服 123 或 0800 080 123
行動客服專線0800-080-090→輸入手機門號後再轉9至客服
2.遠傳
市話撥 0800-058-885
服務專線:0936-000-999 (使用遠傳門號撥打免費)
3.台哥大
用戶手機免費撥打188或02-66062999


     
 
簡訊王數位媒體有限公司 統一編號:28321094 地址:台北市內湖區新明路298巷10號8樓 電話:02-2792-3939 傳真:02-2792-6262
Copyright © by SMS King Digital Media Co., Ltd.  Designed by SMS King