Solavel 文档
中文
开发者参考

SolaCount Finance API

版本: v1 基础 URL: https://solavel.com/api/v1 (替换为您的域名) 格式: JSON 33 个端点

SolaCount Finance API 让您以编程方式读取和写入会计数据,包括客户、供应商、客户发票、供应商账单、付款、日记账分录和财务报表。所有端点均返回 JSON。创建 API 密钥 →

身份验证

每个受保护的端点都需要三个请求头:

X-API-Key: solabooks_<prefix>.<secret>
X-Organization-Id: 1
X-Client-Id: 4
  • X-API-Key——创建时在“设置 → API 访问”中仅显示一次的完整密钥
  • X-Organization-Id——您组织的整数 ID(可在 API 访问页面查看)
  • X-Client-Id——您的客户端 ID(可在 API 访问页面查看)
生成密钥: 转到 设置 → API 访问 在 SolaCount 中。完整密钥只显示一次。每个密钥都有权限范围——只授予您需要的权限。

GET /api/v1/health 端点无需身份验证,可用于验证连通性。

响应格式

所有响应都使用一致的 JSON 封装格式。

单个对象

{
  "success": true,
  "data": { ... }
}

分页列表

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

错误

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message."
  }
}

快速测试

请将 your_key、1 和 4 替换为您实际的 API 密钥、组织 ID 和客户端 ID。

健康检查(无需身份验证)

curl https://solacount.com/api/v1/health

发票列表

curl https://solacount.com/api/v1/invoices \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4"

创建客户

curl -X POST https://solacount.com/api/v1/customers \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo Customer","email":"billing@example.com"}'

创建会计分录

curl -X POST https://solacount.com/api/v1/journal-entries \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-06-07",
    "reference": "JE-001",
    "description": "Manual accrual",
    "lines": [
      {"account_id": 101, "debit": 1000, "credit": 0},
      {"account_id": 202, "debit": 0, "credit": 1000}
    ]
  }'

所有端点

点击任意端点可展开其详情。共 8 个资源组,33 个端点。

健康度

GET /api/v1/health 无认证

确认 API 在线并正常响应。无需身份验证。

响应 HTTP 200

{"success":true,"data":{"service":"finance-api","status":"ok","timestamp":"2026-06-07T12:00:00+00:00"}}

客户

GET /api/v1/customers 范围: customers.get

列出所有客户。支持搜索和分页。

查询参数

参数类型描述
search string 可选 按姓名、邮箱或电话筛选(部分匹配)
page integer 可选 页码(默认:1)
per_page integer 可选 每页结果数(默认:25,最多:100)

响应 HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}],"meta":{"current_page":1,"per_page":25,"total":3,"last_page":1}}
GET /api/v1/customers/{id} 范围: customers.get

按 ID 检索单个客户。

响应 HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}}
POST /api/v1/customers 范围: customers.post

创建新客户。

请求正文 (JSON)

字段类型描述
name string 必填 客户名称
email string 可选 电子邮件地址(必须是有效的电子邮件)
phone string 可选 电话号码(最多 50 个字符)
is_active boolean 可选 有效状态(默认:true)

响应 HTTP 201

{"success":true,"data":{"id":42,"name":"Demo Customer","email":"billing@example.com","phone":null,"is_active":true}}

供应商

GET /api/v1/suppliers 范围: suppliers.get

列出所有供应商。支持搜索和分页。

查询参数

参数类型描述
search string 可选 按姓名筛选(部分匹配)
page integer 可选 页码
per_page integer 可选 每页结果数(最多 100)

响应 HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}],"meta":{"current_page":1,"per_page":25,"total":1,"last_page":1}}
GET /api/v1/suppliers/{id} 范围: suppliers.get

按 ID 检索单个供应商。

响应 HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Supplier","email":"ap@example.com","phone":null,"tax_id":"GB123456789","is_overseas":false,"is_vat_registered":true,"reverse_charge":false}}
POST /api/v1/suppliers 范围: suppliers.post

创建新供应商。

请求正文 (JSON)

字段类型描述
name string 必填 供应商名称
email string 可选 电子邮件地址
phone string 可选 电话号码
tax_id string 可选 增值税 / 税务登记号
is_overseas boolean 可选 供应商是否为海外供应商(默认值:false)
is_vat_registered boolean 可选 已注册增值税(默认:true)
reverse_charge boolean 可选 适用反向征收增值税(默认:false)

响应 HTTP 201

{"success":true,"data":{"id":15,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}}

发票

GET /api/v1/invoices 范围: invoices.get

