LINK 移动实施指南 REST API SMS
LINK Mobility 提供信息传递、小额支付和基于位置的服务。该平台充当服务提供商和运营商之间透明的白标内容获取者和交易路由器。
LINK Mobility 提供了一个 RESTful API，可用于访问 LINK Mobility 服务，例如发送短信。此 API 旨在易于使用并与所有现代语言和框架兼容。使用您选择的语言，您的应用程序可以使用 Link Mobility REST API 来实现强大的消息传递和支付功能
© LINK Mobility，10 年 2021 月 XNUMX 日
法律信息
本文档中提供的信息是 Netsize 的唯一财产和版权。它是保密的，仅供参考。它不具约束力，可能会随时更改，恕不另行通知。任何未经授权的披露或使用均视为非法。
Netsize™ 和 linkmobility™ 受法国、欧洲经济共同体和国际知识产权法的保护。
所有其他引用的商标均为其各自所有者的独有财产。
本文包含的任何内容不得解释为授予 Netsize 专利、版权或商标下的任何许可或权利。
网尺寸
Société anonyme au Capital de 5 478 070 欧元
Siège Social :62, avenue Emile Zola92100 Boulogne – 法国
418 712 477 RCS 楠泰尔
http://www.LinkMobility.com
http://www.linkmobility.com
文件范围
本文档介绍了服务提供商如何使用 LINK Mobility REST API 进行 SMS 操作。本文档面向实施服务提供商服务的技术架构师和设计师。
1. 基本用法
发送短信非常简单。你只需向 LINK Mobility 发送一个 HTTP 请求即可完成 web 瀏覽器。
2. 功能结束view
LINK Mobility 系统为短信提供以下基本功能：
发送移动终止 (MT) SMS 消息，例如文本或二进制（例如 WAP Push）付费和标准费率消息。
接收已提交的 MT 消息的传递报告。
接收移动发起（MO）短信，收费和标准费率。
SMS REST API 专用于发送标准速率的 MT SMS 消息。
该 API 异步发送所有短信，从而实现以下功能：
“发射后不管”——服务提供商希望有更可预测的响应时间，而不想等待运营商的结果。
重试功能——如果运营商遇到暂时问题，LINK Mobility 将重新发送消息。
2.1 发送短信
服务提供商 网络规模 消费者
- 发送 MT 消息
- 返回消息ID
- 提交短信
- 递送发货报告
- 发送送达报告
发送短信的基本流程如下：
服务提供商请求通过 LINK Mobility 系统向收件人发送短信。
向服务提供商返回一个消息 ID。此 ID 可用于将消息与正确的传递报告关联起来。
LINK Mobility 负责路由并将短信传递给目标消费者。
例如当短信传送到消费者的设备时，就会触发传送报告。
送达报告将发送给服务提供商。报告包含与步骤 2 中返回的相同的消息 ID。
替代流程：请求无效
如果请求中提供的参数或用户凭据无效，则向服务提供商返回错误。错误表明拒绝的原因，流程结束。不返回任何消息 ID。
3. 端点
使用以下路径访问 SMS 资源：
/restapi/v1/短信
Example URL
https://europe.ipx.com/restapi/v1/sms
为了连接安全，LINK Mobility REST API 只能通过 HTTPS 访问。
Link Mobility 服务器证书由 Thawte Server CA 签名。
4. 运营
短信服务提供以下操作：
| 姓名 | 小路 |
| 发送 | /restapi/v1/短信/发送 |
4.1 发送
发送操作用于向单个收件人发送短信。
此操作适用于基础用户和高级用户。在最简单的情况下，只需目标地址和消息文本即可发送短信。LINK Mobility 将检测数据编码方案，并在必要时自动将消息串联成多个消息部分。
对于高级用法，服务提供商可以使用可选参数来完全控制消息格式，包括用户数据头。
服务提供商可以发送串联消息，但服务提供商必须准备用户数据和用户数据头，并且必须通过多个发送请求向 LINK Mobility 发送消息。
5. 身份验证
使用 HTTP 基本身份验证方案在每个请求中提交用户名和密码。
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
凭据在 HTTP 请求的授权标头中发送。客户端按如下所述构造标头字段：
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
例如amp例如，如果用户名是 john，密码是 changeme，那么生成的授权标头是：
授权：Basic am9objpjaGFuZ2VtZSA=
作为备用方案，用户名和密码可以作为请求参数提交。这仅推荐用于不支持基本身份验证的客户端。
6. 提交请求
6.1 查询字符串
请求参数以包含名称/值对的查询字符串形式提交。查询字符串使用百分比编码 (URL 编码）。
http://www.w3schools.com/tags/ref_urlencode.asp
例如ample，Hello World！编码为Hello+World%21。
6.2 强制请求参数
| 姓名 | 最大长度 | 描述 |
| 目的地地址 | 40 | SMS 消息应发送到的 MSISDN，以国家代码开头。例如amp乐：46123456789。 对于某些市场（必须对消费者 MSISDN 进行混淆），该值也可以是字母数字别名，以“#”为前缀。 |
| 信息文本 | 1600 | 短信内容。 |
6.3 可选请求参数（高级用法）
| 姓名 | 最大长度 | 描述 |
| 起始地址 | 16 | 发送 SMS 消息的发送地址。发送地址的类型由 originatorTON 参数定义。 短号码最大长度为 16。 字母数字发送器仅限于 GSM 默认字母，最大长度为 11 个字符。 MSISDN 发送方最大长度为 15（使用与目标地址元素相同的格式）。 当系统选择 originatingAddress 和 originatingTON 时，可以省略。此功能取决于市场和配置。 行为可能因运营商集成而异。 |
| 发起者TON | 1 | 发起地址的数字类型（TON）： 0 – 短号码 1 – 字母数字（最大长度 11） 2 – MSISDN 当系统选择 originatingAddress 和 originatingTON 时，可以省略。此功能取决于市场和配置。 行为可能因运营商集成而异。 |
| 用户数据头 | 280 | 用户数据头与用户数据一起最多可包含 140 个八位字节，即十六进制编码时为 280 个八位字节。此参数始终采用十六进制编码。 |
| 分布式控制系统 | 3 | 数据编码方案。 行为可能因运营商集成而异。 |
| PID | 3 | 协议ID。 行为可能因运营商集成而异。 |
| 相对有效时间 | 6 | 相对有效时间（以秒为单位）（相对于提交给 LINK Mobility 的时间）。最大值为 604800（7 天），默认值为 48 小时。 行为可能因运营商集成而异。 |
| 交货时间 | 20 | 时间amp 何时发送短信（延迟发送时间）。请参阅日期时间格式部分。 |
| 状态报告标志 | 1 | 提交报告请求： 0 – 无送达报告（默认） 1 – 请求交付报告 9 – 请求服务器交付报告（LINK Mobility 不会将报告转发给服务提供商，但会在报告等中提供报告） |
| camp署名 | 50 | LINK Mobility 交易是 tag使用此名称对事务进行分组。它用于对 Link Mobility 报告中的事务进行分组。 |
| 最大连接消息数 | 1 | 1 到 10 之间的值，定义允许的串联消息数。默认值为 3。 |
| 相关编号 | 100 | 服务提供商提供的 ID 将在交付报告中显示。 |
| 用户名 | 100 | 作为 HTTP 基本身份验证的替代方案提供。 |
| 密码 | 100 | 作为 HTTP 基本身份验证的替代方案提供。 |
6.4 HTTP 请求方法
为了实现最大程度的互操作性，API 支持 HTTP GET 和 POST 请求方法。不允许使用其他 HTTP 方法。
6.4.1 获取
编码后的查询字符串将附加到 URL.
得到
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=你好+世界%21
授权：Basic am9objpjaGFuZ2VtZSA=
6.4.2 帖子
编码后的查询字符串在HTTP请求消息体中提交。Content-Type为application/x-www-form-url编码。
邮政 https://europe.ipx.com/restapi/v1/sms/send
主机：europe.ipx.com
内容类型：application / x-www-form-url编码
授权：Basic am9objpjaGFuZ2VtZSA=
内容长度：57
目标地址=46123456789&消息文本=Hello+World%21
6.5 日期和时间
REST API 中表示日期和时间的参数始终采用 UTC 时区（协调世界时）。Timestamps 表示为具有以下确切格式的字符串：
2017-04-25T23:20:50Z
这代表 UTC 时间 20 年 50 月 23 日 25 时之后 2017 分 XNUMX 秒。
7.响应消息
在接收并解释请求消息后，API 会使用 HTTP 响应消息进行响应。
7.1 HTTP 状态代码
对于已处理的请求，REST API 始终返回 HTTP 状态代码 200 OK。消息正文包含一个参数 responseCode，用于确定确切的结果。
7.2 消息体
消息正文由描述请求结果的 JSON 组成。
http://json.org/
Link Mobility JSON 符合 Google JSON 样式指南。
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 响应参数
| 姓名 | 最大长度 | 描述 |
| 响应代码 | 3 | 0代表交易成功。 |
| 响应消息 | 255 | 响应文本描述，例如错误文本。 |
| 时间amp | 20 | LINK Mobility 处理请求的日期和时间。（请参阅日期/时间格式部分）。 |
| 跟踪编号 | 36 | Link Mobility 内部标识符。用于支持和故障排除。 |
| 消息 ID | 10 x 36 | 每个成功消息的 LINK Mobility 唯一消息 ID 数组（如果消息连接在一起，则返回多个消息 ID）。 失败时省略。 |
第7.4章amp回应
成功
HTTP/1.1 200 正常
内容类型：application/json
内容长度：144
日期：15 年 2016 月 13 日星期四 20:31:XNUMX GMT
{“responseCode”:0,”responseMessage”:”成功”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
为了便于阅读，以下是相同的 JSON 格式：
{
“响应代码“：0，
“响应消息“：“成功”，
“时间amp“:”2016-0915T13:20:31Z”,
“跟踪编号“:”f678d30879fd4adc25f2”,
“消息 ID“:[“1-4850879008”] }
失败
HTTP/1.1 200 正常
内容类型：application/json
内容长度：148
日期：15 年 2016 月 13 日星期四 20:31:XNUMX GMT
{“responseCode”:1,”responseMessage”:” 无效登录或未授权的 API 使用”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
成功
HTTP/1.1 200 正常
内容类型：application/json
内容长度：144
日期：15 年 2016 月 13 日星期四 20:31:XNUMX GMT
{“responseCode”:0,”responseMessage”:”成功”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
为了便于阅读，以下是相同的 JSON 格式：
{
“响应代码“：0，
“响应消息“：“成功”，
“时间amp“:”2016-0915T13:20:31Z”,
“跟踪编号“:”f678d30879fd4adc25f2”,
“消息 ID“:[“1-4850879008”] }
失败
HTTP/1.1 200 正常
内容类型：application/json
内容长度：148
日期：15 年 2016 月 13 日星期四 20:31:XNUMX GMT
{“responseCode”:1,”responseMessage”:” 无效登录或未授权的 API 使用”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 响应代码
发送响应中可以返回以下响应代码：
| 代码 | 文本 | 描述 |
| 0 | 成功 | 已成功执行。 |
| 1 | 无效登录或未经授权的 API 使用 | 用户名或密码不正确或服务提供商被 LINK Mobility 禁止。 |
| 2 | 消费者被 Link Mobility 屏蔽 | 消费者被 LINK Mobility 阻止。 |
| 3 | LINK Mobility 未提供此操作 | 服务提供商阻止了该操作。 |
| 4 | LINK Mobility 不了解该消费者 | LINK Mobility 不了解消费者的情况。 或者如果在请求中使用了别名；则未找到别名。 |
| 5 | 消费者已在 LINK Mobility 中屏蔽了此服务 | 消费者已在 LINK Mobility 中阻止此服务。 |
| 6 | 不支持原始地址 | 不支持原始地址。 |
| 7 | 账户不支持 Alpha 发起地址 | 账户不支持 alpha 发起地址。 |
| 8 | 不支持 MSISDN 发起地址 | 不支持 MSISDN 原始地址。 |
| 9 | 不支持 GSM 扩展 | 不支持 GSM 扩展。 |
| 10 | 不支持 Unicode | 不支持 Unicode。 |
| 11 | 不支持状态报告 | 不支持状态报告。 |
| 12 | 所需功能不受支持 | 不支持发送消息所需的功能（除上述功能以外）。 |
| 13 | 超出内容提供商的最大节流率 | 服务提供商向 LINK Mobility 发送短信的速度太快。 |
| 14 | 帐户不支持协议 ID | 不支持协议 ID。 |
| 15 | 超出消息串联限制 | 连接消息的数量超出了请求的最大数量。 |
| 16 | 无法路由消息。 | LINK Mobility 无法路由该消息。 |
| 17 | 禁止时间段 | 不允许在时间段内发送消息 |
| 18 | 服务商账户余额过低 | 服务提供商因余额过低而被阻止 |
| 50 | 部分成功 | 向多个收件人发送短信时部分成功。 |
| 99 | 内部服务器错误 | 其他 Link Mobility 错误，请联系 LINK Mobility 支持以获取更多信息。 |
| 100 | 目标地址无效 | 目标地址（MSISDN 或别名）无效。 |
| 102 | 引用（链接）ID 无效 | 参考 ID 无效，可能参考 ID 已被使用、太旧或者未知。 |
| 103 | 帐户名无效 | 帳戶名無效。 |
| 105 | 服务元数据无效 | 服务元数据无效。 |
| 106 | 无效的发件地址 | 原始地址无效。 |
| 107 | 无效的字母数字发件地址 | 字母数字来源地址无效。 |
| 108 | 有效期无效 | 有效时间无效。 |
| 109 | 送货时间无效 | 交货时间无效。 |
| 110 | 消息内容/用户数据无效 | 用户数据（即短信）无效。 |
| 111 | 消息长度无效 | 短信长度无效。 |
| 112 | 无效的用户数据头 | 用户数据头无效。 |
| 113 | 数据编码方案无效 | DCS 无效。 |
| 114 | 协议 ID 无效 | PID 无效。 |
| 115 | 无效状态报告标志 | 状态报告标志无效。 |
| 116 | 无效 TON | 发起方 TON 无效。 |
| 117 | 无效 camp签名名称 | camp签名名称无效。 |
| 120 | 串联消息的最大数量限制无效 | 串联消息的最大数量无效。 |
| 121 | 无效的 msisdn 原始地址 | MSISDN 原始地址无效。 |
| 122 | 关联 ID 无效 | 关联 ID 无效。 |
8. 可选功能
8.1 MSISDN 更正
MSISDN 更正是一项可选功能，如果需要，可以由 LINK Mobility 支持启用。
此功能将更正目标地址并将其与所需的 E.164 格式对齐。除了格式更正之外，系统还可以执行特定于市场的功能，例如在适用的情况下将国际法语号码转换为更正的 DOM-TOM（海外省和领土）号码。
以下是一些示例amp修正内容：
| 提交的目的地址 | 更正的目的地址 |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 （法语编号转换为 DOM-TOM 编号） |
此外，还可以允许选定市场使用国内电话号码。启用此功能后，其他市场的任何国际号码都必须以“+”符号开头，以区别于选定市场。
下面是几个前amp当使用瑞典（国家代码 46）作为国家号码的默认市场时所做的更正。
| 提交的目的地址 | 更正的目的地址 |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | 由于缺少“+”号，因此无效 |
请注意，LINK Mobility 将使用更正后的 MSISDN，并将在传送报告中返回。
请联系 LINK Mobility 支持以获取更多信息。
8.2 字符替换
角色替换是一项可选功能，如果需要，可以由 LINK Mobility 支持启用。
当 DCS 设置为“GSM”(17)时，此功能将把用户数据（短信文本）中的非 GSM 字母字符转换为等效的 GSM 字母字符。例如amp“Seqüência de teste em Português”将被翻译为“Seqüencia de teste em Portugues”。
9. 发货报告
服务提供商可以（如果已配置）请求发送的 MT 消息的 SMS 消息传递报告或传递通知。当 MT 消息已传递至目标消费者或被删除（例如已过期或由于某种原因无法路由）时，运营商 SMSC 会触发这些报告。
仅向服务提供商报告 SMS 消息的最终状态，即已发送或已删除。每条 MT 消息仅生成一份报告。对于已删除状态，可能适用原因代码。此原因代码指定 SMS 消息未发送的原因。
报告通过 LINK Mobility 路由并使用 HTTP 协议发送给服务提供商。
为了接收报告，服务提供商需要实施ample Java Servlet 或 ASP.NET 页面。两者都接收 HTTP GET 或 POST 请求。
参数
该请求包含以下参数：
| 范围 | 类型 | 主/副/进口* | 默认值 | 最大长度 | 描述 |
| 消息 ID | 细绳 | M | – | 22 | 该报告对应的MT消息的消息ID。 |
| 目的地址 | 细绳 | M | – | 40 | 消费者的MSISDN，即原始MT消息的目的地址。 |
| 状态码 | 整数 | M | 1 | 状态代码表示 MT 消息的状态。 适用的状态代码为： 0 – 已交付 2 – 已删除（适用原因代码） |
|
| 时间圣amp | 细绳 | M | – | 20 | 指示 LINK Mobility 收到传送报告的时间。 当前时区amp 是 CET 或 CEST（按照欧盟定义的夏令时）。 格式：yyyyMMdd HH:mm:ss。 |
| 操作员 | 细绳 | M | – | 100 | 发送短信时使用的运营商名称或发送短信时使用的账户名。 可用运营商列表由 LINK Mobility 支持提供。 |
| 原因代码 | 整数 | O | – | 3 | 原因代码表明消息最终为何处于已删除状态。 适用的原因代码为： 100 – 已过期 101 – 被拒绝 102 – 格式错误 103 – 其他错误 110 – 用户未知 111 – 用户被禁止 112 – 未配置订阅者 113 – 用户不可用 120 – SMSC 故障 121 – SMSC 拥塞 122 – SMSC 漫游 130 – 手机错误 131 – 手机内存超出范围 行为可能因运营商集成而异。 |
| 操作时间amp | 细绳 | O | – | 20 | 指示运营商 SMSC 中触发报告的时间（如果运营商提供）。 当前时区amp 是 CET 或 CEST（按照欧盟定义的夏令时）。 格式：yyyyMMdd HH:mm:ss。 |
| 状态文本 | 细绳 | O | – | 255 | 来自操作员的附加信息的占位符，例如状态/原因的明文描述。行为可能因操作员集成而异。 |
| 相关标识 | 细绳 | O | – | 100 | SendRequest 或 SendTextRequest 中提供的关联 ID。 |
| 运营商网络代码 | 整数 | O | – | 6 | 运营商的移动网络代码（MCC+MNC）。 |
* M = 强制，O = 可选，I = 忽略。
服务提供商必须向 LINK Mobility 提供目标 URL 用于传递报告（可选包括 HTTP 基本身份验证的凭据）。服务提供商可以选择使用哪种首选 HTTP 方法：
HTTP POST（推荐）
HTTP 获取。
Examp使用 HTTP GET（已成功传送）：
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Examp使用 HTTP GET（未交付，运营商已提供时间戳amp 活动）：
参数为 URL 编码i。
字符编码：
服务提供商可以选择使用哪种首选字符编码：
UTF-8（推荐）
ISO-8859-1。
9.1 服务提供商确认
服务提供商应该对每份递送报告进行确认。确认可以是肯定的，即成功收到递送报告，也可以是否定的，即失败。
请注意：LINK Mobility 的交付报告确认读取超时为 30 秒。超时将触发交付重试（如果启用重试）或取消交付（如果禁用重试）。这意味着服务提供商应用程序必须确保快速响应时间，尤其是在高负载期间。
强烈建议在处理之前向 LINK Mobility 确认交付报告。
肯定和否定确认的规则描述如下：
肯定确认（ACK），已发送送达报告：
HTTP 200 范围响应代码与以下 XML 格式的内容结合：
否定确认（NAK）、送达报告未送达：
除了积极确认之外的任何回复，例如ample，任何 HTTP 错误代码或以下 XML 内容都会触发否定确认：
XML 内容可用于控制 LINK Mobility 重试机制。如果启用，NAK 将导致重试尝试。对于未配置重试机制的服务提供商，XML 内容是可选的。
下面是 HTTP POST 请求和响应示例amp发送给服务提供商的交付报告文件：
HTTP 请求：
POST /上下文/应用程序 HTTP/1.1
内容类型：application / x-www-form-url编码；字符集=utf-8
主机：服务器：端口
内容长度：xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia&OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP 响应：
HTTP/1.1 200 正常
内容类型：text/plain
9.2 重试
LINK Mobility 系统可以对失败（即未确认）的交付报告交付执行重试尝试。服务提供商可以选择首选的重试行为：
不重试 （默认）——如果连接尝试失败、读取超时或出现任何 HTTP 错误代码，则消息将被丢弃。
重试 – 对于每种类型的连接问题、读取超时或否定确认，都会重新发送消息。
启用 NAK 重试后，了解哪些场景会导致 LINK Mobility 重试以及重试的工作原理非常重要。每个服务提供商都有自己的重试队列，其中的消息按照消息时间戳排序amp。Link Mobility 总是尝试先传递较旧的消息，即使无法保证传递给服务提供商的消息的顺序。消息从重试队列中被丢弃的主要原因有两个：消息 TTL 过期或（理论上）重试队列已满。TTL 取决于运营商和帐户，即可能因运营商和/或消息类型而异，例如，高级 SMS 或标准费率 SMS 消息。
启用重试的服务提供商必须检查 MT 消息的唯一 ID，以确保该消息尚未被收到。
如果在处理交付报告期间发生错误，且错误原因为：暂时，例如数据库不可用，则应返回 NAK，服务提供商必须遵守这些简单规则。LINK Mobility 将重新发送该消息。
永久尝试和重试尝试都可能导致同一类型的问题，应该返回 ACK。例如ample，当消息无法正确解析或导致意外的运行时错误时。
采取相应措施将确保不会因重复发送递送报告而导致阻塞或吞吐量下降。
10. 实施技巧
1. 您可以使用您的 web 浏览器向 API 提交请求。这使得无需任何开发工具即可轻松探索和评估服务。
2. 建议使用 Chrome 或 Firefox 并配合 JSON 等扩展程序View 显示格式漂亮的 JSON。
3. 我们已经使用 SoapUI 来测试 POST、基本身份验证以及检查原始 HTTP 请求和响应消息。
4. cURL 工具对于使用基本身份验证提交 POST 请求非常有用。请参阅示例amp如下。
curl 邮政 \
-H “内容类型：application/x-www-form-url编码” \
-H“授权：基本 am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “目标地址=46123456789&messageText=Hello+World%21”
_______________
转变个性化通信
文件/资源
 |
LINK 移动实施指南 REST API SMS [pdf] 用户指南 移动性实施指南 REST API SMS、移动性、实施指南 REST API SMS、REST API SMS、API SMS、SMS |
