holded-skill

使用 holdedcli 以安全、可重复的工作流读取和修改 Holded 数据。

操作流程

1. 确认技术前提条件。
2. 使用 holded actions list 发现可用操作。
3. 使用 holded actions describe --json 检查所选操作的详细信息。
4. 将该操作归类为读操作或写操作。
5. 若为写操作，执行前须请求用户明确确认。
6. 运行时始终附加 --json 参数，并汇总返回的 ID、HTTP 状态码及已应用的变更。

前提条件

• 验证二进制文件是否存在：holded help
• 验证凭据有效性：holded auth status 或环境变量 HOLDED_API_KEY
• 尽可能使用结构化输出（推荐始终添加 --json）

安全规则

• 在创建任何单据前，务必核查抵扣规则。详见下方“西班牙会计规则”章节。
• 所有 POST、PUT、PATCH 或 DELETE 操作均视为写操作。
• 所有 GET 操作（如存在，也包括 HEAD）均视为读操作。
• 每次操作前，必须先运行 holded actions list，再执行 holded actions describe --json，以验证该操作支持的路径、查询参数与请求体参数。
• 对于采购收据（purchase receipt），必须强制设置 docType=purchase，并在 JSON 请求体中包含 "isReceipt": true。由于 holdedcli 基于 Holded 官方 API Schema 进行校验（该 Schema 不含 isReceipt 字段），因此必须使用 --skip-validation 标志。
• 每次执行写操作前，都必须向用户请求明确确认。
• 不得在收到模糊答复（如 ok、go ahead、continue）时直接执行写操作，须先澄清意图。
• 确认前需完整复述待执行命令，以防误操作。
• 若用户未确认，应立即中止并提供调整请求载荷（payload）的选项。

强制确认协议

执行任何写操作前，需展示以下信息：

1. Holded 操作标识符（action_id 或 operation_id）。
2. HTTP 方法与端点（endpoint）。
3. --path、--query 及请求体参数（--body 或 --body-file）。
4. 将要执行的确切命令。

格式如下：

此操作将在 Holded 中修改数据。
Action:  ( )
Changes: <简要变更摘要>
Command: holded actions run ... --json
您是否确认我应精确执行此命令？（请回复“yes”或“confirm”）

仅在收到明确肯定回复后方可执行。

执行模式

读操作

1. 使用 holded actions list --json（可配合 --filter）定位目标操作。
2. 使用 holded actions describe --json 验证其支持的路径/查询/请求体参数。
3. 执行 holded actions run ... --json。
4. 返回清晰的摘要信息及关键 ID，便于后续步骤引用。

写操作

1. 定位并验证目标操作。
2. 运行 holded actions describe --json 确认必填/可选参数。
3. 准备最终请求载荷（payload）。
4. 若创建采购收据/票据（purchase receipt/ticket），须确保 docType=purchase 且请求体中包含 "isReceipt": true，并启用 --skip-validation 标志。
5. 发起强制确认流程。
6. 获得确认后执行命令。
7. 报告执行结果（status_code、影响的 ID、API 响应正文）。

基础命令

holded auth set --api-key "$HOLDED_API_KEY"
holded auth status
holded ping --json
holded actions list --json
holded actions list --filter contacts --json
holded actions describe invoice.get-contact --json
holded actions run invoice.get-contact --path contactId= --json

对于较长的请求体，推荐使用 --body-file：

holded actions run invoice.update-contact 
  --path contactId= 
  --body-file payload.json 
  --json

采购收据规则（采购票据必需）：

holded actions describe invoice.create-document --json
holded actions run invoice.create-document 
  --path docType=purchase 
  --body '{"isReceipt": true, "date": 1770764400, "contactId": "", "items": [{"name": "Description", "units": 1, "subtotal": 29.4, "tax": 0}]}' 
  --skip-validation 
  --json

重要说明：

• 必须使用 --skip-validation 标志，因为 holdedcli 默认依据 Holded 官方 API Schema 进行校验，而该 Schema 未定义 isReceipt 字段。
• 商品项（items）中应使用 subtotal 字段（而非 price），这是 Holded API 实际期望的字段名。
• 时间戳必须为秒级 Unix 时间戳（epoch seconds），且时区为 Europe/Madrid。

时间戳计算示例（Python）：

from datetime import datetime, timezone, timedelta
# 计算 2026 年 2 月 11 日 00:00（马德里时间）对应的时间戳：
dt = datetime(2026, 2, 11, 0, 0, 0, tzinfo=timezone(timedelta(hours=1)))
print(int(dt.timestamp()))  # 1770764400

西班牙会计规则

⚠️ 创建任何费用单据前，务必核查以下规则：

创建单据前，务必核实：

1. 该费用是否属于税前可抵扣项目？
2. 该费用对应的 IVA 是否可抵扣？（餐饮、差旅交通通常不可抵扣）
3. 如有疑问，务必先咨询确认，再创建单据。

需避免的常见错误：餐饮类费用切勿设置 tax: 10 或 tax: 21 —— 除非是具备充分佐证的商务活动，否则餐费 IVA 不可抵扣。

错误处理

• 若出现 MISSING_API_KEY 错误，请通过 --api-key 参数、HOLDED_API_KEY 环境变量或 holded auth set 命令配置 API 密钥。
• 若出现 ACTION_NOT_FOUND 错误，请先运行 holded actions list --json 列出全部操作，并使用 --filter 过滤查找。
• 若出现 INVALID_BODY 错误，请在执行前校验 JSON 格式有效性。
• 若出现 API_ERROR 错误，请记录 status_code 及相关 API 响应片段并上报。

参考文档

• 查阅 {baseDir}/references/holdedcli-reference.md 获取常用命令与筛选准则。
• 通过以下命令实现动态操作发现与参数检查：
  • holded actions list --json
  • holded actions describe --json