Skip to main content

Billingo Integration

Billingo is a Hungarian online invoicing platform compliant with NAV Online Számla 3.0. When configured in CADENSA, you can issue legally valid Hungarian tax invoices directly from your tracked time entries — with automatic NAV reporting and partner sync from your Billingo address book.

Supported countries

Billingo is designed for businesses registered in Hungary 🇭🇺. For other markets, see Lexoffice (DE/AT/CH), Pennylane (FR/BE), Holded (ES/PT), or SmartBill (RO).

Before You Begin​

You need:

  • An active Billingo account (any paid plan with API access)
  • A Billingo v3 API key (see below)
  • At least one configured invoice block (számlablokk) in Billingo
  • CADENSA unit with at least Admin role

Step 1 — Get Your Billingo API Key​

  1. Log in to app.billingo.hu
  2. In the left menu, go to Beállítások (Settings)
  3. Click API in the settings menu
  4. Click + Új API kulcs létrehozása (Create new API key)
  5. Give it a name (e.g. CADENSA)
  6. Copy the generated key immediately — it is only shown once
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 on your behalf.

Step 2 — Configure in CADENSA​

  1. Open Settings → Invoice in CADENSA
  2. Select Billingo 🇭🇺 as the provider
  3. An info box will appear:

    Find your Billingo API key at: app.billingo.hu → Beállítások → API → API kulcs létrehozása

  4. Paste your API key into the API Key field
  5. Click Test Connection — a green confirms the key is valid
  6. Click Save
Test required before saving

The Save button stays disabled until you successfully test the API key. A failed or untested key cannot be saved.

Step 3 — Set Defaults​

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

SettingRecommended value (HU)Description
Default CurrencyHUFCurrency used on new invoices
Default VAT %27Standard Hungarian VAT rate (ÁFA)
Payment Terms Days8 or 30Days until due date
Default Document TypeInvoicePre-selects "Invoice" in the dialog
Issuer CountryHUYour company's ISO 3166-1 alpha-2 country code
Issuer Country matters for VAT

The Issuer Country field enables smart VAT suggestions (reverse charge, export detection) in the Generate Invoice dialog. Without it, CADENSA falls back to the buyer's domestic VAT rate. See Invoice Generation — VAT Suggestion for details.

Step 4 — Configure Billingo-Specific Settings​

SettingDescription
Invoice Block IDThe Billingo invoice block (számlablokk) to use. CADENSA auto-selects the first active block if left blank. To use a specific block, enter the block ID from Billingo → Beállítások → Bizonylattömbök.
Bank Account IDOptional. Your Billingo bank account ID — appears on the invoice for payment details.
Payment MethodDefault payment method on new invoices (wire_transfer, cash, bankcard, etc.).
LanguageInvoice language (hu, en, de, fr, es, etc.).

Step 5 — (Optional) Sandbox / Test Mode​

Enable Sandbox mode in provider settings to test invoice generation without issuing real NAV-reported invoices. Sandbox invoices:

  • Do not appear in your official Billingo invoice list
  • Do not get reported to NAV
  • Are discarded after testing

Toggle: Settings → Invoice → Sandbox / Test mode

Issuing an Invoice via Billingo​

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 Billingo
  4. (Optional) Use the partner picker to select a client from your Billingo address book
  5. Fill in client details, VAT %, and due date
  6. Click Preview Invoice → review line items and totals
  7. Click Issue Invoice (Billingo)

CADENSA sends the invoice to the Billingo API, receives the invoice number, and downloads the PDF.

What happens in Billingo
  • A new invoice is created and immediately finalized (which assigns the Billingo invoice number)
  • The invoice is automatically reported to NAV Online Számla 3.0
  • The finalized invoice appears in your Billingo invoice list under Számlák → Kimenő számlák

Partner Picker​

When Billingo is configured, the Generate Invoice dialog shows a partner picker — a searchable dropdown of your Billingo contacts.

Selecting a contact auto-fills:

  • Company name
  • Street, postal code, city, country
  • Tax number (adószám)
  • Email address

If the client does not exist in your Billingo address book, CADENSA automatically creates them. Contacts are fetched from the Billingo /partners endpoint (up to 100 partners).

Partner matching

CADENSA matches partners case-insensitively by name. If a partner already exists with the same name, the existing record is updated with any new address details provided.

VAT Rates​

Billingo supports the following VAT rates for Hungarian invoices:

