國際富信API接口規範-UNALv0.2

國際富信API介面規範

1文檔說明

1.1文檔目的

該文檔是面向第三方客戶提供國際富信消息發送的相關API介面調用規範。

1.2適用範圍
本文檔適用於國際富信客戶側業務系統相關富信發送業務場景所需的介面調用。

1.3參考文檔
超文本傳送協議（Hypertext Transfer Protocol） -- HTTP/1.1---RFC 2616
HTTP鑒權(HTTP Authentication: Basic and Digest Access Authentication)--RFC2617
<>
Constrained RESTful Environments (CoRE) Link Format –RFC6690

2協議規範

國際富信服務介面主要包含：認證服務、富信網關和狀態通知三類服務介面，本介面規範遵循RESTful API標準，採用當前流行的微服務2.0技術架構，以HTTP/HTTPS協議方式對外提供服務介面。介面遵循的RESTful架構也是目前較為流行的一種互聯網軟體架構，它具有結構清晰、符合標準、易於理解、擴展方便等優點，從而被得到廣泛使用。

2.1協議說明
RESTFul API介面常見的Body格式有三種：
application/json
JSON報文消息格式。
application/x-www-form-urlencoded
form表單提交的消息格式。
multipart/form-data
多檔上傳的消息格式。
國際富信發送服務目前只支持application/json的形式。

2.2介面約定
介面中的普通時間格式均約定為yyyy-MM-dd HH:mm:ss格式,採用 24 小時制，如2021-09-10 18:52:34
請求參數中時間戳格式均為14位yyyyMMddHHmmss日期格式，採用24小時制，如20131014120000。
介面請求和回應參數名稱均區分大小寫，介面傳輸過程中時應注意。
HTTP 協議，無特殊說明，實體內容及回應內容全部採用JSON 格式進行數據描述，並採用UTF-8 編碼。

2.3富信介面規範

國際富信客戶API介面主要分為：富信消息、狀態通知兩類服務介面。其中富信消息介面由國際富信平臺提供，狀態通知介面由客戶側系統提供。

2.3.1介面地址
http://{IP地址}:{端口}/{service}/openapi/{func}
其中：
service:服務主目錄，可動態配置，也可用於微服務部署模式對應的服務名稱。
openapi：介面地址中規定的中間路徑

{func}：介面所定義的業務路由路徑或介面指令名稱。
示例：http://127.0.0.1:8900/grms/openapi/rmssend

2.3.2消息格式
介面消息格式分HTTP頭、請求消息、回應消息三方面進行說明，其中回應消息統一為當前主流的JSON包體報文格式。

2.3.3HTTP消息頭
在進行HTTP/HTTPS請求時，必須根據本介面協議規範進行HTTP頭標記資訊的填充。該文檔此處僅對HTTP協議擴展頭標記進行簡單說明：

HTTP 頭	選項	說明
ContentType	必填	內容格式資訊與編碼。這裏規定為application/json 表示傳輸內容為文本JSON格式，字元編碼統一為UTF-8格式。未填寫情況下服務介面默認以URL方式進行解碼。
User-Agent	可選	用戶代理類型，一般用於標識流覽器類型版本資訊。這裏僅用於標識介面請求來源類型
Token	可選	介面訪問令牌，僅用於令牌認證模式，富信發送服務介面支持令牌認證和簽名認證兩種方式，由富信發送服務配置決定。前期僅考慮簽名認證模式。採用簽名認證模式該參數可忽略不填。

2.3.4請求消息
HTTP消息頭中Content-Type類型不同，請求消息格式不同。具體可參見第4章節介面定義部分。其中
當Content-Type為application/json時請求消息示例：

 {
    "custom_id":"20210722124041000001",
    "account":"JK0130",
    "sign":"016edd3f94405876bd303449724935a4",
    "req_time":"2021-07-22 12:40:41",
    "timezone":"+0800"
}

2.3.5回應消息

服務介面回應數據包均為JSON格式。回應消息內容分為邏輯上分為回應消息頭和消息體兩部分，其中消息體為動態格式。

