单项权益分销系统 · 开放 API

概述

通用响应结构

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1704355200
}

错误码定义

对接前需准备的信息

外部分销商接入开放 API 前，双方需交换以下信息，以便完成网关授权与联调。

分销商需向 vipsys 提供

vipsys 将向分销商提供

完成上述信息对接并完成网关授权后，即可按本文档「鉴权说明」与「接口列表」进行开发与联调。

以上信息会发送至调用方对接人邮箱。

鉴权说明

分销商仅通过阿里云 API 网关调用开放 API：请求先经网关（安全认证类型为「阿里云 APP」）校验签名，通过后再转发至业务后端。请勿直连业务后端。

参考文档：使用摘要签名认证方式调用 API - 阿里云

请求头（必传）

网关签名串（StringToSign）格式

签名串由以下 7 个字段用换行符 \n拼接，字段为空也保留 \n，大小写敏感：

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

• HTTPMethod：如 GET、POST，全大写。
• Accept：请求头 Accept 的值，可为空。
• Content-MD5：请求头 Content-MD5 的值，无 Body 或为 Form 时可为空。
• Content-Type：请求头 Content-Type 的值，可为空。
• Date：请求头 Date 的值，可为空。
• Headers：参与签名的自定义头。将参与签名的 Header 按 Key 字典序 排序后，按 Key:Value\n 拼接；多个头末尾保留 \n。不参与签名的头：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。
• PathAndParameters：Path + Query/Form 参数。格式为 Path?key1=value1&key2=value2...，Query/Form 的 Key 按字典序排序；无参数则不带 ?。Value 为空时只保留 Key；数组参数取第一个 Value。

计算签名

1. 按上述规则拼出 StringToSign（UTF-8）。
2. 使用 APP Secret 对 StringToSign 做 HmacSHA256（或 HmacSHA1）。
3. 将结果做 Base64 编码，即为 X-Ca-Signature 的值。

签名示例（供对照验算）

以下为 GET /api/open/v1/balance、无 Query、无参与签名的自定义头时的示例。

StringToSign（共 7 行，第 3～6 行为空行）：

GET
application/json



/api/open/v1/balance

计算步骤：使用 AppSecret test_secret_123 对上述 StringToSign（UTF-8 编码）做 HmacSHA256，再对二进制结果做 Base64 编码。

得到的 X-Ca-Signature 示例值：

+UA1tPK41ggA7Ufd6SEHW9rITTnahv50U5OggO7h+Fc=

说明：上述签名为基于示例 AppSecret 计算所得，仅供格式与算法对照；实际调用请使用 vipsys 分配的网关 AppId 与 AppSecret，并在网关控制台配置一致的安全认证方式。

Java 签名示例代码

以下为阿里云 API 网关摘要签名（HmacSHA256 + Base64）的 Java 实现示例，可直接用于生成请求头 X-Ca-Signature。

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Collectors;

public class ApiGatewaySign {

    /**
     * 生成 X-Ca-Signature 头
     *
     * @param method       HTTP 方法，如 GET、POST（大写）
     * @param path         路径，如 /api/open/v1/balance
     * @param queryParams  Query 参数，Key 会按字典序参与 PathAndParameters；可为 null
     * @param headersForSign 参与签名的自定义头，Key 会按字典序参与 Headers 段；可为 null
     * @param accept       Accept 头
     * @param contentMd5B64 Content-MD5 的 Base64，无 Body 时传空字符串
     * @param contentType  Content-Type，无 Body 时传空字符串
     * @param date         Date 头，可不传时传空字符串
     * @param appSecret    网关 AppSecret
     * @return Base64 编码的签名，即 X-Ca-Signature 的值
     */
    public static String sign(String method,
                             String path,
                             Map<String, String> queryParams,
                             Map<String, String> headersForSign,
                             String accept,
                             String contentMd5B64,
                             String contentType,
                             String date,
                             String appSecret) throws Exception {
        // PathAndParameters
        String pathAndParams = path;
        if (queryParams != null && !queryParams.isEmpty()) {
            String query = new TreeMap<>(queryParams).entrySet().stream()
                    .filter(e -> e.getValue() != null && !e.getValue().isEmpty())
                    .map(e -> e.getKey() + "=" + e.getValue())
                    .collect(Collectors.joining("&"));
            if (!query.isEmpty()) {
                pathAndParams = path + "?" + query;
            }
        }

        // Headers 段：参与签名的头按 Key 字典序，格式 Key:Value\n
        StringBuilder headersSb = new StringBuilder();
        if (headersForSign != null && !headersForSign.isEmpty()) {
            for (Map.Entry<String, String> e : new TreeMap<>(headersForSign).entrySet()) {
                headersSb.append(e.getKey()).append(":").append(e.getValue() != null ? e.getValue() : "").append("\n");
            }
        }

        String stringToSign =
                (method != null ? method.toUpperCase() : "") + "\n"
                        + (accept != null ? accept : "") + "\n"
                        + (contentMd5B64 != null ? contentMd5B64 : "") + "\n"
                        + (contentType != null ? contentType : "") + "\n"
                        + (date != null ? date : "") + "\n"
                        + headersSb
                        + pathAndParams;

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] signBytes = mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(signBytes);
    }

    // 示例：GET /api/open/v1/balance，无 Query、无自定义头
    public static void main(String[] args) throws Exception {
        String signature = sign(
                "GET",
                "/api/open/v1/balance",
                null,
                null,
                "application/json",
                "",
                "",
                "",
                "test_secret_123"
        );
        System.out.println("X-Ca-Signature: " + signature);
        // 输出应与文档示例一致: +UA1tPK41ggA7Ufd6SEHW9rITTnahv50U5OggO7h+Fc=
    }
}

