API 文档

将结算凭证接入您的业务系统 · API v1

概览

SettleGen 开放 API 允许认证企业以自己的主体身份程序化开具结算凭证。所有接口均为 HTTPS JSON API（本演示环境为 HTTP），基础路径为 /api/v1。

凭证一律以认证主体名义由服务端开具：请求中的销售方、印章、二维码等身份字段会被忽略并强制覆写。
每次成功开具计入按量计费（免费额度优先，余额不足返回 402）。
开具结果立即可在 /verify?no=凭证编号 查验页查到。

认证

在工作台「API 密钥」页创建密钥（形如 sk_xxxx，明文仅创建时展示一次）。请求时通过任一方式携带：

X-API-Key: sk_your_api_key
# 或
Authorization: Bearer sk_your_api_key

密钥绑定企业主体；撤销后立即失效。企业处于待审核 / 已驳回状态时接口返回 403 unvalidated_enterprise。

开具凭证

POST/api/v1/receipts

开具一张结算凭证。默认返回 JSON（含 PDF base64）；加查询参数 ?format=pdf 直接返回 PDF 字节流。

CA 数字签署通道（企业开通后自动启用）：若企业已完成 CA 开通，凭证走君子签自动签署：响应中 receipt.signState 为 signing、charged 为 pending_ca_sign、 pdfBase64 为空；签署成功后才扣费（轮询 GET /receipts/{serial} 至 signState=signed 后再取 ?format=pdf，未完成时返回 409 sign_not_ready）。签署失败用 POST /receipts/{serial}/sign-retry 重试（复用原编号，不重复计费）。

请求示例（curl）

curl -X POST "http://127.0.0.1:4173/api/v1/receipts" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customNo": "REC-2026-0042",
    "issueDate": "2026-09-04",
    "buyerName": "上海某某贸易有限公司",
    "buyerTaxId": "91310100MA1EXAMPLE",
    "issuer": "李开票",
    "remark": "2026 年 Q3 服务费",
    "items": [
      { "name": "技术服务费", "unit": "次", "quantity": "1", "unitPrice": "20000" }
    ]
  }'

响应（201）

{
  "receipt": {
    "serial": "SG20260904000007",
    "customNo": "REC-2026-0042",
    "status": "active",
    "signChannel": "local",   // local=平台电子印章（同步完成）；junziqian=CA 数字签署（异步）
    "signState": "signed",    // signing / signed / failed / charge_pending
    "applyNo": "",            // CA 通道的君子签签署流水号
    "buyerName": "上海某某贸易有限公司",
    "amountTotal": 20000,
    "issueDate": "2026-09-04",
    "issuedVia": "api",
    "verifyUrl": "http://127.0.0.1:4173/verify?no=SG20260904000007",
    "sha256": "…"
  },
  "charged": "free",          // free=本月免费额度；credits=充值额度扣 1 张；pending_ca_sign=CA 签署成功后扣费
  "balanceAfter": 200,
  "freeRemaining": 5,
  "pdfBase64": "JVBERi0xLjcK…"
}

Node.js 示例

const response = await fetch(`${BASE_URL}/api/v1/receipts`, {
  method: "POST",
  headers: { "X-API-Key": process.env.SETTLEGEN_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    issueDate: "2026-09-04",
    buyerName: "上海某某贸易有限公司",
    items: [{ name: "技术服务费", quantity: "1", unitPrice: "20000" }],
  }),
});
const result = await response.json();
fs.writeFileSync(`${result.receipt.serial}.pdf`, Buffer.from(result.pdfBase64, "base64"));

凭证字段说明

字段	类型	必填	说明
`template`	string	否	票据风格：`classic`（默认，传统票据 · 行业通用版式）、`modern`（现代商务蓝）或 `red`（红色收据 · 参考件原样版式）。非法值回退默认。
`customNo`	string	否	外部单号，1-24 位字母 / 数字 / 连字符，企业内唯一；留空时凭证面打印系统编号。
`issueDate`	string	否	开具日期 `YYYY-MM-DD`，默认当天。
`buyerName`	string	是	购买方单位名称，≤60 字。
`buyerTaxId`	string	否	购买方统一社会信用代码，≤24 字。
`issuer`	string	否	开票人姓名，≤18 字。
`remark`	string	否	备注，≤180 字，打印在凭证备注栏。
`items`	array	是	结算项目，1-6 项，至少一项有名称。
`items[].name`	string	是	项目名称（至少一项非空）。
`items[].spec / unit`	string	否	规格型号、单位。
`items[].quantity / unitPrice`	string	否	数量、单价；金额留空时按数量 × 单价自动计算。
`items[].amount`	string	否	显式金额（字符串数字，避免浮点误差）。
`autoUppercase`	boolean	否	默认 true 自动生成大写金额；false 时使用 `uppercaseOverride`。
`uppercaseOverride`	string	否	自定义大写金额，≤42 字。
`sealText`	string	否	印章类型：`财务专用章 / 结算专用章 / 收款专用章`，默认取企业认证时配置的类型。

