Skip to main content

Holded Integration

Holded is an all-in-one business management platform designed for the Spanish market (ES), also supporting Portugal, Italy, France, and Germany. When configured in CADENSA, you can issue legally valid invoices directly from your tracked time entries, compatible with the FacturaE Spanish e-invoicing standard.

Supported countries

Holded is primarily designed for businesses in Spain 🇪🇸, with additional support for Portugal 🇵🇹, Italy 🇮🇹, France 🇫🇷, and Germany 🇩🇪.

Registro Horario compliance

Spain mandates time tracking records since 2019 (Real Decreto-ley 8/2019). Cadensa's time tracking combined with Holded invoicing provides a complete time log → invoice workflow for Spanish businesses.

Before You Begin​

You need:

  • An active Holded account (any paid plan)
  • A Holded API key (see below)
  • CADENSA unit with at least Admin role

Step 1 — Get Your Holded API Key​

  1. Log in to app.holded.com
  2. Go to Settings (gear icon, top right)
  3. Navigate to Integrations → API
  4. Click "+ New API Key" (or copy an existing key)
  5. Copy the generated key
Keep your API key secret

Never share your API key or commit it to version control. Anyone with the key can create and manage invoices and contacts on your behalf.

For the official Holded API docs, see: developers.holded.com/reference

Step 2 — Configure in CADENSA​

  1. Open Settings → Invoice in CADENSA
  2. Select Holded 🇪🇸 as the provider
  3. Paste your API key into the API Key field
  4. Click Test Connection — a green confirms the key is valid
  5. Click Save

Step 3 — Set Defaults​

Configure defaults so the Generate Invoice dialog is pre-filled with sensible values:

SettingRecommended value (ES)Description
Default CurrencyEURCurrency used on new invoices
Default VAT %21Standard Spanish IVA (impuesto sobre el valor añadido)
Payment Terms Days30Days until due date
Default Document TypeInvoicePre-selects "Invoice" in the dialog
Issuer CountryESYour company's country — enables automatic VAT suggestion
Spanish IVA rates
  • 21% — Standard rate (tipo general) — most services
  • 10% — Reduced rate (tipo reducido) — hospitality, transport, some food
  • 4% — Super-reduced rate (tipo superreducido) — books, medicine, some food
  • 0% — Exempt — intra-EU supply, export, certain financial services

Issuing an Invoice via Holded​

Once configured, follow the standard invoice generation flow:

  1. Open Reports → apply date range and project filters
  2. Click Generate Invoice
  3. In the Document Type field, select Invoice — the output channel shows Holded
  4. Fill in client details (name, address, country, VAT/NIF number)
  5. Set the VAT rate (default: 21%)
  6. Click Preview Invoice → review line items and totals
  7. Click Issue Invoice (Holded)

CADENSA sends the invoice to the Holded API. A contact record is automatically found or created (searched by VAT number first, then by name). The invoice is created and the PDF is available for download.

What happens in Holded
  • A new invoice document is created in Holded under Facturación → Facturas emitidas
  • A contact is automatically created if not found
  • The invoice PDF is available for immediate download

Contact Matching​

CADENSA searches for an existing Holded contact in this order:

  1. By VAT/NIF number — most reliable match (enter the client's VAT number in the invoice dialog)
  2. By company name — exact match (case-insensitive)
  3. Create new — if no match found, a new contact is created automatically
Avoid duplicate contacts

For Spanish clients, always enter the NIF/CIF (e.g. B12345678) in the client VAT number field. This ensures the correct Holded contact is matched even if the company name varies slightly.

Saved Partners (Partner Picker)​

When Holded is configured as your invoice provider, the Generate Invoice dialog shows a partner picker — a searchable dropdown populated directly from your Holded contacts.

How it works:

  • Type a name or partial text to search your Holded contacts in real time
  • Selecting a partner auto-fills all client fields: company name, address, postal code, city, country, VAT number
  • The country field shows the original Holded country name (e.g. "Spain", "Hungary") for easy recognition — while the underlying ISO code (e.g. ES, HU) is used for VAT calculation and reverse charge logic
Country display vs. VAT calculation

Holded stores country names in full text form ("Spain", "Germany", etc.). CADENSA automatically converts these to ISO 3166-1 alpha-2 codes internally for correct VAT suggestion (domestic / reverse charge / export). The full name is displayed in the UI for readability.

Supported workflows:

  • Select an existing partner → all fields filled automatically
  • Clear the partner → edit fields manually
  • Enter client details manually if the partner is not in Holded yet (a new contact will be created on invoice issue)

VAT Rate Mapping​

Holded uses named tax objects. CADENSA maps your numeric tax rate automatically:

Tax RateHolded Tax NameUse case
21%IVA 21%Standard Spanish IVA
10%IVA 10%Reduced rate
4%IVA 4%Super-reduced rate
0%ExentoExempt / export

Invoice Languages​

CADENSA automatically selects the invoice language based on the issuer country:

Issuer CountryInvoice Language
ESSpanish (es)
FRFrench (fr)
DEGerman (de)
PTPortuguese (pt)
ITItalian (it)
OtherSpanish (es, default)

Document Routing​

Document TypeOutput
ProformaInternal PDF (never sent to Holded)
Work SummaryInternal PDF (never sent to Holded)
InvoiceSent to Holded API → PDF returned

Only Invoice type documents are sent to Holded. Proforma and Work Summary are always generated internally, regardless of provider setting.

Invoice History & PDF Download​

After a successful invoice creation:

  • The invoice appears in Reports → Invoices in CADENSA
  • The invoice also appears in your Holded account under Facturación → Facturas emitidas
  • You can re-download the PDF at any time from either place

Testing the Connection​

Use the Test Connection button after entering your API key. CADENSA calls the Holded Contacts API to verify the key is valid.

A successful test shows:

✓ Connection successful
Testing without real invoices

Holded has no sandbox environment. For testing:

  1. Create a test contact in Holded (e.g. "Test Client ES")
  2. Generate a small test invoice in CADENSA
  3. Void/cancel it immediately in Holded (Facturas emitidas → ⋯ → Anular)

Troubleshooting​

"401 Unauthorized" / "403 Forbidden" error​

The API key is invalid, expired, or lacks the required permissions.

Fix: Generate a new API key in Holded (Settings → Integrations → API) and re-enter it in CADENSA.

"INVOICE_NO_ENTRIES" error​

No time entries were found for the selected date range and project filters.

Fix: Adjust the date range or project filter and try again.

Contact not created / wrong contact matched​

If the VAT number is missing and the company name doesn't exactly match an existing Holded contact, a duplicate may be created.

Fix: Check Contactos in Holded and merge duplicate records. For future invoices, always enter the client's NIF/CIF in the VAT number field.

PDF download fails​

Holded generates PDFs synchronously — the PDF should be available immediately after invoice creation.

Fix: Re-download from Reports → Invoices. If the issue persists, check Holded's status page or contact Holded support.

Invoice voiding fails​

Only invoices in pending or draft status can be voided. Paid invoices cannot be reversed via the API.

Fix: Void the invoice manually in Holded (Facturas emitidas → ⋯ → Anular) if the API call fails.

See Also​