列出所有发票及其客户关联。支持状态筛选和分页。

查询参数

参数类型描述
status string 可选 筛选:draft | unpaid | paid | void | overdue
page integer 可选 页码
per_page integer 可选 每页结果数(最多 100)

响应 HTTP 200

{"success":true,"data":[{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","total":5000.00,"customer":{"id":1,"name":"Demo Customer"}}],"meta":{"current_page":1,"per_page":25,"total":48,"last_page":2}}
GET /api/v1/invoices/{id} 范围: invoices.get

检索单张发票及其客户和明细行。

响应 HTTP 200

{"success":true,"data":{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","subtotal":4347.83,"tax_total":652.17,"total":5000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[{"id":1,"description":"Consulting services","qty":10,"unit_price":434.78,"total":4347.83}]}}
POST /api/v1/invoices 范围: invoices.post

创建新发票。以 status=draft 状态创建,并自动生成编号。

请求正文 (JSON)

字段类型描述
customer_id integer 必填 现有客户的 ID
date date 必填 发票日期(YYYY-MM-DD)
due_date date 可选 付款到期日(YYYY-MM-DD)
notes string 可选 内部或面向客户的备注
subtotal decimal 可选 税前合计(默认:0)
tax_total decimal 可选 税额(默认:0)
discount_total decimal 可选 折扣金额(默认:0)
total decimal 可选 总计(默认:0)

响应 HTTP 201

{"success":true,"data":{"id":102,"number":"INV-00102","status":"draft","date":"2026-06-07","due_date":"2026-07-07","total":5000.00,"customer_id":1}}
PUT /api/v1/invoices/{id} 范围: invoices.update

更新现有的草稿发票。所有字段均为可选。

请求正文 (JSON)

字段类型描述
customer_id integer 可选 新客户 ID
date date 可选 发票日期(YYYY-MM-DD)
due_date date 可选 付款到期日
notes string 可选 注释
subtotal decimal 可选 税前合计
tax_total decimal 可选 税额
total decimal 可选 总计

响应 HTTP 200

{"success":true,"data":{"id":102,"status":"draft","total":6000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[]}}
POST /api/v1/invoices/{id}/post 范围: invoices.post

将草稿发票过账到总账。需要总额 > 0 并填写日期。状态变为未付款。

响应 HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z","total":5000.00}}

可能的错误: invoice_already_posted, invoice_total_required, invoice_date_required

POST /api/v1/invoices/{id}/void 范围: invoices.void

作废已过账的发票。冲销所有分类账分录,并将发票标记为作废。

响应 HTTP 200

{"success":true,"data":{"id":102,"status":"void"}}
POST /api/v1/invoices/{id}/mark-sent 范围: invoices.send

将草稿发票标记为已发送给客户(状态由草稿变为未付)。幂等操作。

响应 HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid"}}
DELETE /api/v1/invoices/{id} 范围: invoices.delete

永久删除草稿发票及其所有明细行。无法删除已过账的发票或已有付款分配的发票。

响应 HTTP 200

{"success":true,"data":{"message":"Invoice deleted."}}

可能的错误: posted_invoice_not_deletable, invoice_has_allocations

账单

GET /api/v1/bills 范围: bills.get

列出所有供应商账单。支持状态筛选和分页。

查询参数

参数类型描述
status string 可选 筛选:draft | unpaid | paid | void
page integer 可选 页码
per_page integer 可选 每页结果数(最多 100)

响应 HTTP 200

{"success":true,"data":[{"id":55,"number":"BILL-00055","date":"2026-06-01","status":"draft","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"}}],"meta":{"current_page":1,"per_page":25,"total":12,"last_page":1}}
GET /api/v1/bills/{id} 范围: bills.get

检索单张账单及其供应商和明细行。

响应 HTTP 200

{"success":true,"data":{"id":55,"number":"BILL-00055","date":"2026-06-01","due_date":"2026-07-01","status":"draft","reference":"PO-001","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"},"lines":[]}}
POST /api/v1/bills 范围: bills.post

创建新的供应商账单。以 status=draft 状态创建,并自动生成 BILL-XXXXX 编号。

请求正文 (JSON)

字段类型描述
supplier_id integer 必填 现有供应商的 ID
date date 必填 账单日期(YYYY-MM-DD)
due_date date 可选 付款到期日
reference string 可选 供应商参考 / 采购单号(最多 120 个字符)
notes string 可选 内部备注
subtotal decimal 可选 税前合计(默认:0)
tax_total decimal 可选 税额(默认:0)
discount_total decimal 可选 折扣(默认:0)
total decimal 可选 总计(默认:0)

响应 HTTP 201

{"success":true,"data":{"id":56,"number":"BILL-00056","status":"draft","date":"2026-06-07","total":2000.00,"supplier_id":3}}
PUT /api/v1/bills/{id} 范围: bills.update

更新现有的草稿账单。所有字段均为可选。

请求正文 (JSON)

字段类型描述
supplier_id integer 可选 新供应商 ID
date date 可选 账单日期
due_date date 可选 付款到期日
reference string 可选 供应商参考
total decimal 可选 总计

响应 HTTP 200

{"success":true,"data":{"id":56,"status":"draft","total":2500.00,"supplier":{"id":3,"name":"Demo Supplier"}}}
POST /api/v1/bills/{id}/post 范围: bills.post

将草稿账单过账到总账,登记应付款项。

响应 HTTP 200

{"success":true,"data":{"id":56,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z"}}

可能的错误: bill_post_failed

DELETE /api/v1/bills/{id} 范围: bills.delete

永久删除草稿账单。账单必须处于草稿状态且没有付款分配。

响应 HTTP 200

{"success":true,"data":{"message":"Bill deleted."}}

可能的错误: posted_bill_not_deletable, bill_has_allocations

付款

GET /api/v1/payments 范围: payments.get

列出所有付款(收款和付款)。

查询参数

参数类型描述
type string 可选 筛选:receipt | disbursement
status string 可选 筛选:draft | posted
page integer 可选 页码
per_page integer 可选 每页结果数(最多 100)

响应 HTTP 200

{"success":true,"data":[{"id":20,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","customer_id":1}],"meta":{"current_page":1,"per_page":25,"total":8,"last_page":1}}
POST /api/v1/payments 范围: payments.post

记录收款(客户已付款)或付款(您已向供应商付款)。可选择分配到发票或账单。

请求正文 (JSON)

字段类型描述
type string 必填 receipt(客户付款)或 disbursement(供应商付款)
payment_date date 必填 付款日期(YYYY-MM-DD)
amount_total decimal 必填 已付总金额(必须大于 0)
method string 可选 付款方式,例如 bank_transfer、cash、card
reference string 可选 银行参考号或支票号码(最多 120 个字符)
description string 可选 描述或备注
customer_id integer 条件 收款所需(若 document_type=ar_invoice,则从发票推断)
supplier_id integer 条件 付款支出所需(若 document_type=ap_bill,则从账单推断)
document_type string 可选 "ar_invoice" 或 "ap_bill" — 触发自动分配
document_id integer 可选 要分配到的发票或账单 ID(设置了 document_type 时必填)
allocated_amount decimal 可选 待分配金额(默认为 amount_total)

响应 HTTP 201

{"success":true,"data":{"id":21,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","allocations":[{"document_type":"ar_invoice","document_id":101,"allocated_amount":5000.00}]}}

可能的错误: document_required, document_type_mismatch, invoice_not_found, bill_not_found, client_required, supplier_required

日记账分录

GET /api/v1/journal-entries 范围: journal_entries.get

列出分录及其行和科目。支持按日期范围筛选。

查询参数

参数类型描述
status string 可选 筛选:draft | posted
from date 可选 开始日期(YYYY-MM-DD)
to date 可选 结束日期(YYYY-MM-DD)
page integer 可选 页码
per_page integer 可选 每页结果数(最多 100)

响应 HTTP 200

{"success":true,"data":[{"id":5,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","lines_count":2}],"meta":{"current_page":1,"per_page":25,"total":5,"last_page":1}}
POST /api/v1/journal-entries 范围: journal_entries.post

创建并立即过账平衡的日记账分录。借方合计必须等于贷方合计(容差 ±0.01)。

请求正文 (JSON)

字段类型描述
date date 必填 录入日期(YYYY-MM-DD)
reference string 可选 参考代码,例如 JE-001(最多 120 个字符)
description string 可选 备注 / 描述(最多 2000 个字符)
lines array 必填 至少 2 行。每行包括:account_id(必填)、debit(小数)、credit(小数)、description(字符串)

响应 HTTP 201

{"success":true,"data":{"id":6,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","posted_at":"2026-06-07T12:00:00Z","lines":[{"account_id":101,"account":{"code":"1100","name":"Cash"},"debit":1000,"credit":0},{"account_id":202,"account":{"code":"3000","name":"Equity"},"debit":0,"credit":1000}]}}

可能的错误: journal_not_balanced

DELETE /api/v1/journal-entries/{id} 范围: journal_entries.delete

删除未过账的日记账分录。已过账的分录无法通过 API 删除。

响应 HTTP 200

{"success":true,"data":{"message":"Journal entry deleted."}}

可能的错误: posted_journal_not_deletable

报告列表

所有报表接口都接受 ?from=YYYY-MM-DD&to=YYYY-MM-DD。资产负债表、试算平衡表和账龄报表还接受 ?as_of=YYYY-MM-DD(等同于 to)。

GET /api/v1/reports/income-statement 范围: reports.income_statement

利润表。显示指定期间的收入、支出和净收入。

查询参数

参数类型描述
from date 可选 期间开始(YYYY-MM-DD)
to date 可选 期间结束(YYYY-MM-DD)

响应 HTTP 200

{"success":true,"data":{"revenue":150000,"expenses":85000,"net_income":65000}}
GET /api/v1/reports/balance-sheet 范围: reports.balance_sheet

资产负债表快照。返回截至指定日期的资产、负债和权益。

查询参数

参数类型描述
to date 可选 截至日期(YYYY-MM-DD)。也可使用 ?as_of= 参数。

响应 HTTP 200

{"success":true,"data":{"assets":{"total":250000},"liabilities":{"total":80000},"equity":{"total":170000}}}
GET /api/v1/reports/cash-flow 范围: reports.cash_flow

指定期间的现金流量表(直接法)。

查询参数

参数类型描述
from date 可选 期间开始
to date 可选 期间结束

响应 HTTP 200

{"success":true,"data":{"operating":45000,"investing":-12000,"financing":-8000,"net_change":25000}}
GET /api/v1/reports/trial-balance 范围: reports.trial_balance

试算平衡表,显示截至某日所有科目的借方和贷方合计。

查询参数

参数类型描述
to date 可选 截至日期(YYYY-MM-DD)

响应 HTTP 200

{"success":true,"data":[{"account_code":"1100","account_name":"Cash","debit":50000,"credit":0},{"account_code":"2000","account_name":"Accounts Payable","debit":0,"credit":15000}]}
GET /api/v1/reports/ar-aging 范围: reports.ar_aging

应收账款账龄。未结客户发票按逾期时长分组。

查询参数

参数类型描述
to date 可选 账龄截止日期(YYYY-MM-DD)

响应 HTTP 200

{"success":true,"data":{"current":12000,"1_30":3500,"31_60":800,"61_90":0,"over_90":500,"total":16800}}
GET /api/v1/reports/ap-aging 范围: reports.ap_aging

应付账款账龄。未结供应商账单按逾期时长分组。

查询参数

参数类型描述
to date 可选 账龄截止日期(YYYY-MM-DD)

响应 HTTP 200

{"success":true,"data":{"current":8000,"1_30":1200,"31_60":0,"61_90":0,"over_90":0,"total":9200}}
GET /api/v1/reports/tax 范围: reports.tax

增值税 / 税务汇总。返回该期间销售已收税款和采购已付税款。

查询参数

参数类型描述
from date 可选 期间开始
to date 可选 期间结束

响应 HTTP 200

{"success":true,"data":{"tax_collected":15000,"tax_paid":4200,"net_vat_payable":10800}}

错误参考

错误代码 HTTP 含义
invoice_already_posted 422 发票已过账到分类账
invoice_total_required 422 无法过账总额为零或为负的发票
invoice_date_required 422 过账前需要填写单据日期
posted_invoice_not_deletable 422 删除前请先作废或取消过账发票
invoice_has_allocations 422 删除前请先移除付款分配
posted_bill_not_deletable 422 无法删除已过账或非草稿状态的账单
bill_has_allocations 422 删除前请先移除付款分配
bill_post_failed 422 账单未通过内部过账验证
journal_not_balanced 422 借方合计与贷方合计不相等
posted_journal_not_deletable 422 只能删除草稿(未过账)条目
document_required 422 设置 document_type 时,必须填写 document_id
document_type_mismatch 422 ar_invoice 需要 receipt;ap_bill 需要 disbursement
invoice_not_found 404 该 ID 的发票不存在
bill_not_found 404 具有该 ID 的账单不存在
client_required 422 customer_id 是 receipt 付款所必需的
supplier_required 422 supplier_id 是 disbursement 付款所必需的

分页

所有列表接口都返回分页结果。使用查询参数控制分页:

参数默认最大值描述
page1—要获取的页码
per_page25100每页结果数

每个列表响应中的 meta 对象都包含 current_page、per_page、total 和 last_page。