RateUse case
27%Standard Hungarian VAT (ÁFA — Általános forgalmi adó)
5%Reduced rate (e.g. certain food products, medicines)
0%VAT-exempt, intra-community supply, export
AAMTax-exempt under § 85 of VAT Act (Általános adómentesség)
TAMTax-exempt supply (Tárgyi adómentesség)
EUIntra-community supply of goods (EU)
EUKIntra-community supply (EU special)
MAAAgricultural flat-rate compensation (Mezőgazdasági átalányadó)
F.AFAReverse charge (Fordított ÁFA)
K.AFACash accounting VAT (Pénzforgalmi áfa)
KBAUKExport outside the EU
Unsupported VAT rates

If you enter a VAT rate not in the list above, CADENSA defaults to 27%. Use the numeric rates (0, 5, 27) for standard cases, and the string codes for special tax treatments.

Non-HUF Invoices​

Billingo natively supports HUF. For invoices in other currencies (EUR, USD, GBP, etc.):

  • CADENSA automatically fetches the current HUF exchange rate from the Frankfurter API (sourced from the European Central Bank)
  • The exchange rate (conversion_rate) is included in the invoice payload as required by Billingo
  • The exchange rate is logged in CADENSA's invoice record for audit purposes
Fallback rates

If the exchange rate API is unavailable, CADENSA uses approximate fallback rates (EUR ~400 HUF, USD ~370 HUF). For production use, ensure outbound connectivity to api.frankfurter.app.

Document Routing​

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

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

Invoice Cancellation (Storno)​

To cancel a Billingo invoice from CADENSA:

  1. Go to Billing → Invoice History
  2. Find the invoice and click Cancel Invoice
  3. Confirm the cancellation

CADENSA calls POST /documents/{id}/cancel on the Billingo API. A storno invoice is automatically created in Billingo and reported to NAV.

Cancellation is irreversible

Cancelled invoices cannot be uncancelled. If you need to re-invoice, generate a new invoice from the Reports page.

Invoice History & PDF Download​

After a successful invoice creation:

  • The invoice appears in Billing → Invoice History in CADENSA
  • The invoice also appears in your Billingo account under Számlák → Kimenő számlák
  • 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 Billingo /utils/time endpoint to verify:

  • The API key is valid and active
  • The key has the required permissions

A successful test shows:

✓ Connection successful

Troubleshooting​

"Invalid API key" / 401 Unauthorized​

The API key is invalid, expired, or has been revoked.

Fix: Generate a new API key in Billingo (Beállítások → API → + Új API kulcs) and re-enter it in CADENSA.

"No document blocks found" error​

Your Billingo account has no configured invoice blocks.

Fix: In Billingo, go to Beállítások → Bizonylattömbök and create at least one invoice block (számlablokk). Make sure its status is active.

"INVOICE_NO_BILLABLE_ITEMS" error​

All line items have amount = 0. This happens when no hourly rates are configured.

Fix: Go to Settings → Rates and configure hourly rates for your projects.

"Partner not found" error​

Auto-creation of the partner failed — usually due to a missing required field (postal code, city, or address).

Fix: Ensure the client record in CADENSA has at least a country code and city. Alternatively, create the partner manually in Billingo first and select it via the partner picker.

PDF has no invoice number​

The Billingo API call succeeded but the PDF downloaded from CADENSA is missing the external invoice number.

Fix: Re-download the PDF from Billing → Invoice History — the stored record has the correct invoice number from Billingo.

Rate limit exceeded (429 Too Many Requests)​

Billingo allows 120 requests per minute. Generating many invoices in quick succession may exceed this.

Fix: Wait 60 seconds and retry. For bulk invoice generation, stagger the requests.

Non-HUF invoice: "conversion_rate required"​

Billingo requires a HUF conversion rate for all non-HUF currencies.

Fix: This is handled automatically by CADENSA (via Frankfurter API). If this error appears, check network connectivity to api.frankfurter.app. If the API is blocked, CADENSA uses hardcoded fallback rates.

Billingo vs. Lexoffice​

FeatureBillingo 🇭🇺Lexoffice 🇩🇪
MarketHungaryDE / AT / CH
Legal standardNAV Online Számla 3.0ZUGFeRD / E-Rechnung
AuthAPI key (v3)Bearer token (API key)
Sandbox mode Available Not available
Partner picker /partners endpoint /contacts endpoint
PDF generationSynchronousAsync (polling up to 30s)
Invoice finalizationAutomaticExplicit (?finalize=true)
Non-domestic currencyAuto conversion rate (MNB via Frankfurter)Supported natively