> API 文档

JSONBill 完整 API 参考 - 从 JSON 数据创建 PDF 发票与结算单

概述

JSONBill 是一个超轻量级的基于 JSON 的账单系统。它提供 RESTful API，用于从 JSON 数据创建 PDF 发票与结算单。

相关文档： x402 支付

身份验证

所有 API 端点都需要通过 Authorization 请求头进行身份验证：

Authorization: Bearer <token>

<token> 可以是 JWT token 或 API key，系统会自动检测 token 类型。

点数

每次生成 PDF 消耗 1 个 Quaily 点数。使用 API key 身份验证时，系统会在创建任务前检查您的点数余额。请确保账户中有足够的点数。

x402 支付（v2）

JSONBill 支持 x402 v2 链上按次支付。支持的网络/资产：Base（eip155:8453）USDC。

使用 x402 支付时不需要 Authorization 请求头。详细说明：见 x402 支付文档。

流程：

不带 PAYMENT-SIGNATURE 调用 POST /tasks/docs。
返回 402 Payment Required，响应头包含 PAYMENT-REQUIRED（base64 的 PaymentRequired JSON）。
使用 x402 客户端签名后，携带 PAYMENT-SIGNATURE 重试。

重试示例（仅头部）：

Content-Type: application/json
PAYMENT-SIGNATURE: <base64 payment payload>

API 端点

创建文档任务

端点： POST /tasks/docs

描述： 从 JSON 数据创建新的 PDF 发票 / 结算单生成任务。

请求头：

Content-Type: application/json
Authorization: Bearer <token>

请求体示例：

{
  "type": "invoice",
  "lang": "zh_cn",
  "theme": "classic",
  "params": {
    "id": "20260102-INC-1",
    "date": "2026-01-02T09:30:01.001Z",
    "currency": "USD",
    "company_name": "示例公司",
    "company_address": "加州帕萨迪纳市红木街102号，邮编98812",
    "company_email": "john@example.com",
    "tax_number": "123456789Z",
    "bill_to_company": "你好公司",
    "bill_to_address": "乔治市AZ教堂街2楼，邮编119802",
    "doc": {
      "title": "Invoice",
      "description": "2025年12月咨询服务"
    },
    "summary": {
      "period_start": "2025-12-01T00:00:00.000Z",
      "period_end": "2026-01-01T00:00:00.000Z",
      "title": "咨询服务",
      "currency": "USD",
      "total_include_tax": 10000,
      "tax_rate": 0.08,
      "total_include_tax_quote_amount": 75000,
      "total_include_tax_quote_symbol": "CNY"
    },
    "detail_items": [
      {
        "date": "2025-12-15T00:00:00.000Z",
        "title": "项目Alpha - 第一阶段",
        "desc": "初始开发和设置",
        "currency": "USD",
        "total_include_tax": 5000,
        "total_include_tax_quote_amount": 37500,
        "total_include_tax_quote_symbol": "CNY"
      },
      {
        "date": "2025-12-28T00:00:00.000Z",
        "title": "项目Alpha - 第二阶段",
        "desc": "测试和部署",
        "url": "https://example.com/project-alpha",
        "total_include_tax": 5000
      }
    ],
    "payment": {
      "instruction": {
        "receive_account_bank": "乔治银行",
        "receive_account_branch": "红木街支行",
        "receive_account_number": "12345-113",
        "receive_deposit_type": "活期",
        "receive_account_name": "示例公司"
      }
    }
  }
}

请求参数：

参数	类型	必填	说明
`type`	string	否	文档类型：`invoice` 或 `settlementstatement`。默认：`invoice`
`lang`	string	否	语言代码（`en`、`ja`、`zh_cn`、`zh_tw`）。默认：`en`
`theme`	string	否	文档主题。默认：`classic`
`params`	object	是	文档数据（见文档数据格式）

结算单说明：

