{
    "openapi": "3.1.0",
    "info": {
        "title": "Cloudsign OpenAPI · 账号与账单",
        "version": "1.22.0-preview.1",
        "description": "通过用户开放 API 管理自己账号下已授权的企业签名和应用分发资源，完成上传、签名、发布、查询和订单处理。接入前请在开发者中心创建 API 应用并配置权限。\n按产品筛选操作的契约，请求字段、默认值和权限与完整契约一致。应用分发列表须显式传 module=distribution。"
    },
    "servers": [
        {
            "url": "https://{host}",
            "variables": {
                "host": {
                    "default": "www.fenfa.im",
                    "description": "配置的主网站域名，不是分发或存储域名"
                }
            }
        }
    ],
    "security": [
        {
            "AccessKeySignature": []
        }
    ],
    "components": {
        "parameters": {
            "Date": {
                "name": "X-Api-Date",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "date-time"
                },
                "description": "UTC，YYYY-MM-DDTHH:mm:ssZ，前后 300 秒窗口"
            },
            "Nonce": {
                "name": "X-Api-Nonce",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{32}$"
                }
            },
            "BodyHash": {
                "name": "X-Api-Content-Sha256",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                },
                "description": "实际请求体字节的 SHA-256；GET 为零字节摘要"
            },
            "Environment": {
                "name": "X-Api-Environment",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "const": "production"
                }
            }
        },
        "schemas": {
            "AccountBalance": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "available",
                    "currency",
                    "observed_at"
                ],
                "properties": {
                    "available": {
                        "type": "string",
                        "pattern": "^-?[0-9]{1,11}\\.[0-9]{2}$"
                    },
                    "currency": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "code",
                            "unit",
                            "external_settlement"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "unit": {
                                "type": "string"
                            },
                            "external_settlement": {
                                "type": "string"
                            }
                        }
                    },
                    "observed_at": {
                        "type": "integer",
                        "minimum": 0
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "request_id",
                    "error"
                ],
                "properties": {
                    "request_id": {
                        "type": "string"
                    },
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "AccountOrders": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "items",
                    "next_cursor",
                    "currency",
                    "historical_complete"
                ],
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                                "id",
                                "app_id",
                                "order_number",
                                "description",
                                "amount",
                                "status",
                                "payment_method",
                                "created_at",
                                "paid_at"
                            ],
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "app_id": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "pattern": "^A[a-f0-9]{32}$"
                                },
                                "order_number": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string"
                                },
                                "amount": {
                                    "type": "string",
                                    "pattern": "^-?[0-9]{1,11}\\.[0-9]{2}$"
                                },
                                "status": {
                                    "type": "string",
                                    "enum": [
                                        "paid",
                                        "pending",
                                        "closed",
                                        "refunded",
                                        "unknown"
                                    ]
                                },
                                "payment_method": {
                                    "type": "string",
                                    "enum": [
                                        "alipay",
                                        "wechat",
                                        "balance",
                                        "admin",
                                        "usdt_gateway",
                                        "usdt_tron",
                                        "other"
                                    ]
                                },
                                "created_at": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "paid_at": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ],
                                    "minimum": 0
                                }
                            }
                        }
                    },
                    "next_cursor": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "pattern": "^O[a-f0-9]{32}$"
                    },
                    "currency": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "code",
                            "unit",
                            "external_settlement"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "unit": {
                                "type": "string"
                            },
                            "external_settlement": {
                                "type": "string"
                            }
                        }
                    },
                    "historical_complete": {
                        "type": "boolean"
                    }
                }
            },
            "AccountLedger": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "items",
                    "next_cursor",
                    "currency",
                    "historical_complete"
                ],
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                                "id",
                                "app_id",
                                "before",
                                "change",
                                "after",
                                "event_type",
                                "title",
                                "created_at"
                            ],
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "app_id": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "pattern": "^A[a-f0-9]{32}$"
                                },
                                "before": {
                                    "type": "string",
                                    "pattern": "^-?[0-9]{1,11}\\.[0-9]{2}$"
                                },
                                "change": {
                                    "type": "string",
                                    "pattern": "^-?[0-9]{1,11}\\.[0-9]{2}$"
                                },
                                "after": {
                                    "type": "string",
                                    "pattern": "^-?[0-9]{1,11}\\.[0-9]{2}$"
                                },
                                "event_type": {
                                    "type": "string"
                                },
                                "title": {
                                    "type": "string"
                                },
                                "created_at": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            }
                        }
                    },
                    "next_cursor": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "pattern": "^L[a-f0-9]{32}$"
                    },
                    "currency": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "code",
                            "unit",
                            "external_settlement"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "unit": {
                                "type": "string"
                            },
                            "external_settlement": {
                                "type": "string"
                            }
                        }
                    },
                    "historical_complete": {
                        "type": "boolean"
                    }
                }
            },
            "PaymentBudget": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "currency",
                    "timezone",
                    "observed_at",
                    "account",
                    "application",
                    "financial_health"
                ],
                "properties": {
                    "currency": {
                        "$ref": "#/components/schemas/PurchaseCurrency"
                    },
                    "timezone": {
                        "type": "string",
                        "const": "Asia/Shanghai"
                    },
                    "observed_at": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "account": {
                        "$ref": "#/components/schemas/BudgetScope"
                    },
                    "application": {
                        "$ref": "#/components/schemas/BudgetScope"
                    },
                    "financial_health": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "payment_quarantined",
                            "checked_at"
                        ],
                        "properties": {
                            "payment_quarantined": {
                                "type": "boolean"
                            },
                            "checked_at": {
                                "type": "integer",
                                "minimum": 0
                            }
                        }
                    }
                }
            },
            "PurchaseCurrency": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "code",
                    "unit",
                    "external_settlement",
                    "revision"
                ],
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string"
                    },
                    "external_settlement": {
                        "type": "string",
                        "const": "payment_provider"
                    },
                    "revision": {
                        "type": "string",
                        "pattern": "^C[a-f0-9]{64}$"
                    }
                }
            },
            "BudgetScope": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "enabled",
                    "currency_current",
                    "single_limit",
                    "daily",
                    "monthly"
                ],
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "currency_current": {
                        "type": "boolean"
                    },
                    "single_limit": {
                        "type": "string",
                        "pattern": "^(?:0|[1-9][0-9]{0,8})\\.[0-9]{2}$"
                    },
                    "daily": {
                        "$ref": "#/components/schemas/BudgetPeriod"
                    },
                    "monthly": {
                        "$ref": "#/components/schemas/BudgetPeriod"
                    }
                }
            },
            "BudgetPeriod": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "limit",
                    "used",
                    "remaining",
                    "resets_at"
                ],
                "properties": {
                    "limit": {
                        "type": "string",
                        "pattern": "^(?:0|[1-9][0-9]{0,8})\\.[0-9]{2}$"
                    },
                    "used": {
                        "type": "string",
                        "pattern": "^(?:0|[1-9][0-9]{0,12})\\.[0-9]{2}$"
                    },
                    "remaining": {
                        "type": "string",
                        "pattern": "^(?:0|[1-9][0-9]{0,8})\\.[0-9]{2}$"
                    },
                    "resets_at": {
                        "type": "integer",
                        "minimum": 0
                    }
                }
            }
        },
        "responses": {
            "Error": {
                "description": "400 请求格式；401 凭据无效/过期；403 未授权；404 资源不存在或不可见；405 方法不支持；409 nonce 重放；429 限流（Retry-After 秒）；503 平台关闭或依赖不可用。通过验签的失败请求也须使用新 nonce 重试。",
                "headers": {
                    "X-Request-Id": {
                        "schema": {
                            "type": "string"
                        }
                    },
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "securitySchemes": {
            "AccessKeySignature": {
                "type": "apiKey",
                "in": "header",
                "name": "Authorization",
                "description": "CS1-HMAC-SHA256 Credential=AKP<40hex> 或 AKT<40hex>,Signature=<64hex>。签入 Host、路径、规范查询和 X-Api-* 字段。AKT 必须携带 X-Api-Security-Token，并在 canonical 原有结尾追加换行和 Token 的 SHA-256 摘要；AKP 不携带该头。Secret 不发送给 API。"
            }
        }
    },
    "paths": {
        "/api/v1/billing/balance": {
            "get": {
                "operationId": "getBalance",
                "summary": "查询账号可用余额",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    }
                ],
                "description": "读取本账号的 available、站内金额单位与观测时间。金额为十进制字符串，展示和记账应保留小数精度。",
                "responses": {
                    "200": {
                        "description": "成功；禁止缓存",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/AccountBalance"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "tags": [
                    "账号与账单"
                ],
                "x-cloudsign-products": [
                    "account"
                ]
            }
        },
        "/api/v1/billing/orders": {
            "get": {
                "operationId": "listOrders",
                "summary": "查询账号订单",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^O[a-f0-9]{32}$"
                        }
                    }
                ],
                "description": "按状态分页查询本人订单。保存 next_cursor 查询下一页。订单描述、支付方式和金额均按返回值展示，后台充值是订单的支付来源之一。",
                "responses": {
                    "200": {
                        "description": "成功；禁止缓存",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/AccountOrders"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "tags": [
                    "账号与账单"
                ],
                "x-cloudsign-products": [
                    "account"
                ]
            }
        },
        "/api/v1/billing/ledger": {
            "get": {
                "operationId": "listLedger",
                "summary": "查询账号资金流水",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^L[a-f0-9]{32}$"
                        }
                    }
                ],
                "description": "分页读取有真实记录的变动前余额、变动额和变动后余额。历史数据覆盖范围见 historical_complete，原样使用返回的游标。",
                "responses": {
                    "200": {
                        "description": "成功；禁止缓存",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/AccountLedger"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "tags": [
                    "账号与账单"
                ],
                "x-cloudsign-products": [
                    "account"
                ]
            }
        },
        "/api/v1/billing/budget": {
            "get": {
                "operationId": "getPaymentBudget",
                "summary": "查询费用预算与剩余额度",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    }
                ],
                "description": "分别查看账号与本 API 应用的单笔上限、日/月已用与剩余预算。付款同时受两层额度约束，余额与预算请分别查询。\n\n仅父 AKP；须独立 billing:ReadBudget、全部资源范围及账号财务读取许可。查询账号和当前 API 应用预算，不授予扣款权限，不返回其他 API 应用详情。",
                "responses": {
                    "200": {
                        "description": "成功；禁止缓存",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/PaymentBudget"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "tags": [
                    "账号与账单"
                ],
                "x-cloudsign-products": [
                    "account"
                ]
            }
        }
    },
    "x-cloudsign-webhooks": "webhooks-v1.json",
    "tags": [
        {
            "name": "账号与账单",
            "description": "查询本人账号的余额、API 费用预算、订单和资金流水。账单查询与付款分别授权；账号级账单需要覆盖全部自有应用的范围。"
        }
    ],
    "x-cloudsign-product": "account"
}
