holded-skill

Operate Holded ERP through holdedcli to read and update data safely. Use when the user asks to read, search, create, update, or delete Holded entities (conta...

Use holdedcli to read and modify Holded data with a safe, repeatable workflow.

Operational Flow

1. Confirm technical prerequisites.
2. Discover available actions with holded actions list.
3. Inspect the selected action with holded actions describe <action> --json.
4. Classify the action as read or write.
5. If it is a write operation, ask for explicit confirmation before execution.
6. Run with --json and summarize IDs, HTTP status, and applied changes.

Prerequisites

• Verify that the binary exists: holded help
• Verify credentials: holded auth status or HOLDED_API_KEY
• Prefer structured output whenever possible: --json

Safety Rules

• ALWAYS check deductibility rules BEFORE creating any document. See "Accounting Rules for Spain" section below.
• Treat any POST, PUT, PATCH, or DELETE action as write.
• Treat any GET action (or HEAD when present) as read.
• Before any operation, always run holded actions describe <action> --json (after holded actions list) to validate accepted parameters.
• For purchase receipts, always enforce docType=purchase and include "isReceipt": true in the JSON body. Since holdedcli validates against Holded's schema (which doesn't include isReceipt), you must use --skip-validation flag.
• Ask for explicit user confirmation every time before any write action.
• Do not execute writes on ambiguous replies (ok, go ahead, continue) without clarification.
• Repeat the exact command before confirmation to avoid unintended changes.
• If the user does not confirm, stop and offer payload adjustments.

Mandatory Confirmation Protocol

Before any write action, show:

1. Holded action (action_id or operation_id).
2. Method and endpoint.
3. --path, --query, and body parameters (--body or --body-file).
4. The exact command to run.

Use this format:

text

This operation will modify data in Holded.
Action: <action_id> (<METHOD> <endpoint>)
Changes: <short summary>
Command: holded actions run ... --json
Do you confirm that I should run exactly this command? (reply with "yes" or "confirm")

Execute only after an explicit affirmative response.

Execution Pattern

Read Operations

1. Locate the action with holded actions list --json (use --filter).
2. Verify accepted path/query/body parameters with holded actions describe <action> --json.
3. Run holded actions run <action> ... --json.
4. Return a clear summary and relevant IDs for follow-up steps.

Write Operations

1. Locate and validate the action.
2. Run holded actions describe <action> --json to verify required/optional parameters.
3. Prepare the final payload.
4. If creating a purchase receipt/ticket, verify docType=purchase and "isReceipt": true, and use --skip-validation flag.
5. Request mandatory confirmation.
6. Run the command after confirmation.
7. Report result (status_code, affected ID, API response).

Base Commands

bash

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=<id> --json

For long payloads, prefer --body-file:

bash

holded actions run invoice.update-contact \
  --path contactId=<id> \
  --body-file payload.json \
  --json

Purchase receipt rule (mandatory for purchase tickets):

bash

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

Important notes:

• Use --skip-validation flag because holdedcli validates against Holded's schema which doesn't include isReceipt.
• Use subtotal in items (not price) - this is the field name Holded's API expects.
• Timestamps must be in seconds (Unix epoch) and in Europe/Madrid timezone.

Timestamp calculation (Python):

python

from datetime import datetime, timezone, timedelta
# For 11/02/2026 00:00 in Madrid:
dt = datetime(2026, 2, 11, 0, 0, 0, tzinfo=timezone(timedelta(hours=1)))
print(int(dt.timestamp()))  # 1770764400

Accounting Rules for Spain

⚠️ ALWAYS check these rules BEFORE creating any expense document:

Expense Type	IVA Deductible	Expense Deductible	Account
Restaurants/Meals	❌ No	✅ Yes (with justification)	629
Displacement	❌ No	✅ Yes	629
Fuel	⚠️ Mixed	✅ Yes	625/622
Office supplies	✅ Yes	✅ Yes	600/602
Insurance	⚠️ Mixed	✅ Yes	625

Before creating any document, ALWAYS verify:

1. Is the expense tax deductible?
2. Is the IVA deductible? (usually NO for restaurants, displacement)
3. If in doubt, ASK before creating the document.

Common mistake to avoid: Never set tax: 10 or tax: 21 for restaurant expenses - IVA is NOT deductible for meals unless it's a business event with proper justification.

Error Handling

• If MISSING_API_KEY appears, configure API key through --api-key, HOLDED_API_KEY, or holded auth set.
• If ACTION_NOT_FOUND appears, list the catalog and search with --filter.
• If INVALID_BODY appears, validate JSON before execution.
• If API_ERROR appears, report status_code and the API snippet.

References

• Read {baseDir}/references/holdedcli-reference.md for quick commands and criteria.
• Use dynamic action discovery and parameter inspection via:
  • holded actions list --json
  • holded actions describe <action> --json