QrCode - nxtele/http-api-document GitHub Wiki

二维码管理

利用二维码管理 API，您的商家可以创建和管理 WhatsApp 二维码，用户扫描后可以向您的商家号码发送预设消息。WhatsApp 二维码和短链接为商家创造了一个数字门阶，能帮助商家维持与现有客户的联系并与新客户建立联系。通过这种方式，客户只需使用移动设备的相机扫描二维码或输入短链接，即可开始对话，而无需输入电话号码。

运作方式

WhatsApp 二维码的工作流程：

商家可以创建包含预设消息的二维码，用户扫描后会自动打开 WhatsApp 对话并填充该消息。
每个二维码都有唯一的 code 标识和对应的深度链接（deep_link_url）。
商家可以随时更新二维码的预设消息内容。
支持获取单个二维码详情或列表查询。
不再需要的二维码可以删除。

限制

一个 WABA 电话号码关联的二维码和短链接数量不能超过 2,000。
扫描二维码可发起一条预先填好的消息（最多包含 140 个字符的文本）。
预设消息（prefilled_message）为必填参数。
二维码创建后，code 值不可修改，但可以更新预设消息。
删除的二维码无法恢复。

功能

此 API 包含 5 个接口：

// Create QR Code
/api/wa/createQrCode

// Get QR Code
/api/wa/getQrCode

// Update QR Code
/api/wa/updateQrCode

// Delete QR Code
/api/wa/deleteQrCode

// List QR Codes
/api/wa/listQrCodes

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数：

参数名	类型	必选	示例值	说明
accessKey	String	是	fme2na3kdi3ki	用户身份标识
ts	String	是	1655710885431	当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType	String	是	2	WhatsApp业务类型，取固定值"2"
action	String	是	mt	WhatsApp业务操作，取固定值"mt"
sign	String	是	6e9506557d1f289501d333ee2c365826	API入参参数签名，签名算法

创建二维码

使用此端点创建一个新的 WhatsApp 二维码，用户扫描后可以发送预设消息。

接口

URL：https://api2.nxcloud.com/api/wa/createQrCode
Method：POST
Content-Type：application/json
需要鉴权：是

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为"whatsapp"
business_phone	String	是	xxx	商户的WhatsApp号码，需要带国码。
prefilled_message	String	是	Cyber Monday	用户扫描二维码后预填充的消息内容
generate_qr_image	String	否	SVG	首选图片格式：`SVG` 或 `PNG`

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "prefilled_message": "Cyber Monday",
     "generate_qr_image": "SVG"
}

响应结果

参数	描述
`code`	状态码，0表示成功
`message`	响应消息
`data`对象	返回数据

data 对象

`code`	二维码的唯一标识符
`prefilled_message`	预填充的消息内容
`deep_link_url`	二维码对应的深度链接，用户可以通过此链接打开对话
`qr_image_url`	二维码图片地址【注意保存，该值在查询接口不会返回】

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "prefilled_message": "Cyber Monday",
        "code": "XWSX6W323G5HJ1",
        "deep_link_url": "https://wa.me/message/XWSX6W323G5HJ1",
        "qr_image_url": "https://scontent-hkg4-1.xx.fbcdn.net/m1/v/t6/An_itZzcZpwq7DikZr4GKSObhCgJt1SymdZSti1STsAzKTkfxXjlE9pAMzOhexcnQqR-eJoB5B2JHOMQa2-eSHKsmIFev_Qw-9z0CZJ-sMA2oBqQnThAmRTr1E7i_Y-cmh7IthT3Ez9D?edm=ADZZtP0EAAAA&_nc_gid=c9-Wvukne06Ui-BIJbp0EA&_nc_oc=AdkmH_3P7Q3VMw0ylWkx1GuMoWmDNaxp1q1HtxUcXELmCokjqh-bsEPXm086bdFgZwc&ccb=10-5&oh=00_Afs66uP2TqtYWdSHbL7QyXz1OT4thCAOjyFHCCUDgmbCtw&oe=69CA0455&_nc_sid=5a413f"
    },
    "message": "success"
}

