> ## 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.

# 查询发票

> 根据发票 ID 获取发票详情。



## OpenAPI

````yaml /zh/api/invoice-openapi.json get /api/v1/invoices/{invoice_id}
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/{invoice_id}:
    get:
      tags:
        - 发票
      summary: 查询发票
      description: 根据发票 ID 获取发票详情。
      operationId: getInvoice
      parameters:
        - $ref: '#/components/parameters/InvoiceId'
        - $ref: '#/components/parameters/XStablePayTimestamp'
        - $ref: '#/components/parameters/XStablePayNonce'
        - $ref: '#/components/parameters/XStablePaySignature'
      responses:
        '200':
          description: 查询成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          description: 请求参数错误。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 认证失败。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 发票不存在或无权限访问。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器错误。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    InvoiceId:
      name: invoice_id
      in: path
      required: true
      description: 发票 ID。
      schema:
        type: string
    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...
  schemas:
    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 秒。
    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 秒。
    InvoiceStatus:
      type: string
      enum:
        - open
        - paid
        - void
      description: 发票状态。查询参数必须使用小写值：`open`、`paid`、`void`。
  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` 为空字符串。

````