飞印API参考手册

飞印API是基于web的应用程序接口。您的网站/业务系统是通过 国际W3C标准的HTTP通信协议 发送信息到飞印API并输出到飞印无线打印机的。本章节介绍飞印提供的所有应用程序接口、方法以及对应的参数。

飞印API返回内容分为两种类型:第一种是直接返回一个整型,用来表示调用的结果;第二种是返回XML格式的字符串查询结果。

具体而言,飞印API支持您的网站/业务系统用以下方式调用飞印无线打印机,

  1. 发送数据到飞印打印机打印输出
  2. 查询打印任务状态(例如:队列中、已打印)
  3. 查询打印机工作状态(例如:在线、离线、缺纸等)
  4. 查询打印异常信息

API基本工作流程

对飞印API的每个调用流程都分为以下2个步骤:

调用请求的鉴权
  1. 您的网站/业务系统每次调用飞印API都针对发送到信息生成一个MD5的hash字串,将此字串赋值给 securityCode 这一必填变量并发送给飞印API。
  2. 飞印API根据收到的 securityCode 以及客户代码、 API密钥等信息验证请求的合法性和有效性。
请求的处理
  1. 对于通过成功鉴权的请求,飞印API将根据调用的方法进行对应的处理/计算。
  2. 对于未通过成功鉴权的请求,飞印API将拒绝并返回异常信息。

必填参数

所有飞印API请求都必须包含以下参数:

reqTime :请求(发生)时间戳,数值型
本次API请求发生的时刻,值为自 1970-1-1 0:0 到现在的 毫秒数 ,类似于Java语言中的 System.currentTimeMillis() 函数的取值。
securityCode :安全校验码,字符串
调用飞印API的网站/应用系统用 API_KEY 针对请求内容生成的MD5哈希字串,此字串将被飞印API用于请求有效性的验证。 请参考 使用前的准备 了解如何获取 API_KEY
memberCode :商户编码,数值型
您在 飞印中心 注册的帐号对应的(系统自动生成的)商户编码,可登录飞印中心按指引获取。

发送打印数据

本节介绍飞印API最重要的功能,发送数据到飞印API并通过飞印打印机输出打印,以及对应的返回状态码。

支持的打印格式

通过飞印API发送的信息内容支持2种格式:
  1. 自由格式(自定义格式)的文本信息,需根据业务需要自行调整打印输出格式
  2. 格式化信息(例如客户订单)

如果选择格式化信息,您必须根据飞印中心或 飞印API集成示例代码 提供的例子来需要打印输出的数据和格式。

API调用方法

发送打印数据的飞印API请求以及参数应该用 HTTP POST 方法发送。飞印API将根据收到的信息验证请求的有效性反馈对应的状态码。

必填参数

发送打印数据的飞印请求必须包含以下参数(必填参数用 粗体 标识)。每个有效的飞印API请求必须必须包含必填参数:

reqTime :请求(发生)时间戳,数值型
本次API请求发生的时刻,值为自 1970-1-1 0:0 到现在的 毫秒数 类似于Java语言中的 System.currentTimeMillis() 函数的取值。
securityCode :安全校验码,字符串
调用飞印API的网站/应用系统用 API_KEY 针对请求内容生成的MD5哈希字串,此字串将被飞印API用于请求有效性的验证。 请参考 使用前的准备 了解如何获取 API_KEY
memberCode :商户编码,数值型
您在 飞印中心 注册的帐号对应的(系统自动生成的)商户编码,可登录飞印中心按指引获取。
deviceNo :飞印打印机的设备编码,字符串
打印请求将发送到对应此设备编码的飞印无线打印机。可在 飞印中心 “我的终端”中获取已注册到飞印中心的飞印打印机设备编码,也可通过以下方式直接从打印机本身获取:按一下通电中的飞印打印机背面黑色小按钮,即可打印出一张测试页面,其中包含本机设备编码。
mode :发送打印信息的格式类型,数值型
1 表示格式化信息,2 表示自由格式(自定义格式)信息。这种方法方便您灵活配置和测试打印信息格式,开发时建议通过一台测试机测试实际打印效果,直到获得满意的输出信息格式化效果。
msgDetail :打印的数据/信息内容,字符串

