SolaCount Finance API
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 访问页面查看)
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 个端点。
健康度
/api/v1/health
无认证
确认 API 在线并正常响应。无需身份验证。
响应 HTTP 200
{"success":true,"data":{"service":"finance-api","status":"ok","timestamp":"2026-06-07T12:00:00+00:00"}}
客户
/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}}
/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}}
/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}}
供应商
/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}}
/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}}
/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}}
发票
/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}}
/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}]}}
/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}}
/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":[]}}
/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
/api/v1/invoices/{id}/void
范围: invoices.void
作废已过账的发票。冲销所有分类账分录,并将发票标记为作废。
响应 HTTP 200
{"success":true,"data":{"id":102,"status":"void"}}
/api/v1/invoices/{id}/mark-sent
范围: invoices.send
将草稿发票标记为已发送给客户(状态由草稿变为未付)。幂等操作。
响应 HTTP 200
{"success":true,"data":{"id":102,"status":"unpaid"}}
/api/v1/invoices/{id}
范围: invoices.delete
永久删除草稿发票及其所有明细行。无法删除已过账的发票或已有付款分配的发票。
响应 HTTP 200
{"success":true,"data":{"message":"Invoice deleted."}}
可能的错误:
posted_invoice_not_deletable,
invoice_has_allocations
账单
/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}}
/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":[]}}
/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}}
/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"}}}
/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
/api/v1/bills/{id}
范围: bills.delete
永久删除草稿账单。账单必须处于草稿状态且没有付款分配。
响应 HTTP 200
{"success":true,"data":{"message":"Bill deleted."}}
可能的错误:
posted_bill_not_deletable,
bill_has_allocations
付款
/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}}
/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
日记账分录
/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}}
/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
/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)。
/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}}
/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}}}
/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}}
/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}]}
/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}}
/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}}
/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 付款所必需的
|
分页
所有列表接口都返回分页结果。使用查询参数控制分页:
| 参数 | 默认 | 最大值 | 描述 |
|---|---|---|---|
page | 1 | — | 要获取的页码 |
per_page | 25 | 100 | 每页结果数 |
每个列表响应中的 meta 对象都包含 current_page、per_page、total 和 last_page。