使用说明 - QR码微服务
如何运行
本微服务采用Docker容器的方式进行发布，用户可以通过方位DockerHub直接下载并在自己的服务器或者计算机上运行本容器。运行的指令为：
docker run -it -p 5555:80 benjaminshi/qrencoder
-p 5555:80 指定的是容器开放/映射的端口，您可以根据实际需要调整。
当运行完成之后，如果有映射端口，您可以通过在浏览器中输入类似如下的地址验证容器实例是否运行成功：
QR码生成微服务接口
本接口主要用来生成QR码矩阵，如果希望直接输出图片，请采用QR图片生成微服务接口。
请求方式
本接口支持的请求方式包括：
- GET
- POST
调用的接口
调用本接口可以使用的接口为：
/qr/encode/api/qr/api/encode
下列示例地址都可以访问本接口：
http://localhost:5555/qr
http://localhost:5555/encode
http://localhost:5555/api/qr
http://localhost:5555/api/encode
参数
访问本接口时，需要输入的参数如下表所示。采用GET或者POST访问接口时，参数输入的方式是不同的，请具体参阅后面相应的章节。
| 字段 | 说明 | 数据情况 | |
|---|---|---|---|
| data | 需要编码进QR中的数据 | 必选 | 当采用GS1 QR时输入的数据是GS1数据传输字符串形式，即：不带括号的形式；变长AI要采用<GS>(FNC1)分隔。具体请参阅之后的示例。 |
| mode | QR的模式 | 可选 |
设置Code128是标准/普通的QR还是GS1 QR，可选值为：
|
| version | QR的版本 | 可选 |
指定QR码的版本：1-40。如果不指定或者设置为0，将根据纠错等级和数据自动选择版本。
请注意：如果指定了版本，但是该版本的QR码在规定的纠错等级下容纳不下所有数据，会编码失败报错。如果没有严格规定必须设置某个版本的QR码，请将本字段设置为0或者不设置。 |
| ecl | QR的纠错等级 | 可选 |
指定QR码的纠错等级：
|
返回值
不论采用GET还是POST方式访问接口，返回值都是JSON类型的数据，具体的数据包括以下的内容：
| 字段 | 说明 | 备注 |
|---|---|---|
| isOK | 是否成功 | true或false |
| code | 返回值编码 | 0代表成功 |
| message | 返回的信息 | 一般返回的是错误的信息，成功返回空字符串。 |
| symbol | 返回的QR码符号 | 错误时返回null;正确时返回QR码符号，具体格式请参见表3 |
| 字段 | 说明 |
|---|---|
| version | 编码成功的符号版本 |
| ecl | 编码成功的符号纠错等级 |
| masking | 编码成功的符号掩膜方案 |
| width | 编码成功的符号宽度 |
| height | 编码成功的符号高度 |
| base64matrix | 编码成功的符号矩阵的Base64编码，注意解析为字节序列之后，每8个模块(8位)存储一个字节。 |
GET请求方式
当采用GET请求方式访问本接口时，数据是采用查询字符串(Query String)的方式输入的。具体的输入参数在上面有说明。
请参照下面的例子，调用相关的接口：
例1.
访问的地址：
{
"isOK": true,
"code": 0,
"message": "",
"symbol": {
"version": 1,
"ecl": "M",
"masking": 0,
"width": 21,
"height": 21,
"base64matrix": "/hP8FNBujrt0JdurrsEpB/qv4AAAqkiR5aoS3c
z6O7sjcgBxG/kicEREuoqt06quvdsEu7/vdoA="
}
}
例2.
访问的地址：
{
"isOK": true,
"code": 0,
"message": "",
"symbol": {
"version": 6,
"ecl": "Q",
"masking": 1,
"width": 41,
"height": 41,
"base64matrix": "/h/qcb/BLydLUG6FmTDrt17Y40XbpWtpsuwUf
Mh5B/qqqqr+AepZgwBiU7/0tFQuK6lgF+vjhYO
FpuG5RBsh6UTw4u7DIHCpzaP9pPYrZYR4GpJ74
eXpkCn2cGvH4dGlpVOfDrh6zL8cBeb5KyWAUAr
/GRW8LlIXkDhCOlZd7Rvw2ZYKjJWnun489aeFV
IsidVn+T3gN0AcGw25FMlrgYftLh8ne6Jxe+gB
cSgfE/5U92mrwS+lHkSuiWb5frdJBFSk26zlb1
5cFLxuIzv5DgDJegA=="
}
}
例3.
访问的地址：
{
"isOK": false,
"code": -1,
"message": "Encode failed!",
"symbol": null
}
POST请求方式
当采用POST请求方式访问本接口时，数据是采用请求体(Request Body)的方式输入的，输入的格式是JSON。具体的输入参数在上面有说明。
请参照下面的例子，调用相关的接口：
例1.
访问的地址：
{
"data": "QR"
}
返回的结果:
{
"isOK": true,
"code": 0,
"message": "",
"symbol": {
"version": 1,
"ecl": "M",
"masking": 0,
"width": 21,
"height": 21,
"base64matrix": "/hP8FNBujrt0JdurrsEpB/qv4AAAqkiR5aoS3c
z6O7sjcgBxG/kicEREuoqt06quvdsEu7/vdoA="
}
}
例2.
访问的地址：
{
"data": "010690123456789210A200801<GS>21ABC123",
"mode": "GS1",
"version": 6,
"ecl": "Q"
}
返回的结果:
{
"isOK": true,
"code": 0,
"message": "",
"symbol": {
"version": 6,
"ecl": "Q",
"masking": 1,
"width": 41,
"height": 41,
"base64matrix": "/h/qcb/BLydLUG6FmTDrt17Y40XbpWtpsuwUf
Mh5B/qqqqr+AepZgwBiU7/0tFQuK6lgF+vjhYO
FpuG5RBsh6UTw4u7DIHCpzaP9pPYrZYR4GpJ74
eXpkCn2cGvH4dGlpVOfDrh6zL8cBeb5KyWAUAr
/GRW8LlIXkDhCOlZd7Rvw2ZYKjJWnun489aeFV
IsidVn+T3gN0AcGw25FMlrgYftLh8ne6Jxe+gB
cSgfE/5U92mrwS+lHkSuiWb5frdJBFSk26zlb1
5cFLxuIzv5DgDJegA=="
}
}
例3.
访问的地址：
{
"data": "010690123456789210A200801<GS>21ABC123",
"mode": "GS1",
"version": 1
}
返回的结果:
{
"isOK": false,
"code": -1,
"message": "Encode failed!",
"symbol": null
}
QR图片生成微服务接口
本接口用来直接生成QR码图片。
请求方式
本接口支持的请求方式包括：
- GET
- POST
调用的接口
调用本接口可以使用的接口为：
/image/qr/image/api/image/qr/api/image
下列示例地址都可以访问本接口：
http://localhost:5555/image/qr
http://localhost:5555/image
http://localhost:5555/api/image/qr
http://localhost:5555/api/image
参数
访问本接口时，需要输入的参数如下表所示。采用GET或者POST访问接口时，参数输入的方式是不同的，请具体参阅后面相应的章节。
| 字段 | 说明 | 数据情况 | |
|---|---|---|---|
| data | 需要编码进QR中的数据 | 必选 | 当采用GS1 QR时输入的数据是GS1数据传输字符串形式，即：不带括号的形式；变长AI要采用<GS>(FNC1)分隔。具体请参阅之后的示例。 |
| mode | QR的模式 | 可选 |
设置Code128是标准/普通的QR还是GS1 QR，可选值为：
|
| version | QR的版本 | 可选 |
指定QR码的版本：1-40。如果不指定或者设置为0，将根据纠错等级和数据自动选择版本。
请注意：如果指定了版本，但是该版本的QR码在规定的纠错等级下容纳不下所有数据，会编码失败报错。如果没有严格规定必须设置某个版本的QR码，请将本字段设置为0或者不设置。 |
| ecl | QR的纠错等级 | 可选 |
指定QR码的纠错等级：
|
| pixel | QR的模块尺寸 | 可选 | 指定QR码每个模块被放大成多少个像素。默认采用每个模块放大成5个像素(5 x 5)。 |
返回值
当编码成功的时候，返回的是png格式的图片(image/png)；如果编码失败，返回空结果(Content-Length:0)。
GET请求方式
当采用GET请求方式访问本接口时，数据是采用查询字符串(Query String)的方式输入的。具体的输入参数在上面有说明。
请参照下面的例子，调用相关的接口：
例1.
访问的地址：
例2.
访问的地址：
例3.
访问的地址：
空(Header: Content-Length=0)
POST请求方式
当采用POST请求方式访问本接口时，数据是采用请求体(Request Body)的方式输入的，输入的格式是JSON。具体的输入参数在上面有说明。
请参照下面的例子，调用相关的接口：
例1.
访问的地址：
{
"data": "QR"
}
返回的结果:
例2.
访问的地址：
{
"data": "010690123456789210A200801<GS>21ABC123",
"mode": "GS1",
"version": 6,
"ecl": "Q"
}
返回的结果:
例3.
访问的地址：
{
"data": "010690123456789210A200801<GS>21ABC123",
"mode": "GS1",
"version": 1
}
返回的结果:
空(Header: Content-Length=0)
试用版和激活
为什么需要激活？
如果使用未激活版本，本软件会存在一些限制，比如：生成QR码会被时不时替换成版权信息、最多能产生50个左右的条码等。
未激活版本的软件只能作为试用，帮助您决定这个微服务是否满足您的基本要求。如果本软件能够帮到您， 请联系我们（联系我们）购买激活。
采用网页直接激活
本微服务直接封装了网页的激活功能，直接在微服务展现的网页(比如：https://localhost:5555/)上选择激活，就可以看到下面的界面：
激活界面
您可以通过执行下面的步骤进行激活
- 在界面中的设备码是您需要提供给我们的东西。
- 联系我们（联系我们）了解激活码申请步骤。
- 付费：请一定注意激活码是针对容器实力的，如果更换电脑或者重新启动一个新的容器实例需要获取新的设备码和激活码。
-
向我们提供以下信息：
- 获得的设备码；
- 您的公司、姓名、联系方式（电子邮箱地址、手机）；
- 付费的凭证（我们会有人配合您验证）；
- 需要开具发票的，您的发票信息和快递信息；
- 以及其他我们可能需要的信息。
- 我们会在确认您付费之后，将激活码通过电子邮件或者微信的形式发给您。
-
您收到我们的激活码之后，回到激活页面之中在激活码框中输入激活码。
用“激活”按钮查看您是否激活成功。如果激活成功激活会显示“激活成功”。
激活成功
激活API接口
除了采用网页激活之外，在服务器上我们一般没有图形界面，这种情况可以采用API接口的形式完成激活。
您可以通过执行下面的步骤进行激活
-
可以通过下面的API地址获得设备码：
http://localhost:5555/devicekey这个接口会返回一串数字字符组成的序列即为“设备码”——需要提供给我们的东西。 - 联系我们（联系我们）了解激活码申请步骤。
- 付费：请一定注意激活码是针对容器实力的，如果更换电脑或者重新启动一个新的容器实例需要获取新的设备码和激活码。
-
向我们提供以下信息：
- 获得的设备码；
- 您的公司、姓名、联系方式（电子邮箱地址、手机）；
- 付费的凭证（我们会有人配合您验证）；
- 需要开具发票的，您的发票信息和快递信息；
- 以及其他我们可能需要的信息。
- 我们会在确认您付费之后，将激活码通过电子邮件或者微信的形式发给您。
-
您收到我们的激活码之后，应该使用激活API接口来激活本微服务。激活的接口为：
/enable/{激活码}比如：http://localhost:5555/enable/{从我们这里收到的激活码} -
激活之后，可以使用验证激活状态API接口来验证您是不是已经激活了本微服务。验证激活的接口为：
/enabled比如：http://localhost:5555/enabled如果返回的是YES说明您已经完成了这个微服务实例的激活；NO表示没有激活成功。