对于 mode=1 的信息,打印输出的数据将按以下方式排版:

  订单项名称 1@单价 1@数量 1 ||
  订单项名称 2@单价 2@数量 2 ||
  ......||
  订单项名称  x@单价 N@数量 N`mode=2` 时,用户可自由设置打印格式,空行或空格等全部由调用程序自行控制。

可选参数

charge :订单总金额,数值型
以 “分” 计算的金额,例如:1元 = 100分。只用于发送格式化信息( mode=1 时)。
customerName :客户名称,字符串
只用于发送格式化信息( mode=1 时)。
customerPhone :客户联系人电话,字符串
只用于发送格式化信息( mode=1 时)。
customerAddress :客户地址,字符串
只用于发送格式化信息( mode=1 时)。
customerMemo :客户留言/备注,字符串
只用于发送格式化信息( mode=1 时)。
msgNo :信息/订单编号,字符串
自定义的打印信息编号,可选,一般由调用网站/应用系统自动生成,用于跟踪订单。如果没有设置,飞印API将给每个打印请求自动分配一个。

返回的状态码

飞印API的打印数据请求的返回信息包含2类:

  1. 以整型表示的状态码,表示请求的处理结果
  2. XML格式的字符串信息,表示请求的返回内容/信息

飞印API将对每个打印请求返回一个状态码。它们的含义如下:

0 :正常

-1 :IP地址不允许

-2 :关键参数为空或请求方式不对

-3 :客户编码不对

-4 :安全校验码不正确

-5 :请求时间失效

-6 :订单内容格式不对

-7 :重复的消息 ( msgNo 的值重复)

-8 :消息模式不对

-9 :服务器错误

-10 :服务器内部错误

-111 :打印终端不属于该账户

打印输出一维条码

方法与格式

按以下 格式字符串 作为打印内容的一部分发到飞印API即可, 格式字符串 部分将会以条码形式打印:

<Barcode# Type=x Height=y>此处为目标条码的编码</Barcode#>

参数说明

  1. 参数 Type 用于选择条码类型,取值范围:1 ≤ x ≤ 6,`Type`对应关系如下:

    1: UPC-A
    2: JAN13(EAN13)
    3: JAN8(EAN8)
    4: CODE39
    5: ITF
    6: CODABAR
    
  2. 参数 Height 用于选择条码高度,取值范围: y={10, 15, 20, 25, 30}, 单位:mm。

  3. 目标条码的编码为ASCII码格式,个数限制及字符集参照下面的 支持的条码类型

支持的条码类型

条码类型: UPC-A
字符个数限制: 11 ≤ n ≤ 12, 字符集: 0~9, 备注: 48 ≤ d ≤ 57
条码类型: JAN13(EAN13)
字符个数限制: 12 ≤ n ≤13, 字符集: 0~9, 备注: 48 ≤ d ≤ 57
条码类型: JAN8(EAN8)
字符个数限制: 7 ≤ n ≤8, 字符集: 0~9, 备注: 48 ≤ d ≤ 57
条码类型: CODE39
字符个数限制: 1 ≤ n ≤ 12, 字符集: 0~9, A~Z, SP, $, %, +, -, . , /, 备注: 48 ≤ d ≤ 57, 57, 65≤d≤90 d=32,36,37,43,45,46,47
条码类型: ITF
字符个数限制: 1 ≤ n ≤ 16 (偶数), 字符集: 0~9, 备注: 48 ≤ d ≤ 57
条码类型: CODABAR
字符个数限制: 1 ≤ n ≤ 17, 字符集: 0~9, A~D, $, +, -, 。, / , :, 备注: 48 ≤ d ≤ 57, 65 ≤ d ≤ 68, d=36, 43, 45, 46, 47 ,58