调用示例（GET 余额）：

String xCaSignature = ApiGatewaySign.sign(
    "GET",
    "/api/open/v1/balance",
    null,           // 无 Query
    null,           // 无参与签名的自定义头
    "application/json",
    "",
    "",
    "",
    "your_app_secret"
);
// 请求头: x-ca-key: your_app_id, X-Ca-Signature: xCaSignature, Accept: application/json

POST 带 Body 时，若网关要求对 Body 做 Content-MD5，可先对 Body 的 UTF-8 字节做 MD5 再 Base64，再传入 contentMd5B64；path 仍为路径不含 Query，如 /api/open/v1/orders。

时间戳与防重放

网关侧可配置时间戳、Nonce 等防重放策略，具体以阿里云控制台为准。

接口列表

curl -X POST "https://your-gateway.aliyuncs.com/api/open/v1/orders" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-ca-key: your_app_id" \
  -H "X-Ca-Signature: your_computed_signature" \
  -d '{
    "merchant_order_no": "M20260104001",
    "product_code": "HF-100-0001",
    "recharge_account": "13800138000"
  }'

{
    "code": 0,
    "message": "订单创建成功",
    "data": {
        "order_no": "ORDER-20260104-A1B2C3D4",
        "merchant_order_no": "M20260104001",
        "product_code": "HF-100-0001",
        "product_name": "话费充值100元",
        "face_value": "100.00",
        "amount": "95.00",
        "recharge_account": "13800138000",
        "order_status": "PAID",
        "order_status_code": 2,
        "delivery_status": "WAITING",
        "delivery_status_code": 0,
        "create_time": "2026-01-04 10:00:00",
        "complete_time": null,
        "refund_reason": null
    },
    "timestamp": 1704355200
}

curl -X GET "https://your-gateway.aliyuncs.com/api/open/v1/orders/ORDER-20260104-A1B2C3D4" \
  -H "Accept: application/json" \
  -H "x-ca-key: your_app_id" \
  -H "X-Ca-Signature: your_computed_signature"

curl -X GET "https://your-gateway.aliyuncs.com/api/open/v1/orders?merchant_order_no=M20260104001" \
  -H "Accept: application/json" \
  -H "x-ca-key: your_app_id" \
  -H "X-Ca-Signature: your_computed_signature"

curl -X GET "https://your-gateway.aliyuncs.com/api/open/v1/balance" \
  -H "Accept: application/json" \
  -H "x-ca-key: your_app_id" \
  -H "X-Ca-Signature: your_computed_signature"

{
    "code": 0,
    "message": "success",
    "data": {
        "cash_balance": "10000.00",
        "credit_limit": "5000.00",
        "used_credit": "1000.00",
        "available_credit": "4000.00",
        "available_balance": "14000.00",
        "frozen_amount": "0.00"
    },
    "timestamp": 1704355200
}

curl -X GET "https://your-gateway.aliyuncs.com/api/open/v1/products?page=1&page_size=20" \
  -H "Accept: application/json" \
  -H "x-ca-key: your_app_id" \
  -H "X-Ca-Signature: your_computed_signature"

{
    "code": 0,
    "message": "success",
    "data": {
        "list": [
            {
                "product_code": "HF-100-0001",
                "product_name": "话费充值100元",
                "category": "话费充值",
                "face_value": "100.00",
                "supply_price": "95.00",
                "delivery_type": 1,
                "recharge_account_type": 2,
                "stock_status": 1,
                "daily_limit": 1000,
                "daily_remaining": 800
            }
        ],
        "pagination": {
            "total": 50,
            "page": 1,
            "page_size": 20,
            "total_pages": 3
        }
    },
    "timestamp": 1704355200
}

回调通知

订单状态变更时，系统会向 notify_url 发送 HTTP POST 请求。

回调请求

请求方式：POST · Content-Type：application/json

回调参数

回调示例

{
    "order_no": "ORDER-20260104-A1B2C3D4",
    "merchant_order_no": "M20260104001",
    "order_status": "COMPLETED",
    "order_status_code": 5,
    "delivery_status": "SUCCESS",
    "delivery_status_code": 2,
    "complete_time": "2026-01-04 10:05:00",
    "refund_reason": null,
    "timestamp": 1704355500,
    "sign": "a1b2c3d4e5f6..."
}

回调签名验证

使用与请求签名相同的算法验证回调签名：

# 去掉 sign 参数后验证
params = {k: v for k, v in callback_data.items() if k != 'sign'}
expected_sign = generate_sign(params, app_secret)
is_valid = callback_data['sign'].lower() == expected_sign.lower()

响应要求

返回 JSON 格式：

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

• 返回 code=0 表示接收成功
• 其他返回视为失败，系统会重试

重试机制

最多重试 10 次，建议实现幂等处理。

状态码说明

订单状态（order_status）

发货状态（delivery_status）

发货类型（delivery_type）

充值账号类型（recharge_account_type）

最佳实践

1. 订单创建

• 使用唯一的 merchant_order_no，建议格式：{日期}{序号}
• 实现幂等处理，避免重复下单
• 下单前先查询余额，避免余额不足

2. 状态查询

• 不要频繁轮询，建议间隔 10 秒以上
• 优先使用回调通知获取状态

3. 回调处理

• 验证回调签名，防止伪造
• 实现幂等处理，相同订单号只处理一次
• 快速返回响应，异步处理业务

4. 异常处理

• 网络超时：重试请求
• 业务错误：根据错误码处理
• 系统错误：记录日志，联系技术支持

技术支持