> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # 发票列表 > 分页查询发票列表，支持按订阅、客户、状态筛选。 ## OpenAPI ````yaml /zh/api/invoice-openapi.json get /api/v1/invoices openapi: 3.1.0 info: title: StablePay 发票 API version: '2026-04-20' description: 独立的发票查询 API，用于按发票 ID 查询详情或分页查询发票列表。发票 API 与订阅 API 分开维护。 servers: - url: https://api.stablepay.co description: 生产环境 security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: 发票 description: 查询订阅发票。 paths: /api/v1/invoices: get: tags: - 发票 summary: 发票列表 description: 分页查询发票列表，支持按订阅、客户、状态筛选。 operationId: listInvoices parameters: - name: subscription_id in: query description: 按订阅 ID 筛选。 schema: type: string - name: customer in: query description: 按客户 ID 筛选。 schema: type: string - name: status in: query description: 按发票状态筛选，仅支持 `open`、`paid`、`void`。 schema: $ref: '#/components/schemas/InvoiceStatus' - name: limit in: query description: 返回数量，默认 10，最大 100。 schema: type: integer default: 10 minimum: 1 maximum: 100 - name: starting_after in: query description: 向后分页游标。当前实现按 `invoice_id > starting_after` 查询。 schema: type: string - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' responses: '200': description: 查询成功。 content: application/json: schema: $ref: '#/components/schemas/InvoiceList' '400': description: 请求参数错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 认证失败。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务器错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: InvoiceStatus: type: string enum: - open - paid - void description: 发票状态。查询参数必须使用小写值：`open`、`paid`、`void`。 InvoiceList: type: object properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/Invoice' has_more: type: boolean description: 是否还有更多数据。当前实现按返回数量是否等于 limit 判断。 url: type: string description: 当前查询 URL。 ErrorResponse: type: object description: 错误响应。 properties: error: type: object properties: type: type: string description: 错误类型。 code: type: string description: 错误代码。 message: type: string description: 错误信息。 param: type: string description: 相关参数。 doc_url: type: string description: 错误文档链接。 decline_code: type: string description: 拒绝代码。 request_log_url: type: string description: 请求日志链接。 charge: type: string description: 相关支付 ID。 request_id: type: string description: 请求 ID。 timestamp: type: integer format: int64 description: 错误发生时间，Unix 秒。 Invoice: type: object required: - id - object - subscription_id - customer - amount_due - amount_paid - amount_remaining - currency - status - payment_status - billing_reason - period_start - period_end - created properties: id: type: string description: 发票 ID。 object: type: string example: invoice subscription_id: type: string description: 关联订阅 ID。 customer: type: string description: 客户 ID。 amount_due: type: integer format: int64 description: 应付金额，使用最小单位。 amount_paid: type: integer format: int64 description: 已支付金额，使用最小单位。 amount_remaining: type: integer format: int64 description: 未支付金额，使用最小单位。 currency: type: string description: 币种。 status: $ref: '#/components/schemas/InvoiceStatus' payment_status: type: string enum: - pending - processing - completed - failed - canceled - expired description: 发票支付状态。 billing_reason: type: string description: 开票原因，例如 `subscription_create`、`subscription_cycle`。 frequency: type: string description: 计费频率展示文本，例如 `Monthly`。 recurring_interval: type: string enum: - day - week - month - year description: 重复计费周期。 recurring_interval_count: type: integer format: int32 description: 重复计费周期数量。 period_start: type: integer format: int64 description: 计费周期开始，Unix 秒。 period_end: type: integer format: int64 description: 计费周期结束，Unix 秒。 payment_id: type: string description: 关联支付会话 ID。优先返回 payment_session_id，其次返回 trade_order_id。 paid_at: type: integer format: int64 description: 支付完成时间，Unix 秒。 due_date: type: integer format: int64 description: 到期时间，Unix 秒。 created: type: integer format: int64 description: 创建时间，Unix 秒。 parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 schema: type: string example: a1b2c3d4e5f6... securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key，例如 `Bearer sk_live_xxx`。 stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 ````