回應消息頭部分：包含code、desc元素標記
code：回應狀態碼，僅用於表示介面調用結果情況的標識，不代表真正的業務執行結果。業務執行的結果依賴於data包體中的相關定義來做標識。code狀態碼的定義延續HTTP請求狀態碼的定義，但用法有所差異。HTTP狀態碼是協議層面的，code是介面調用層面的，其中0為成功，其他為失敗原因代碼，具體請參見附錄中的狀態碼定義。
desc：回應提示資訊，比如請求失敗的具體原因描述等。

回應消息內容部分：包含回應內容元素標記

當code為0時，根據具體的報文說明處理相關的字段資訊；
當code非0時，則無須關注其他字段的內容
回應示例：

{ "code":0, "desc":"ok", "file_id":"578106112816451584", "url":"http://file.io/rc/578106112816451584"

}

2.4安全簽名機制

安全簽名機制是面向對簽名認證模式的一種安全簽權演算法，本文僅針對介面定義章節的相關介面有效，具體規則如下：
介面請求中的參數除sign外其他已填參數以參數名作為key進行ascii字母順序排序，然後將值(json對象、json數組不參與拼接)直接進行拼接開頭加上”{appid}”變數值末尾加上”{apikey}”值進行拼接，將拼接結果進行MD5摘要得到簽名資訊。

介面生成簽名示例如下：
account =”JK0100”
custom_id =”2021072212000000100001”
req_time =”2021-07-22 12:00:00”
message_id =”6853212118188288
msisdn =”85212341234”
//參數排序URL拼接：
String parametersStr=”JK0100”
+”2021072212000000100001”
+”6853212118188288”
+”85212341234”
+”2021-07-22 12:00:00”
);
//生成安全簽名資訊：
String sign=MD5( appid+parametersStr+apikey);
注意：實際使用中請嚴格控制appid、apikey的洩漏，避免造成不必要的損失。

3介面定義

3.1富信消息

3.1.1範本消息發送介面

請求地址	/grms/openapi/rmssend
功能說明	範本消息發送介面。主要用於富信控制臺和客戶側系統調用，具有高頻次、大流量調用特性。
認證方式	簽名認證

輸入參數：

參數名稱	類型	說明
account	string	發送簽權帳號，必填，介面調用的API帳號
sender	string	SENDERID，必填，自動檢測字母-數字，是否攜帶國家碼
msisdn	string	目標手機號碼，含國家碼，必填。
check_dnc	integer	是否拒收登記冊檢查，必填 0-不過拒收登記冊檢查 1-需要拒收登記冊檢查
title	string	富信主題，必填，實際展示以該字段展示富信主題。
template_id	string	範本編號，非必填。當未填寫範本編號時，則按順序排列參數拼接內容進行發送。
tag	string	標籤，非必填，用於標注業務場景、類型或用途
parameter	jsonarray	參數對象數組，非必填， template_id不存在時，參數個數限制在8個以內。其格式參見下方parameter對象格式說明
send_type	integer	發送方式： 1-即時發送 2-定時發送
send_time	string	定時發送時間，非必填，格式：yyyy-MM-dd HH:mm:ss 1） send_type=1，即時發送時無須填寫； 2） send_type=2，定時發送時必須填寫；若定時發送時間小於伺服器時間或未填寫該字段，消息將立即發送，其他情況按填充時間進行定時發送。若定時發送時間大於當前不足1分鐘，則按及時發送方式進行發送。
send_timezone	string	時區，選填，格式：+HHmm，默認+0800
custom_id	string	客戶請求方唯一流水號，選填。限定64位ASCII字元。
sign	string	簽名資訊，簽名方式必填，具體可參見2.5安全簽名機制

parameter對象格式

參數名稱	類型	說明
name	string	參數名，必填，用於匹配範本中參數占位符。
type	integer	參數類型，必填 1-文本 2-圖片 3-音頻 4-視頻
suffix	string	檔擴展名文本：txt 圖片：jpg/jpeg、gif、png 音頻：mp3、acc 視頻：mp4(必須是H.264編碼)
value	string	參數值： 1）當type為1時，value值內容有效，即實際文本內容； 2) 當type非1時，其值內容為圖片或音頻或視頻進行base64編碼的字串，非必填。 3）如url非空情況下將優先使用url指示的地址進行下載。
url	string	參數資源地址，非必填，若填寫，則從該地址下載參數值進行範本拼接組裝。