使用 recipient_company / recipient_address 替代 bill_to_company / bill_to_address。
payment.instruction 会被忽略，仅展示 payment.result。

可用主题：

主题	说明
`classic`	传统发票布局，与基础输出一致
`modern`	仪表盘风格，账单和摘要采用双栏布局
`compact`	modern 的紧凑版，减少留白，更适合单页显示
`spotlight`	总金额/付款金额突出显示在前，便于快速浏览
`ledger`	会计风格，明细在前，汇总在后
`split`	明细在前，页脚双栏显示付款和摘要信息

查看各主题 PDF 效果示例：主题示例。

响应：

{
  "data": {
    "id": 1,
    "trace_id": "f4730554-791c-463b-9a27-aeacdfb02cf2",
    "status": 0,
    "created_at": "2026-01-02T09:30:01.001Z",
    "updated_at": "2026-01-02T09:30:01.001Z"
  },
  "ts": 1767766187
}

任务状态码：

0：初始化（任务已创建）
1：已调度
2：运行中
3：已完成
4：错误

查询任务状态

端点： GET /tasks/{traceID}

描述： 查询文档生成任务的状态。

响应：

{
  "data": {
    "id": 1,
    "trace_id": "f4730554-791c-463b-9a27-aeacdfb02cf2",
    "status": 3,
    "created_at": "2026-01-02T09:30:01.001Z",
    "updated_at": "2026-01-02T09:30:05.001Z"
  },
  "ts": 1767766191
}

下载 PDF

端点： GET /tasks/{traceID}.pdf

描述： 下载生成的 PDF 文档。仅在任务状态为 3（已完成）时可用。

响应： PDF 文件

注意： PDF 文件将在 1 小时后从服务器删除。

查询点数余额

端点： GET /proxy/credits/balance

描述： 查询当前点数余额。

响应：

{
  "data": {
    "user_id": 123,
    "balance_credit": "10.00",
    "status": 1
  },
  "ts": 1767766187
}

文档数据格式

基本文档字段

字段	类型	必填	说明
`id`	string	否	文档编号
`date`	string	否	文档日期（ISO 8601 格式）
`currency`	string	否	货币代码（如 `USD`、`EUR`、`JPY`、`CNY`）。支持任意货币代码。
`company_name`	string	是	您的公司名称
`company_address`	string	否	您的公司地址
`company_email`	string	否	您的公司邮箱
`tax_number`	string	否	税务登记号
`bill_to_company`	string	否	客户公司名称（仅发票）
`bill_to_address`	string	否	客户地址（仅发票）
`recipient_company`	string	否	收款方公司名称（结算单）
`recipient_address`	string	否	收款方地址（结算单）
`doc`	object	否	文档信息（见文档字段）

文档字段

doc 对象用于设置文档上显示的标题和描述：

字段	类型	必填	说明
`title`	string	否	文档标题
`description`	string	否	文档描述

摘要字段

summary 对象包含文档汇总和账期信息：

字段	类型	必填	说明
`title`	string	否	摘要标题/说明
`period_start`	string	否	账期开始日期（ISO 8601）
`period_end`	string	否	账期结束日期（ISO 8601）
`currency`	string	否	本摘要的货币代码（默认使用顶层 `currency`）
`total_exclude_tax`	number	否	未含税总金额
`total_include_tax`	number	否	含税总金额
`tax`	number	否	税额
`tax_rate`	number	否	税率（如 `0.08` 表示 8%）
`total_include_tax_quote_amount`	number	否	参考货币的等值金额
`total_include_tax_quote_symbol`	string	否	参考货币符号（如 `CNY`）

说明：

total_exclude_tax 与 total_include_tax 二选一，不要同时提供。
使用 total_exclude_tax 时，可提供 tax 或 tax_rate 指定税额。

参考货币示例：

当使用 USD 开票但客户希望看到当地货币的等值金额时：

"summary": {
  "total_include_tax": 10000,
  "total_include_tax_quote_amount": 75000,
  "total_include_tax_quote_symbol": "CNY"
}