异常响应示例

{
    "code": 0,
    "data": {
        "error": {
            "code": 100.0,
            "message": "(#100) The parameter prefilled_message is required.",
            "type": "OAuthException",
            "fbtrace_id": "A4zvp8rZeQFGiXlLwTPttn_"
        }
    },
    "message": "success"
}

更新二维码

使用此端点更新已存在的二维码的预设消息内容。

接口

URL：https://api2.nxcloud.com/api/wa/updateQrCode
Method：POST
Content-Type：application/json
需要鉴权：是

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为"whatsapp"
business_phone	String	是	xxx	商户的WhatsApp号码，需要带国码。
code	String	是	HUBPIKSFQEXLJ1MMM	要更新的二维码的唯一标识符
prefilled_message	String	是	Cyber Tuesday	更新后的预填充消息内容
generate_qr_image	String	否	SVG	首选图片格式：`SVG` 或 `PNG`

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "code": "XWSX6W323G5HJ1",
    "prefilled_message": "Cyber Tuesday",
     "generate_qr_image": "SVG"
}

响应结果

参数	描述
`code`	状态码，0表示成功
`message`	响应消息
`data`对象	返回数据

data 对象

`code`	二维码的唯一标识符
`prefilled_message`	更新后的预填充消息内容
`deep_link_url`	二维码对应的深度链接
`qr_image_url`	二维码图片地址【注意保存，该值在查询接口不会返回】

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "prefilled_message": "Cyber Tuesday",
        "code": "XWSX6W323G5HJ1",
        "deep_link_url": "https://wa.me/message/XWSX6W323G5HJ1",
        "qr_image_url": "https://scontent-hkg4-1.xx.fbcdn.net/m1/v/t6/An_itZzcZpwq7DikZr4GKSObhCgJt1SymdZSti1STsAzKTkfxXjlE9pAMzOhexcnQqR-eJoB5B2JHOMQa2-eSHKsmIFev_Qw-9z0CZJ-sMA2oBqQnThAmRTr1E7i_Y-cmh7IthT3Ez9D?edm=ADZZtP0EAAAA&_nc_gid=DL4P4JEUtW-FQwl9cF0LBQ&_nc_oc=AdkmH_3P7Q3VMw0ylWkx1GuMoWmDNaxp1q1HtxUcXELmCokjqh-bsEPXm086bdFgZwc&ccb=10-5&oh=00_Afs3l_W2F0c-SRph9XezDylC1bpRORrsFQ1nXLYrZxqJ-w&oe=69CA0455&_nc_sid=5a413f"
    },
    "message": "success"
}

删除二维码

使用此端点删除指定的二维码。删除后该二维码将无法使用。

接口

URL：https://api2.nxcloud.com/api/wa/deleteQrCode
Method：POST
Content-Type：application/json
需要鉴权：是

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为"whatsapp"
business_phone	String	是	xxx	商户的WhatsApp号码，需要带国码。
code	String	是	HUBPIKSFQEXLJ1MMM	要删除的二维码的唯一标识符

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "code": "HUBPIKSFQEXLJ1MMM"
}

响应结果

参数	描述
`code`	状态码，0表示成功
`message`	响应消息
`data`对象	返回数据
`success`	布尔值，true表示删除成功

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "success": true
    },
    "message": "success"
}

异常响应示例【二维码不存在】

{
    "code": 9001,
    "data": null,
    "message": "System business error"
}

获取单个二维码

使用此端点获取指定二维码的详细信息。

接口

URL：https://api2.nxcloud.com/api/wa/getQrCode
Method：POST
Content-Type：application/json
需要鉴权：是

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为"whatsapp"
business_phone	String	是	xxx	商户的WhatsApp号码，需要带国码
code	String	是	HUBPIKSFQEXLJ1MMM	要查询的二维码的唯一标识符

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "code": "XWSX6W323G5HJ1"
}

响应结果

参数	描述
`code`	状态码，0表示成功
`message`	响应消息
`data`对象	返回数据

data 对象

