什么是 Wafeq API？

Wafeq API 技能为 Wafeq 平台提供了功能齐全的参考和集成工具集。Wafeq 是专门为中东（特别是阿联酋和沙特阿拉伯）量身定制的领先会计解决方案。它使开发人员和自动化代理能够与 Wafeq REST API 交互，以管理业务财务的各个方面，从生成标准和简化的税务发票到跟踪支出以及生成实时财务报表。通过利用 Openclaw Skills，您可以简化会计工作流程，并通过自动化的数据处理和管理确保符合地区税务法规。

下载入口:https://github.com/openclaw/skills/tree/main/skills/yordilorenzo/wafeq

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Wafeq API 应用场景

• 针对阿联酋和沙特阿拉伯的税务合规性，自动化 B2B 和 B2C 电子发票。
• 使用批量发票创建接口，将电子商务销售与 Wafeq 同步。
• 通过程序化记录账单和支出，管理应付账款。
• 为高级数据分析生成实时的损益表或资产负债表。
• 自动将报价单转换为发票，并记录未结余额的付款。

1. 通过 Openclaw Skills 环境配置，使用 API 密钥或 OAuth2 令牌对 Wafeq 平台进行身份验证。
2. 使用特定的实体 ID 前缀（如 cnt_ 或 inv_）识别目标资源，例如联系人、账户或发票。
3. 执行标准 CRUD 操作或专门用于税务机关报告和 PDF 下载的接口。
4. 利用幂等性密钥确保安全重试，并防止财务记录中的重复交易。
5. 处理分页结果，以将大型数据集（如历史交易或客户列表）同步到您的本地环境中。

Wafeq API 配置指南

要开始使用此技能，请从您的 Wafeq 账户设置中获取 API 密钥。在终端中设置环境变量：

export WAFEQ_API_KEY='your-key-here'

或者，您可以在本地配置文件中配置该密钥，以启用 Openclaw Skills 访问 API：

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

Wafeq API 数据架构与分类体系

该技能通过带前缀的实体 ID 和遵循地区会计标准的结构化 JSON 有效负载来组织数据。主要资源包括：

所有来自 Openclaw Skills 集成的响应都包含标准的分页元数据：count、next、previous 和 results。

name: wafeq-api
description: Complete Wafeq accounting & e-invoicing API reference for the Middle East (UAE, Saudi Arabia). Use when building integrations with Wafeq, creating/managing invoices (standard, simplified, bulk), contacts, accounts, bills, expenses, credit/debit notes, payments, payslips, quotes, items, files, manual journals, reports (P&L, balance sheet, cash flow, trial balance), branches, cost centers, employees, projects, warehouses, or any task involving the Wafeq REST API.
metadata: {"openclaw":{"emoji":"??","homepage":"https://wafeq.com","primaryEnv":"WAFEQ_API_KEY","requires":{"env":["WAFEQ_API_KEY"]}}}

Wafeq API Skill

Complete API reference for the Wafeq accounting and e-invoicing platform.

Setup

To use this skill, you need a Wafeq API key:

1. Log in to Wafeq
2. Go to Settings → API Keys (direct link)
3. Create a new API key
4. Set the environment variable:

   export WAFEQ_API_KEY='your-key-here'
   

   Or configure in ~/.openclaw/openclaw.json:

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

?? Security: Never hardcode your API key in code, prompts, or skill files. Always use the WAFEQ_API_KEY environment variable or configure it via skills.entries.wafeq-api.apiKey in ~/.openclaw/openclaw.json.

You can validate your setup by running scripts/setup.sh from the plugin root.

Quick Reference

• Base URL: https://api.wafeq.com/v1/
• Auth (API Key): Authorization: Api-Key $WAFEQ_API_KEY — get keys at https://app.wafeq.com/c/api-keys
• Auth (OAuth2): Authorization: Bearer — contact Wafeq for client credentials
• Idempotency: X-Wafeq-Idempotency-Key: on POST/PUT/PATCH/DELETE (1hr cache, replayed response includes X-Wafeq-Idempotent-Replayed: true)
• Pagination: ?page=1&page_size=25 — response: { count, next, previous, results[] }
• Content-Type: application/json
• Currency codes: ISO 4217 (full list in references/enums.md)
• Entity IDs: Prefixed strings (e.g. cnt_..., acc_..., inv_...)

Standard CRUD Pattern

Most resources follow: POST /{resource}/, GET /{resource}/, GET /{resource}/{id}/, PUT /{resource}/{id}/, PATCH /{resource}/{id}/, DELETE /{resource}/{id}/. Some also have GET /{resource}/{id}/download/ for PDF.

Line items are nested: /{resource}/{parent_id}/line-items/ with the same CRUD pattern.

Reference Files

Common Workflows

Create and Send an Invoice

1. Create contact: POST /contacts/
2. Get revenue account: GET /accounts/?classification=REVENUE
3. Get tax rates: GET /tax-rates/
4. Create invoice: POST /invoices/ (with line_items, contact, currency, invoice_date, invoice_due_date, invoice_number)
5. Report to tax authority: POST /invoices/{id}/tax-authority/report/
6. Download PDF: GET /invoices/{id}/download/

Bulk Send Invoices (E-Commerce / High Volume)

1. POST /api-invoices/bulk_send/ with array of invoice objects including channels for email delivery
2. Response: { "queued": N }
3. Generate summary: GET /api-invoices/summary/

Record Expense

1. Get expense account: GET /accounts/?classification=EXPENSE
2. Create expense: POST /expenses/ with paid_through_account, contact, date, currency, tax_amount_type, line_items

Record Payment Against Invoice

1. POST /payments/ with invoice_payments array linking to invoice IDs and amounts

Generate Financial Reports

• Balance Sheet: GET /reports/balance-sheet/?currency=SAR&date=2025-12-31
• Profit & Loss: GET /reports/profit-and-loss/?currency=SAR&date_after=2025-01-01&date_before=2025-12-31
• Cash Flow: GET /reports/cash-flow/?currency=SAR&date_after=2025-01-01&date_before=2025-12-31
• Trial Balance: GET /reports/trial-balance/?from_date=2025-01-01&to_date=2025-12-31

Quote to Invoice Conversion

1. Create quote: POST /quotes/
2. Convert to invoice: POST /quotes/{id}/invoice/

Important Notes

• Tax authority reporting is available for invoices, simplified invoices, and credit notes via POST /{resource}/{id}/tax-authority/report/
• Simplified invoices are for B2C transactions (no buyer tax registration required)
• Standard invoices are for B2B transactions
• Place of supply field is UAE-specific (emirate codes or OUTSIDE_UAE)
• Use reference fields as unique identifiers to prevent duplicate creation