注解

  1. 格式字符串 区分大小写。

  2. 如果 格式字符串 错误参数超过取值范围或违反条码规则,将不会打印出条码,此时会将格式字符串原文打印。

  3. 若条码格式字符串前存在打印正文,此时打印正文必须以回车换行符结尾,否则无法正常打印条码,条码部分将以条码编码字符串的形式打印。错误的例子:

    飞印<Barcode# Type=1 Height=20>012345678912</Barcode#>012345678912,此格式错误,将打印为::
    
        飞印012345678912012345678912
    
    正确的例子(需用空行符 `\n` 与前面正文隔开)::
    
        飞印\n<Barcode# Type=1 Height=20>012345678912</Barcode#>012345678912
    

查询打印任务状态

您的网站/业务系统可以通过查询打印任务功能查询已发出的打印任务状态,例如“队列中”,“已打印”等。

API调用方法

查询打印任务状态的请求以及参数须采用HTTP GET发送。

必填参数

查询打印任务状态的API功能应该包含以下必填参数(粗体部分):

reqTime :请求(发生)时间戳,数值型
本次API请求发生的时刻,值为自 1970-1-1 0:0 到现在的 毫秒数 类似于Java语言中的 System.currentTimeMillis() 函数的取值。
securityCode :安全校验码,字符串
调用飞印API的网站/应用系统用 API_KEY 针对请求内容生成的MD5哈希字串,此字串将被飞印API用于请求有效性的验证。 请参考 使用前的准备 了解如何获取 API_KEY
memberCode :商户编码,数值型
您在 飞印中心 注册的帐号对应的(系统自动生成的)商户编码,可登录飞印中心按指引获取。
msgNo :信息/订单编号,字符串
自定义的打印信息编号,可选,一般由调用网站/应用系统自动生成,用于跟踪订单。如果没有设置,飞印API将给每个打印请求自动分配一个。

请求状态码

查询打印任务请求返回以下状态码:

0 :打印请求/任务中队列中,等待打印

1 :打印任务已完成/请求数据已打印

2 :打印任务/请求失败

9 :打印任务/请求已发送

-1 :IP地址不允许

-2 :关键参数为空或请求方式不对

-3 :客户编码不正确

-4 :安全校验码不正确

-5 :请求时间失效。请求时间和请求到达飞印API的时间长超出安全范围。请参考 同步应用服务器时间 了解更多飞印API的时间安全设置。

-6 :订单编号错误或者不存在

测试查询打印任务

飞印提供一个测试方法 testQueryState() ,供测试查询打印任务状态功能。请通过参考 飞印API集成示例代码 了解更详细的用法示例。

查询打印机状态

飞印API支持查询已部署飞印移动打印机(终端)的实时工作状态。当飞印API收到一个查询打印机设备状态的请求时,将检查一遍调用方所拥有的所有飞印移动打印机,并返回一段状态信息和对应的状态码。

API调用方法

飞印API打印请求及其参数应该用HTTP GET方式发送。

必填参数

查询打印(终端)状态的API功能应该包含以下必填参数(粗体部分):

reqTime :请求(发生)时间戳,数值型
本次API请求发生的时刻,值为自 1970-1-1 0:0 到现在的 毫秒数 类似于Java语言中的 System.currentTimeMillis() 函数的取值。
securityCode :安全校验码,字符串
调用飞印API的网站/应用系统用 API_KEY 针对请求内容生成的MD5哈希字串,此字串将被飞印API用于请求有效性的验证。 请参考 使用前的准备 了解如何获取 API_KEY
memberCode :商户编码,数值型
您在 飞印中心 注册的帐号对应的(系统自动生成的)商户编码,可登录飞印中心按指引获取。

返回信息

XML字符串 :正常的打印状态查询返回信息采用XML格式,例如:

<?xml version="1.0" encoding="UTF-8"?>
<deviceList>
    <device id="4600000006463940">
    <address>Device Installation Address </address>
    <since>2010-09-20</since>
    <simCode>13560081341</simCode>
    <lastConnected>2010-09-26  18:09:29</lastConnected>
    <deviceStatus>Normal</deviceStatus>
    <paperStatus>Normal</paperStatus>
    </device>
</deviceList>

since 是指打印机的激活日期。

simCode 是指打印机对应的IMSI编码(打印机本身采用的移动SIM卡唯一识别号)。

lastConnected 是指打印机最后一次通信连接发生的时刻。

deviceStatus 是指打印机的连接状态,包括: 离线在线

