对接约定

接入方式

发票云API采用RESTfull的设计方式，客户端通过HTTP协议的GET、POST(目前主要是这两种)方法请求进行调用。

Restful：参考资料
http://www.infoq.com/cn/articles/designing-restful-http-apps-roth

API的调用地址基本上遵循如下约定的方式： API地址前缀 + 服务 + 资源 + 参数

环境地址

测试环境: https://api-dev.piaozone.com/test
正式环境: https://api.piaozone.com

:::caution
单机版开票等部分开票产品为兼容历史客户，维护了不同的环境地址。对接前，请务必阅读该产品的开发指南
:::

认证方式

对接过程中需要：

• 发票云授权标识（client_id）
• 授权密钥（client_secret）
• 加密密钥（encrypt_key）

client_id和client_secret用于授权认证：获取AccessToken
encrypt_key用于报文加密（加密方式在下一节介绍）。
每个环境的授权不同，获取方式可以找实施人员协助提供。如果是金蝶机构的同事，也可以直接通过智能审批获取，审批流名称如下：

签名规则

支持以下3种签名生成方式：
1、MD5（encType=0） 代码示例：

MD5(client_id + client_secret + timestamp)

2、SHA256（encType=1） 代码示例：

DigestUtils.sha256Hex(client_id + client_secret + timestamp)

3、HMACSHA256（encType=2） 代码示例：

HMACSHA256.sha256_HMAC((client_id + client_secret + timestamp), client_secret)

HMACSHA256 工具类代码示例：

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class HMACSHA256 {
    /**
     * 将加密后的字节数组转换成字符串
     *
     * @param b 字节数组
     * @return 字符串
     */
    public  static String byteArrayToHexString(byte[] b) {
        StringBuilder hs = new StringBuilder();
        String stmp;
        for (int n = 0; b!=null && n < b.length; n++) {
            stmp = Integer.toHexString(b[n] & 0XFF);
            if (stmp.length() == 1)
                hs.append('0');
            hs.append(stmp);
        }
        return hs.toString().toLowerCase();
    }
    /**
     * sha256_HMAC加密
     * @param message 消息
     * @param secret  秘钥
     * @return 加密后字符串
     */
    public static String sha256_HMAC(String message, String secret) {
        String hash = "";
        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            byte[] bytes = sha256_HMAC.doFinal(message.getBytes());
            hash = byteArrayToHexString(bytes);
        } catch (Exception e) {
            System.out.println("Error HmacSHA256 ===========" + e.getMessage());
        }
        return hash;
    }
}

加密方式

部分接口需要做报文加密。
方法：将请求体的json数据需采用AES128加密再传输，秘钥用的是上一节提到的encrypt_key。加密方式代码样例参考：JAVA方式、C++方式、C#方式

返回格式

若无特别说明，接口返回如下：

{
    "errcode": "0000", ///成功时为0000, 失败时为非0000
    "description": "操作成功", //描述，失败时可以根据这个字段进行提示
    "data": "" //请求的返回实际数据
}