Bukku API — HS Design Accounting Integration

Bukku API — HS Design 账目集成

通过 Bukku REST API 读取和分析 HS Design 会计数据。

公司信息

字段	值
公司名	HS Design (Health Space Interior)
SSM	202603001610 (PG0581660-U)
Bukku 子域名	hsdesign
Bukku 公司 ID	83394
Bukku URL	https://hsdesign.bukku.my
货币	MYR (RM)
创建人	Jake Ti

API 基础信息

项目	值
API 基础 URL	https://hsdesign.bukku.my/api
生产服务器	https://api.bukku.my
测试服务器	https://api.staging.bukku.dev
API 版本	v1.0
速率限制	600 次/分钟
文档	https://developers.bukku.my (SPA，需 JS 渲染)

认证方式

必需 Headers

Authorization: Bearer {access_token}
Company-Subdomain: hsdesign
Accept: application/json

⚠️ Company-Subdomain 是必填项！ 缺少此 header 会导致 403 “User is not authorised to access the company” 错误。

Access Token

Token 在 Bukku Web App 中获取： Control Panel → Integrations → API Access switch → Save → 获取 Access Token

Token 格式为 JWT，payload 示例：

{
  "iss": "https://hsdesign.bukku.my/settings/api",
  "sub": "106404",
  "prv": "..."
}

⚠️ Token 存储： 见 vault keychain 或 env 配置文件。不在文档中明文保存。

已发现的 API 端点

✅ 正常工作

端点	方法	说明	示例响应
/api/companies	GET	获取公司列表	{"companies":[{"id":83394,"legal_name":"HS Design","subdomain":"hsdesign"}]}
/api/sales/invoices	GET	销售发票列表（含分页）	返回 paging + transactions[]
/api/contacts	GET	联系人列表	已验证端点存在

待测试

端点	说明
/api/sales/quotations	报价单
/api/purchases	采购
/api/reports	报表
/api/banking	银行流水
/api/tax	税务
/api/products	产品

销售发票 API 详解

GET /api/sales/invoices

参数：

• page — 页码（默认 1）
• per_page — 每页条数（默认 30）

响应结构：

{
  "paging": {
    "current_page": 1,
    "per_page": 30,
    "total": 22
  },
  "transactions": [
    {
      "id": 260,
      "number": "IV-00024",
      "type": "sale_invoice",
      "contact_id": 42,
      "contact_name": "Kong Wang Yang",
      "date": "2026-05-26",
      "currency_code": "MYR",
      "currency_symbol": "RM",
      "amount": 4200,
      "balance": 2100,
      "status": "ready",
      "payment_mode": "credit",
      "description": "Pc frame multipoint casement with 8mm laminated glass",
      "title": "53, Jalan Anggerik 54, Taman Johor Jaya",
      "created_by": "Jake Ti",
      "term_items": [{"date": "2026-06-25", "amount": 4200, "balance": 2100}]
    }
  ]
}

关键字段说明：

• amount — 发票总金额
• balance — 未结余额（0 表示已结清）
• status — "ready" 表示已发布
• payment_mode — "credit" 表示信用/赊账
• term_items — 分期付款项，内有 date（到期日）和 balance（届时余额）
• contact_name — 客户名称

当前发票统计（截至 2026-05-26）

未结清发票：

发票号	客户	金额 (RM)	余额 (RM)	到期日
IV-00024	Kong Wang Yang	4,200	2,100	2026-06-25
IV-00023	Du En Bei	4,190	1,090	2026-06-25
IV-00007	Jeffley	1,860	1,860	2025-06-16

未收总额：RM 5,050

调用示例

# 获取公司列表
curl -s -H "Authorization: Bearer {token}" \
  -H "Company-Subdomain: hsdesign" \
  -H "Accept: application/json" \
  "https://hsdesign.bukku.my/api/companies"
 
# 获取销售发票
curl -s -H "Authorization: Bearer {token}" \
  -H "Company-Subdomain: hsdesign" \
  -H "Accept: application/json" \
  "https://hsdesign.bukku.my/api/sales/invoices"
 
# 获取联系人
curl -s -H "Authorization: Bearer {token}" \
  -H "Company-Subdomain: hsdesign" \
  -H "Accept: application/json" \
  "https://hsdesign.bukku.my/api/contacts"

相关链接

• Bukku Web App: https://hsdesign.bukku.my
• Bukku API 文档: https://developers.bukku.my
• 开发支持: [email protected]
• bukku-api-access — Agent 技能文档
• HS Design Overview — 公司概览