注意事項：
1、所有參數總和加上範本大小不超過1.9MB
2、為確保視頻內容清晰度，建議視頻播放時間不超過33秒
3、請求參數模版編號為空的情況，適用於無須創建模版直接通過參數進行拼接模版的情況，建議慎用。

輸出參數：

參數名稱	類型	說明
code	integer	消息接收狀態 0-成功其他-失敗，見錯誤碼表
desc	string	描述資訊
message_id	string	消息編號
custom_id	string	調用方請求流水號，將請求中custom_id原值返回；請求報文未填寫時，使用message_id填充

報文示例：

CURL請求示例：
curl http://host:port/grms/openapi/rmssend -s -H"Content-Type:application/json" -d

 '{
  "account": "USR007",
  "custom_id": "1634113718787",
  "sender": "MontRMS",
  "msisdn": "852xxxxx",
"check_dnc": 0,
  "template_id": "",
  "tag": "",
  "title": "Montnets RMS",
  "sign": "xxxxxxxxxxxxxxx",
  "parameter": [
    {
      "name": "1.png",
      "url": "1.png.url",
      "type": 2,
      "suffix": "png"
    },
    {
      "name": "1.mp4",
      "url": "1.mp4.url",
      "type": 4,
      "suffix": "mp4"
    },
    {
      "name": "1.txt",
      "value": "Max number of connections to a single broker that is kept in the pool",
      "type": 1,
      "suffix": "txt"
    }
  ],
  "send_time": "",
  "send_timezone": "+0800",
  "send_type": 1
}'

回應示例：

 {
  "code": 0,
  "desc": "ok",
  "message_id": "6868856361645170690",
  "custom_id": "1634113718787"
}

3.1.2檔上傳接口

請求地址	/grms/openapi/fileupload
功能說明	富信範本參數檔上傳接口。
認證方式	簽名認證

輸入參數：

參數名稱	類型	說明
account	string	消息發送用戶ID必填
md5	string	檔md5摘要
name	string	檔案名稱
mime	string	ext/richtext text/html image/tiff image/jpeg image/gif audio/mid video/mpeg application/octet-stream
value	string	檔內容base64
sign	string	簽名資訊，具體可參見2.5安全簽名機制

輸出參數：

參數名稱	類型	說明
code	integer	檔接收狀態 0-成功其他-失敗，見錯誤碼表
desc	string	描述資訊
file_id	string	檔編號
url	string	檔下載地址

CURL請求示例：
curl http://HOST:PORT/grms/openapi/fileupload -s -H"Content-Type:application/json" -d

 '{"name":"curltest.txt", "mime":"text/plain","value":"Y3VybCBodHRwOi8vMTkyLjE2OS4yLjE4OTo4MDgzL3JzYy9vcGVuYXBpL3IvdXBsb2FkIC1kIC1IQ29udGVudC1UeXBlOmFwcGxpY2F0aW9uL2pzb24geyJuYW1lIjoiY3VybHRlc3QudHh0IiwgIm1pbWUiOiJ0ZXh0L3BsYWluIiwidmFsdWUiOiIiLCJzaWduIjoieHgiLCJtZDUiOiJ4eHgifQo=","sign":"xx","md5":"xxx"}'

回應示例：

{
  "file_id": "6868858389289164868",
  "url": "http://host:port/6868858389289164868",
  "code": 0,
  "desc": "ok"
}

3.2狀態通知

回調給客戶側的狀態通知介面，該部分介面由客戶側實現，用於接收消息發送狀態、下載狀態的回調通知。如客戶側不提供服務介面，視為不接收狀態報告。

3.2.1通知消息狀態報告介面

請求地址

由客戶側提供

功能說明

推送富信消息發送的狀態報告資訊到客戶側，狀態報告反映了富信短信通知消息是否有送達到用戶手機終端。狀態報告推送失敗會進行重推。

重推機制：推送失敗後會按指定時間間隔進行重推；最多重推指定次數後若不成功則丟棄。