忽略字段：请求中的 sellerName / sellerTaxId / stamp.* / qr.* / footerText 等身份字段一律被服务端覆写为认证主体与平台查验文案，提交不生效。

批量开具

POST/api/v1/receipts/batch

两种请求体：{"items": [凭证对象, …]}（最多 50 个），或 {"csv": "表格文本"}（与网页批量模板同格式）。逐张独立成败，额度不足时中断剩余行。

curl -X POST "http://127.0.0.1:4173/api/v1/receipts/batch" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "buyerName": "北京某某科技有限公司", "items": [{ "name": "服务费", "amount": "8000" }] },
      { "buyerName": "广州某某设计工作室", "items": [{ "name": "设计费", "amount": "5600" }] }
    ]
  }'

响应（200，节选）

{
  "issued":  [ { "index": 1, "serial": "SG20260904000008", "amountTotal": 8000, "charged": "free" } ],
  "failures": [ { "index": 2, "code": "validation_failed", "message": "…" } ],
  "zipBase64": "UEsDBBQ…",   // 已开具 PDF 的 ZIP 包
  "balanceAfter": 199,
  "freeRemaining": 4
}

查询与作废

GET/api/v1/receipts

分页查询本企业凭证：?offset=0&limit=20。

GET/api/v1/receipts/{serial}

查询单张详情（含完整打印数据 payload）；?format=pdf 直接下载 PDF（CA 签署中返回 409 sign_not_ready，轮询至 signState=signed 后再取）。仅能访问本企业的凭证。

POST/api/v1/receipts/{serial}/sign-retry

CA 签署失败后重试：复用原凭证编号重新提交君子签签署，成功前不计费。仅 signState=failed 的凭证可调用。

POST/api/v1/receipts/{serial}/void

作废凭证，请求体 {"reason": "开具有误"}。作废后查验页显示「已作废」，额度不退还；CA 签署中的凭证需等待签署完成或失败后才能作废（409 sign_in_progress）。带 CA 签名的已签文件物理上不可撤回，作废为平台状态标记。

账户与用量

GET/api/v1/account

返回企业信息、充值额度余额、当月免费剩余与价格配置。

GET/api/v1/account/usage?month=2026-09

返回指定账期（默认当月）的计费流水与汇总。

Python 示例

import os, requests

BASE = "http://127.0.0.1:4173"
headers = {"X-API-Key": os.environ["SETTLEGEN_KEY"]}

account = requests.get(f"{BASE}/api/v1/account", headers=headers).json()
print(account["balance"], account["freeRemaining"])

错误码

所有错误返回统一信封：{"error": {"code": "…", "message": "…", "issues": [{"field": "…", "message": "…"}]}}。

HTTP	code	说明
400	`validation_failed`	凭证数据校验未通过，`issues` 给出逐字段问题。
400	`invalid_json`	请求体不是有效 JSON。
401	`unauthorized`	缺少 / 错误 / 已撤销的 API 密钥。
402	`insufficient_balance`	免费与充值额度均不足，请充值后重试。
403	`unvalidated_enterprise`	企业主体未通过认证审核。
404	`not_found`	凭证或资源不存在（或不属于本企业）。
409	`sign_not_ready`	CA 签署尚未完成（或失败 / 待扣费），暂不能下载 PDF。
409	`sign_in_progress`	凭证正在 CA 签署中，暂不能作废。
413	`payload_too_large`	请求体超过 10MB。
429	`rate_limited`	超出限流，响应头含 `Retry-After`。
500	`server_error`	服务器内部错误（已记录日志）。

限流与计费

限流：每密钥 60 次 / 分钟（内存令牌桶）。需要更高配额请联系平台。
计费：成功开具一张计一张（免费额度优先），失败不计费；批量按实际成功张数计费。CA 通道以签署成功为计费时点，签署中的凭证会占用可用额度。
幂等建议：为每次业务开具携带唯一 customNo，重复提交会返回 validation_failed（外部单号已被使用），可作为防重依据。
时间：所有时间为 ISO 8601 UTC。