申请费率导出
申请生成一个包含 requester 费率的 CSV 文件,可以包含所有账户,也可以只包含一个账户。文件在后台生成:响应返回导出申请的 key,文件就绪时会通过 invoice_export webhook 通知。
Endpoint
ENDPOINT
/billing/invoices/exports方法
POSTSTATUS
201认证
需要对请求进行签名。参见认证。requester 即签署该请求的凭证所属的 requester。
请求体
所有字段均为可选。空请求体({})导出该 requester 的全部费率,但须遵守下方的规模规则。
| 字段 | 类型 | 必填 | 描述 | 长度 |
|---|---|---|---|---|
start_date | string | 否 | 周期起始日期,格式为 yyyy-mm-dd,包含当天。 | 10 |
end_date | string | 否 | 周期结束日期,格式为 yyyy-mm-dd,包含当天。不得早于 start_date。 | 10 |
payment_method | string | 否 | 费率的支付方式。 payment_method 枚举值 | — |
status | string | 否 | 费率状态。 status 枚举值 | — |
billing_types | array | 否 | 要包含的费率类型(billing_type)。为空时包含全部类型。 | — |
owner_document_number | string | 否 | 账户持有人的 CPF 或 CNPJ,仅数字。导出该持有人所有账户的费率。 | — |
account_number | string | 否 | 账号,不含校验位。 | — |
owner_name | string | 否 | 持有人姓名的开头部分。将导出按持有人姓名 筛选返回的前 50 个账户的费率。 | — |
account_key | uuid | 否 | 账户 key,用于只导出一个账户的费率对账单。不能与上面三个字段同时使用。 | 36 |
规模规则
- 周期不超过 31 天(包含首尾两天):申请始终会被接受。
- 周期超过 31 天,或未提供
start_date和end_date:如果 requester(发送account_key时为该账户)在该周期内的费率不超过 200,000 条(不计其他筛选条件),申请会被接受。超过该数量时,响应为422 BLL000136,且不会创建任何导出申请。请选择更短的周期。
进行中的申请
- 如果与另一个仍在进行中的申请筛选条件相同,不会创建新申请:响应返回已有的申请,并带有
already_in_flight: true。 - 每个 requester 最多可以有 20 个进行中的申请(
pending或processing)。第 21 个会收到422 BLL000134。
{
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"payment_method": "bank_slip",
"status": "open",
"billing_types": ["account_maintenance"],
"owner_document_number": "96969879003"
}
响应
| 字段 | 类型 | 描述 |
|---|---|---|
invoice_export_key | uuid | 导出申请的 key。用于查询导出申请。 |
status | string | 导出申请状态。 导出申请状态枚举值 |
filters | object | 规范化后的筛选条件:包含请求体的所有字段,未发送的字段为 null。 |
row_count | integer | 已写入文件的费率数量。仅在 done 时为最终值。 |
created_at | string | 申请的日期和时间。 |
finished_at | string | 文件就绪的日期和时间。done 之前为 null。 |
expires_at | string | 文件可下载的截止日期和时间。done 之前为 null。 |
file_name | string | 在此响应中始终为 null。 |
download_url | string | 在此响应中始终为 null。下载链接在查询导出申请时生成。 |
already_in_flight | boolean | 当响应返回的是筛选条件相同的进行中申请时为 true。 |
{
"invoice_export_key": "7a9c0a5e-1b2f-4c3d-9e8f-0123456789ab",
"status": "pending",
"filters": {
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"payment_method": "bank_slip",
"status": "open",
"billing_types": ["account_maintenance"],
"owner_document_number": "96969879003",
"account_number": null,
"owner_name": null,
"account_key": null
},
"row_count": 0,
"created_at": "2026-10-15T14:03:11",
"finished_at": null,
"expires_at": null,
"file_name": null,
"download_url": null,
"already_in_flight": false
}
错误
| Status | 代码 | 描述 |
|---|---|---|
| 400 | QIT000001 | 请求体格式不符:未知字段、类型错误或 account_key 不是 36 个字符。 |
| 400 | BLL000096 | 日期不符合 yyyy-mm-dd 格式,或 end_date 早于 start_date。 |
| 400 | BLL000043 | status 不在枚举值中。 |
| 400 | BLL000130 | payment_method 不在枚举值中。 |
| 400 | BLL000137 | account_key 与 owner_document_number、account_number 或 owner_name 同时发送。 |
| 404 | BLL000111 | 某个 billing_types 不存在。 |
| 404 | BLL000058 | account_key 不是该 requester 的账户。 |
| 422 | BLL000134 | 该 requester 已有 20 个进行中的申请。请等待其中一个完成。 |
| 422 | BLL000136 | 周期超过 31 天且费率超过 200,000 条。请选择更短的周期。 |
错误响应体采用标准格式(title、description、translation、code)。上表列出了本 endpoint 的错误码;平台通用错误(如 QIT000001)参见 BaaS 错误目录中的通用错误。
枚举值
payment_method 枚举值
| 值 | 描述 |
|---|---|
account_debit | 从持有人账户扣款。 |
centralizing_account_debit | 从 requester 的集 中账户扣款。 |
bank_slip | 通过 boleto(银行付款单)收取。 |
account_debit_and_bank_slip | 部分从账户扣款,其余通过 boleto 收取。 |
status 枚举值
| 值 | 描述 |
|---|---|
open | 未结费率。 |
pending | 等待付款。 |
paid | 已结清费率。 |
written_off | 已核销费率。 |
导出申请状态枚举值
| 值 | 描述 |
|---|---|
pending | 申请已登记,等待处理。 |
processing | 文件生成中。 |
done | 文件已就绪,可在 expires_at 之前下载。 |
expired | 文件在 7 天期限后已删除。请重新申请。 |
相关 Webhook
文件就绪时,requester 会收到 invoice_export webhook。
下一步
查询费率导出以获取下载链接。