`data`数组	二维码信息数组
`code`	二维码的唯一标识符
`prefilled_message`	预填充的消息内容
`deep_link_url`	二维码对应的深度链接

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "data": [
            {
                "prefilled_message": "Cyber Tuesday",
                "code": "XWSX6W323G5HJ1",
                "deep_link_url": "https://wa.me/message/XWSX6W323G5HJ1"
            }
        ]
    },
    "message": "success"
}

异常响应示例【二维码不存在】

{
    "code": 0,
    "data": {
        "data": []
    },
    "message": "success"
}

获取二维码列表

使用此端点获取商户号码下所有二维码的列表，支持分页查询。

接口

URL：https://api2.nxcloud.com/api/wa/listQrCodes
Method：POST
Content-Type：application/json
需要鉴权：是

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为"whatsapp"
business_phone	String	是	xxx	商户的WhatsApp号码，需要带国码。
limit	Integer	否	3	每页返回的二维码数量上限
after	String	否		游标，用于获取下一页数据，从上一次响应的 paging.cursors.after 获取
before	String	否		游标，用于获取上一页数据，从上一次响应的 paging.cursors.before 获取

请求示例1（分页查询）

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "limit": 3
}

响应结果

参数	描述
`code`	状态码，0表示成功
`message`	响应消息
`data`对象	返回数据
`data`数组	二维码信息数组
`code`	二维码的唯一标识符
`prefilled_message`	预填充的消息内容
`deep_link_url`	二维码对应的深度链接
`paging`对象	分页信息（仅在有更多数据时返回）
`next`	下一页的完整URL
`cursors.after`	下一页游标
`cursors.before`	上一页游标

data 对象

`data`数组	二维码信息数组
`paging`对象	分页信息（仅在有更多数据时返回）

data 数组

`code`	二维码的唯一标识符
`prefilled_message`	预填充的消息内容
`deep_link_url`	二维码对应的深度链接

paging 对象

`next`	下一页的完整URL
`cursors.after`	下一页游标
`cursors.before`	上一页游标

响应示例1（分页查询）

{
    "code": 0,
    "data": {
        "data": [
            {
                "prefilled_message": "Cyber Monday",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "嗨，云缨",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "My teammate is waiting for me",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            }
        ],
        "paging": {
            "next": "https://graph.facebook.com/v20.0/124871750714609/message_qrdls?limit=3&after=MTcwNTQ2MDQ5OCxRWlZAHTUJGREVTVTJLMQZDZD",
            "cursors": {
                "after": "MTcwNTQ2MDQ5OCxRWlZAHTUJGREVTVTJLMQZDZD"
            }
        }
    },
    "message": "success"
}

请求示例2（查询所有）

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx"
}

响应示例2（查询所有）

{
    "code": 0,
    "data": {
        "data": [
            {
                "prefilled_message": "Cyber Monday",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "嗨，云缨",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "My teammate is waiting for me",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "Hi, I want to order.",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "Hi Luckin coffee",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            },
            {
                "prefilled_message": "Hi, I want to order",
                "code": "xxx",
                "deep_link_url": "https://wa.me/message/xxx"
            }
        ]
    },
    "message": "success"
}

QrCode - nxtele/http-api-document GitHub Wiki

二维码管理

运作方式

限制

功能

鉴权机制

请求参数

header参数：

创建二维码

接口

body参数：

请求示例

响应结果

data 对象

响应示例 SUCCESS

异常响应示例

更新二维码

接口

body参数：

请求示例

响应结果

data 对象

响应示例 SUCCESS

删除二维码

接口

body参数：

请求示例

响应结果

响应示例 SUCCESS

异常响应示例【二维码不存在】

获取单个二维码

接口

body参数：

请求示例

响应结果

data 对象

响应示例 SUCCESS

异常响应示例 【二维码不存在】

获取二维码列表

接口

body参数：

请求示例1（分页查询）

响应结果

data 对象

data 数组

paging 对象

响应示例1（分页查询）

请求示例2（查询所有）

响应示例2（查询所有）

异常响应示例【二维码不存在】