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

# 获取账单下载地址

> 为当前商户已有的单个账单文件签发临时下载地址。

校验账单属于当前商户后，为已有账单文件签发临时下载地址。 下载地址有效期为 600 秒。调用方获得地址后直接从 OSS 下载文件。

<Note>
  下载地址有效期为 **600 秒**。该接口只签发已有文件的地址，不生成、合并或重新计算账单。
</Note>

## 认证与请求头

使用 Bearer API Key，并同时携带以下签名请求头。GET 请求的 `requestBody` 为空字符串，签名字符串为 `{timestamp}.{nonce}.`，使用商户 API Secret 计算 HMAC-SHA256 并转换为小写 hex。详见[认证与签名](/zh/api/getting-started#认证与签名)。

<ParamField header="Authorization" type="string" required>
  Bearer API Key，格式：`Bearer sk_live_xxx`。
</ParamField>

<ParamField header="X-StablePay-Timestamp" type="string" required>
  Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
</ParamField>

<ParamField header="X-StablePay-Nonce" type="string" required>
  防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 最短 16 个字符。 最长 64 个字符。
</ParamField>

<ParamField header="X-StablePay-Signature" type="string" required>
  使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。
</ParamField>

## 路径参数

<ParamField path="bill_id" type="string" required>
  账单 ID。建议直接使用查询账单接口返回的字符串值。 匹配规则：`^[1-9][0-9]*$`。
</ParamField>

## 成功响应

HTTP `200`，`application/json`。下载地址签发成功。

<ResponseField name="bill_id" type="string" required>
  账单 ID。
</ResponseField>

<ResponseField name="filename" type="string" required>
  下载文件名。
</ResponseField>

<ResponseField name="content_type" type="string" required>
  文件媒体类型，例如 `text/csv`。
</ResponseField>

<ResponseField name="download_url" type="string" required>
  OSS 临时签名下载地址。该地址包含访问凭证，请勿公开或长期保存。 格式：`uri`。
</ResponseField>

<ResponseField name="expires_in" type="integer" required>
  下载地址剩余有效时间，单位为秒。 取值：`600`。
</ResponseField>

## 错误响应

| HTTP 状态码 | 说明 |
| - | - |
| 400 | 账单 ID 或请求参数不合法。 |
| 401 | 认证失败。 |
| 404 | 账单不存在、不属于当前商户，或账单文件不存在。 |
| 410 | 历史账单文件不符合当前商户隔离规则，无法提供下载。 |
| 422 | 账单记录存在，但账单文件尚不可用。 |
| 503 | BillProd、OSS 或其他依赖服务暂时不可用。 |

### 服务错误结构

<ResponseField name="error" type="object" required>
  <Expandable title="字段">
    <ResponseField name="code" type="string" required>
      错误代码，例如 `invalid_parameter`、`resource_not_found`、 `historical_report_unavailable`、`report_incomplete` 或 `service_unavailable`。
    </ResponseField>

    <ResponseField name="message" type="string" required>
      错误信息。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string" required>
  请求 ID。
</ResponseField>

<ResponseField name="timestamp" type="integer" required>
  错误发生时间，Unix 秒。 格式：`int64`。
</ResponseField>

### 网关认证错误结构

API 网关在请求进入 PaymentProd 前可能返回以下结构的 HTTP `401` 响应。

<ResponseField name="status" type="string" required>
  取值：`error`。
</ResponseField>

<ResponseField name="error" type="string" required>
  认证失败原因。
</ResponseField>

请直接使用[查询账单](/zh/api/bills/list)返回的字符串 `bill_id`。下载地址包含访问凭证，请勿公开或长期保存。

<RequestExample>
  ```bash cURL theme={"system"}
  TIMESTAMP=$(date +%s)
  NONCE=$(uuidgen)
  SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}." | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')

  curl --get 'https://api.stablepay.co/api/v1/bills/1234567890/download_url' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
    -H "X-StablePay-Nonce: ${NONCE}" \
    -H "X-StablePay-Signature: ${SIGNATURE}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200（示例） theme={"system"}
  {
    "bill_id": "1234567890",
    "filename": "payment-2026-09-01.csv",
    "content_type": "text/csv",
    "download_url": "https://example.com/bills/payment-2026-09-01.csv?signature=example",
    "expires_in": 600
  }
  ```

  ```json 服务错误（示例） theme={"system"}
  {
    "error": {
      "code": "invalid_parameter",
      "message": "请求参数不合法"
    },
    "request_id": "req_example",
    "timestamp": 1790812800
  }
  ```

  ```json 网关认证错误（示例） theme={"system"}
  {
    "status": "error",
    "error": "认证失败"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.