跳到主要内容

申请费率导出

申请生成一个包含 requester 费率的 CSV 文件,可以包含所有账户,也可以只包含一个账户。文件在后台生成:响应返回导出申请的 key,文件就绪时会通过 invoice_export webhook 通知。

Endpoint​

ENDPOINT
/billing/invoices/exports
方法
POST
STATUS
201

认证​

需要对请求进行签名。参见认证。requester 即签署该请求的凭证所属的 requester。

请求体​

所有字段均为可选。空请求体({})导出该 requester 的全部费率,但须遵守下方的规模规则。

字段类型必填描述长度
start_datestring否周期起始日期,格式为 yyyy-mm-dd,包含当天。10
end_datestring否周期结束日期,格式为 yyyy-mm-dd,包含当天。不得早于 start_date。10
payment_methodstring否费率的支付方式。 payment_method 枚举值—
statusstring否费率状态。 status 枚举值—
billing_typesarray否要包含的费率类型(billing_type)。为空时包含全部类型。—
owner_document_numberstring否账户持有人的 CPF 或 CNPJ,仅数字。导出该持有人所有账户的费率。—
account_numberstring否账号,不含校验位。—
owner_namestring否持有人姓名的开头部分。将导出按持有人姓名筛选返回的前 50 个账户的费率。—
account_keyuuid否账户 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_keyuuid导出申请的 key。用于查询导出申请。
statusstring导出申请状态。 导出申请状态枚举值
filtersobject规范化后的筛选条件:包含请求体的所有字段,未发送的字段为 null。
row_countinteger已写入文件的费率数量。仅在 done 时为最终值。
created_atstring申请的日期和时间。
finished_atstring文件就绪的日期和时间。done 之前为 null。
expires_atstring文件可下载的截止日期和时间。done 之前为 null。
file_namestring在此响应中始终为 null。
download_urlstring在此响应中始终为 null。下载链接在查询导出申请时生成。
already_in_flightboolean当响应返回的是筛选条件相同的进行中申请时为 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代码描述
400QIT000001请求体格式不符:未知字段、类型错误或 account_key 不是 36 个字符。
400BLL000096日期不符合 yyyy-mm-dd 格式,或 end_date 早于 start_date。
400BLL000043status 不在枚举值中。
400BLL000130payment_method 不在枚举值中。
400BLL000137account_key 与 owner_document_number、account_number 或 owner_name 同时发送。
404BLL000111某个 billing_types 不存在。
404BLL000058account_key 不是该 requester 的账户。
422BLL000134该 requester 已有 20 个进行中的申请。请等待其中一个完成。
422BLL000136周期超过 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。

下一步​

查询费率导出以获取下载链接。