这将在文档上显示隐含汇率 1 USD = 7.5 CNY。

未含税示例：

"summary": {
  "total_exclude_tax": 9259.26,
  "tax": 740.74
}

明细项目

detail_items 数组包含文档的各行项目：

字段	类型	必填	说明
`date`	string	否	项目日期（ISO 8601）
`title`	string	否	项目标题
`desc`	string	否	项目描述
`url`	string	否	相关链接
`currency`	string	否	本项目的货币代码（默认使用顶层 `currency`）
`total_exclude_tax`	number	否	项目未含税金额
`total_include_tax`	number	否	项目含税金额
`total_include_tax_quote_amount`	number	否	参考货币的等值金额（项目级）
`total_include_tax_quote_symbol`	string	否	参考货币符号（项目级）
`tax`	number	否	项目税额

说明：

total_exclude_tax 与 total_include_tax 二选一，不要同时提供。
使用 total_exclude_tax 时，可提供 tax 指定税额。

示例：

"detail_items": [
  {
    "date": "2025-12-15T00:00:00.000Z",
    "title": "咨询服务 - 第一周",
    "desc": "策略规划和分析",
    "total_exclude_tax": 2500,
    "tax": 200
  },
  {
    "date": "2025-12-22T00:00:00.000Z",
    "title": "咨询服务 - 第二周",
    "desc": "实施支持",
    "url": "https://example.com/report",
    "total_exclude_tax": 2500,
    "tax": 200
  }
]

付款方式

payment 对象包含两个可选部分：

instruction：付款指引（告诉客户如何付款）。
result：付款结果（可选）。

两部分都支持 disabled 字段，用于在文档中隐藏该部分。

结算单注意： 仅展示 payment.result，payment.instruction 会被忽略。

银行转账（指引）

"payment": {
  "instruction": {
    "receive_account_bank": "乔治银行",
    "receive_account_branch": "红木街支行",
    "receive_account_number": "12345-113",
    "receive_deposit_type": "活期",
    "receive_account_name": "示例公司"
  }
}

SWIFT 转账（指引）

"payment": {
  "instruction": {
    "receive_account_swift": "BOFAUS3N",
    "receive_account_number": "123456789",
    "receive_account_name": "示例公司",
    "receive_account_bank": "美国银行",
    "receive_account_branch": "Charlotte, NC"
  }
}

加密货币（指引）

"payment": {
  "instruction": {
    "receive_crypto_network": "ETH Mainnet",
    "receive_crypto_address": "0x1234567890abcdef1234567890abcdef12345678",
    "receive_crypto_currency": "USDC",
    "receive_crypto_memo": ""
  }
}

字段	描述
`instruction.receive_crypto_network`	区块链网络（如 ETH Mainnet、Polygon、Solana）
`instruction.receive_crypto_address`	用于接收付款的钱包地址
`instruction.receive_crypto_currency`	加密货币符号（如 USDC、USDT、ETH）
`instruction.receive_crypto_memo`	可选的备注或目标标签（用于 XRP、XLM 等网络）

付款结果（可选）

"payment": {
  "result": {
    "payment_method": "Bank transfer",
    "amount_paid": 5200,
    "currency": "USD",
    "paid_date": "2026-01-27",
    "tx_id": "TXN-12345"
  }
}

字段	描述
`result.payment_method`	实际付款方式（自由文本）
`result.amount_paid`	实际付款金额
`result.currency`	付款金额币种
`result.paid_date`	付款日期（ISO 字符串）
`result.tx_id`	交易或参考编号

目录

概述

身份验证

点数

x402 支付（v2）

API 端点

创建文档任务

查询任务状态

下载 PDF

查询点数余额

文档数据格式

基本文档字段

文档字段

摘要字段

明细项目

付款方式

银行转账（指引）

SWIFT 转账（指引）

加密货币（指引）

付款结果（可选）