時間間隔默認3分鐘；最大重推次數默認5次；可以根據實際情況進行調整。

認證方式

簽名認證

3.2.1通知消息狀態報告介面

輸入參數：

參數名稱	類型	說明
account	string	用戶帳號（同3.2.1章節範本消息發送介面請求參數中的帳號）
custom_id	string	調用側請求方流水號；若發送時未提交，填寫message_id；限定64位ASCII字元。
message_id	string	消息流水號
sender	string	最終手機展示的sender ID。
msisdn	string	手機號碼，含國家碼，必填。
recv_time	string	狀態報告返回時間： YYYY-MM-DD HH:MM:SS
recv_timezone	string	時區，選填，格式：+HHmm，默認+0800
state	integer	接收狀態： 0：失敗 1：成功 2：待返(查詢可見)
sign	string	簽名資訊，具體可參見2.5安全簽名機制

輸出參數：

參數名稱

類型

說明

code

integer

檔接收狀態

0- 失敗

1- 成功

3.2.2消息下載狀態報告介面

請求地址	由客戶側提供
功能說明	推送下載狀態報告到客戶側系統。下載狀態報告反映了富信模版消息是否被終端用戶點擊下載或自動下載過。其失敗重推機制同3.3.1章節。
認證方式	簽名認證

輸入參數：

參數名稱	類型	說明
account	string		用戶帳號（同3.2.1章節範本消息發送介面請求參數中的帳號）
custom_id	string		調用側請求方流水號，選填。限定64位ASCII字元。
message_id	string		消息流水號
sender	string		senderID
msisdn	string	手機號碼(含國家碼)
download_time	string	下載時間，非必填，超時未下載時不填寫。格式如：yyyy-MM-dd HH:mm:ss
download _timezone	string	時區，選填，格式：+HHmm，默認+0800
download_state	integer	下載狀態 0：失敗 1：成功 2：待返(查詢可見)
sign	string	簽名資訊，具體可參見2.5安全簽名機制

輸出參數：

參數名稱

類型

說明

code

integer

檔接收狀態

0-失敗

1-成功

4附錄說明

4.1代碼定義

4.1.1數據類型

類型	說明
string	字串型
integer	整型
double	浮點型
long	長整型
JSONObject	JSON對象
JSONArray	JSON數組

4.1.2回應代碼
這裏主要針對2.3.5回應消息頭中的code元素所對應的狀態碼進行說明

狀態碼及範圍	說明
300~399	通信協議層相關校驗的狀態碼範圍，該錯誤代碼範圍內的請求記錄不產生入庫記錄。避免非法無效請求產生大量無效請求。一般用於調用側或存在後向服務請求的場景。
400~410	介面請求安全許可權認證非法的錯誤碼範圍，該錯誤代碼情況下，請求消息不做入庫記錄。
500~510	網路錯誤代碼範圍，主要為上下游調用時所產生的相關網路錯誤代碼。
1000-99999	該範圍內的錯誤代碼為富信發送務業務處理邏輯過程中產生的錯誤代碼。

如下僅對與富信發送業務相關錯誤代碼進行具體定義：

錯誤代碼	說明	排查方法
10001	請求頭錯誤	應正確填寫 Content-Type:application/json
10002	請求數據Body錯誤	請求數據錯誤,非法的JSON格式,參數與約定協議不符等
10003	請求必填字段缺失	請求參數字段缺失,請確認所有必填參數是否填寫
10004	請求必填字段值類型錯誤	請求必填字段值類型錯誤
10005	簽名錯誤	請求攜帶的簽名校驗失敗
20003	企業發送限量攔截發送超限	富信發送量超限,聯繫管理員充值
20004	sender不可用	請求攜帶的SENDER非法不可用
20005	用戶不存在	請求發起者用戶資訊不存在
20006	號碼非法	號碼非法請檢查確認是否正確攜帶國家碼,號碼長度最長21位
20007	任務被取消	定時任務被取消
20008	拒收登記攔截	目標號碼在拒收登記冊內攔截
-	其他錯誤碼	請聯繫服務提供者核查確認