Wafeq API 技能

Wafeq 会计与电子发票平台的完整 API 参考文档。

设置

要使用此技能，您需要一个 Wafeq API 密钥：

1. 登录 Wafeq
2. 进入 设置 → API 密钥（直接链接）
3. 创建一个新的 API 密钥
4. 设置环境变量：

   export WAFEQ_API_KEY='your-key-here'
   

   或在 ~/.openclaw/openclaw.json 中配置：

   { "skills": { "entries": { "wafeq-api": { "apiKey": "your-key-here" } } } }
   

⚠️ 安全性：切勿将 API 密钥硬编码在代码、提示词（prompts）或技能文件中。请始终通过 WAFEQ_API_KEY 环境变量传入，或在 ~/.openclaw/openclaw.json 中通过 skills.entries.wafeq-api.apiKey 进行配置。

您可通过在插件根目录下运行 scripts/setup.sh 来验证配置是否生效。

快速参考

• 基础 URL： https://api.wafeq.com/v1/
• 认证（API 密钥）： Authorization: Api-Key $WAFEQ_API_KEY — 密钥获取地址：https://app.wafeq.com/c/api-keys
• 认证（OAuth2）： Authorization: Bearer — 请联系 Wafeq 获取客户端凭据
• 幂等性： 在 POST/PUT/PATCH/DELETE 请求中添加请求头 X-Wafeq-Idempotency-Key: （缓存 1 小时；若重放请求，响应中将包含 X-Wafeq-Idempotent-Replayed: true）
• 分页： 使用查询参数 ?page=1&page_size=25；响应结构为：{ count, next, previous, results[] }
• Content-Type： application/json
• 币种代码： ISO 4217 标准（完整列表见 references/enums.md）
• 实体 ID： 带前缀的字符串（例如 cnt_...、acc_...、inv_...）

标准 CRUD 模式

大多数资源遵循以下端点模式： POST /{resource}/、GET /{resource}/、GET /{resource}/{id}/、PUT /{resource}/{id}/、PATCH /{resource}/{id}/、DELETE /{resource}/{id}/。部分资源还支持 GET /{resource}/{id}/download/ 以下载 PDF 文件。

明细项（line items）采用嵌套路径：/{resource}/{parent_id}/line-items/，同样支持完整的 CRUD 操作。

参考文档

常见工作流

创建并发送发票

1. 创建联系人：POST /contacts/
2. 获取收入类科目：GET /accounts/?classification=REVENUE
3. 获取税率：GET /tax-rates/
4. 创建发票：POST /invoices/（需提供 line_items、contact、currency、invoice_date、invoice_due_date、invoice_number 等字段）
5. 向税务机关申报：POST /invoices/{id}/tax-authority/report/
6. 下载 PDF：GET /invoices/{id}/download/

批量发送发票（适用于电商 / 高频场景）

1. 调用 POST /api-invoices/bulk_send/，传入包含多个发票对象的数组，并在每个对象中指定 channels 字段用于邮件投递
2. 响应示例：{ "queued": N }
3. 生成汇总报告：GET /api-invoices/summary/

记录费用

1. 获取费用类科目：GET /accounts/?classification=EXPENSE
2. 创建费用：POST /expenses/，需提供 paid_through_account、contact、date、currency、tax_amount_type 和 line_items

记录针对发票的付款

1. 调用 POST /payments/，并在请求体中通过 invoice_payments 数组关联发票 ID 与对应金额

生成财务报表

• 资产负债表：GET /reports/balance-sheet/?currency=SAR&date=2025-12-31
• 利润表：GET /reports/profit-and-loss/?currency=SAR&date_after=2025-01-01&date_before=2025-12-31
• 现金流量表：GET /reports/cash-flow/?currency=SAR&date_after=2025-01-01&date_before=2025-12-31
• 试算平衡表：GET /reports/trial-balance/?from_date=2025-01-01&to_date=2025-12-31

报价单转发票

1. 创建报价单：POST /quotes/
2. 转换为发票：POST /quotes/{id}/invoice/

重要说明

• 税务机关申报 支持对标准发票、简化版发票和贷项凭证进行操作，接口路径为 POST /{resource}/{id}/tax-authority/report/
• 简化版发票 适用于 B2C 场景（无需买方税务登记号）
• 标准发票 适用于 B2B 场景
• 供应地（Place of supply） 字段为阿联酋专属字段（填写所属酋长国代码，或值为 OUTSIDE_UAE）
• 建议使用 reference 字段作为唯一标识符，防止重复创建资源