面向开发者

API 文档

以编程方式上传、处理银行对账单并下载为 Excel 的参考文档。

即将推出

API 密钥

您将在控制台中创建密钥，并从服务器调用下方的接口。本页面展示了 API 上线后的工作方式。

身份验证

在每个请求的 Authorization 请求头中发送您的 API 密钥。请将其保存在服务器上，切勿放在浏览器或移动应用中。

Authorization: Bearer <your_api_key>

基础 URL

https://api.bayainy.com/api/v1

POST/upload/preview

上传前预览

识别每一页 (数字版或扫描版) 并计算确切的页数费用，不会扣费。

POST /upload/preview HTTP/1.1
Authorization: Bearer <your_api_key>
Content-Type: multipart/form-data
 
file: statement.pdf

响应

{
  "page_count": 3,
  "digital_pages": 2,
  "scanned_pages": 1,
  "credit_cost": 4,
  "pages": [
    { "page": 1, "type": "digital" },
    { "page": 2, "type": "digital" },
    { "page": 3, "type": "scanned" }
  ]
}

POST/upload

上传对账单

上传 PDF 以开始提取。对账单的状态从 pending 开始，并自动进入 processing。

POST /upload HTTP/1.1
Authorization: Bearer <your_api_key>
Content-Type: multipart/form-data
 
file: statement.pdf

响应

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "statement.pdf",
  "status": "pending",
  "page_count": 3,
  "estimated_seconds": 6
}

GET/statements/{id}

获取对账单及其交易

用于了解处理何时完成，并取回提取出的交易和余额。

注：每隔几秒查询一次此接口，直到状态从 processing 变为 completed (或 failed)。

GET /statements/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Authorization: Bearer <your_api_key>

响应

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "bank_name": "Al Rajhi Bank",
  "transaction_count": 42,
  "opening_balance": 12480.00,
  "closing_balance": 24755.00,
  "available_exports": ["excel", "csv", "qbo", "xml"],
  "transactions": [
    {
      "date": "2026-09-01",
      "description": "Card purchase, Panda",
      "debit": 184.50,
      "credit": 0.00,
      "balance": 12295.50,
      "category": "grocery",
      "reference": "FT26244S1K7Q",
      "page_number": 1
    }
  ]
}

交易字段

datestring

交易日期，格式为 YYYY-MM-DD。

descriptionstring

交易内容，已去除参考号。

debitnumber

支出金额。始终为正数，没有时为 0。

creditnumber

收入金额。始终为正数，没有时为 0。

balancenumber

该行印出的当前余额。透支时为负数。

categorystring

支出类别，例如 grocery、transfer、fuel。

referencestring | null

银行自己的参考号 (如有印出)。

page_numberinteger

该行所在的 PDF 页码。

GET/statements

列出您的对账单

返回与您的账户关联的所有对账单，最新的在前。

GET /statements HTTP/1.1
Authorization: Bearer <your_api_key>

响应

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "statement.pdf",
    "status": "completed",
    "transaction_count": 42
  }
]

GET/download/{id}/{format}

下载文件

仅在状态为 completed 后可用。您的方案包含的格式列在 available_exports 中。

excelcsvqboquickbooksxmlodoozohomt940camt053iif

GET /download/550e8400-e29b-41d4-a716-446655440000/excel HTTP/1.1
Authorization: Bearer <your_api_key>

响应

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 
<binary .xlsx file>

DELETE/statements/{id}

删除对账单

删除对账单及其交易和文件。此操作无法撤销。

DELETE /statements/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Authorization: Bearer <your_api_key>

响应

HTTP/1.1 204 No Content

可能的状态值

状态含义

pending

已接收，即将开始。

queued

正在排队等待。

processing

正在提取。

completed

交易和文件已准备就绪。

failed

无法处理。原因见 error_message。

对集成有疑问？

联系我们