paperStatus 是指打印纸张的状态,包括 正常缺纸

返回的状态码

飞印API对查询打印机(终端)状态的请求返回以下状态码:

-1 :IP地址不允许

-2 :关键参数为空或请求方式不对

-3 :客户编码不正确

-4 :安全校验码不正确

-5 :请求时间失效。请求时间和请求到达飞印API的时间长超出安全范围。请参考 同步应用服务器时间 了解更多飞印API的时间安全设置。

测试查询打印机状态

您可以用 testListDevice() 这个方法测试查询打印机状态。请参考 飞印API集成示例代码 了解更详细的使用。

查询打印异常

无线移动网络或停电的外部因素可以导致飞印无线打印机打印失败。每当这类事故发生时,飞印API将对失败的打印请求生成异常日志。用户可以用查询打印异常的API功能来查询相关异常信息,方便诊断问题和解决问题。

每当收到查询打印异常的请求时,飞印API将根据用户指定的时间段(默认是最后10天)内、用户所拥有的所有飞印打印机的打印异常,并返回XML格式的异常日志信息。

API端点

http://my.feyin.net/api/listException

API调用方法

查询打印异常的请求及其参数须采用HTTP GET发送给飞印API。

必填参数

用于查询打印异常的请求须包含以下参数(粗体部分为必填):

reqTime :请求(发生)时间戳,数值型
本次API请求发生的时刻,值为自 1970-1-1 0:0 到现在的 毫秒数 类似于Java语言中的 System.currentTimeMillis() 函数的取值。
securityCode :安全校验码,字符串
调用飞印API的网站/应用系统用 API_KEY 针对请求内容生成的MD5哈希字串,此字串将被飞印API用于请求有效性的验证。 请参考 使用前的准备 了解如何获取 API_KEY
memberCode :商户编码,数值型
您在 飞印中心 注册的帐号对应的(系统自动生成的)商户编码,可登录飞印中心按指引获取。
start :查询的开始日期,日期字符串
yyyy-MM-dd 格式。例如: 2010-09-03 是指 2010年9月3日 。如此参数留空,默认为最近10天。
end :查询的截至日期,日期字符串
yyyy-MM-dd 格式。例如: 2010-09-03` 是指 2010年9月3日 。如此参数留空,默认为今天。

返回信息

XML字符串 :查询打印异常日期的请求返回XML格式的信息,例如:

<?xml version="1.0" encoding="UTF-8"?>
<exceptionList begin="2010-10-08" end="2010-10-18">
  <exception>
    <msgNo>12873947857</msgNo>
    <msgTime>2010-10-18 17:39</msgTime>
    <customer><![CDATA[  Name: Ms Liu,Phone: 13321332245, Add: SCUT
            North Campus, Notes: Please hurry up. ]]> </customer>
    <detail>
    <![CDATA[
    Fried noodle-1000-1 Fried chicken legs-2000-1
    ]]>
    </detail>
  </exception>

  <exception>
    <msgNo>12873945227</msgNo>
    <msgTime>2010-10-18 17:35</msgTime>
    <customer><![CDATA[  ]]> </customer>
    <detail><![CDATA[
    This is free-form print data. Please limit your text within 4KB in size
    in each print request you send.]]>
    </detail>
  </exception>
</exceptionList>

beginend 用来指定查询打印异常发生的时间段。它们都是日期字符串,格式为 YYYY-MM-DD

msgNo 是用户(API调用网站/系统)自行指定的打印请求编号。

msgTime 是指请求发生的时间。

customer 是指客户信息(只用于格式化打印请求)。

detail 是打印请求的数据/内容。

返回状态码

查询打印异常信息功能可返回以下状态码:

-1 :IP地址不允许

-2 :关键参数为空或请求方式不对

-3 :客户编码不正确

-4 :安全校验码不正确

-5 :请求时间失效。请求时间和请求到达飞印API的时间长超出安全范围。请参考 同步应用服务器时间 了解更多飞印API的时间安全设置。

测试查询打印异常

您可通过 testListException() 这个方法测试查询打印异常功能。请参考 飞印API集成示例代码 中的示例代码了解具体的使用。