Billingo-Integration
Billingo ist eine ungarische Online-Rechnungsplattform, die mit NAV Online Számla 3.0 konform ist. Wenn sie in CADENSA konfiguriert ist, können Sie direkt aus Ihren erfassten Zeiteinträgen rechtsgültige ungarische Steuerrechnungen ausstellen — mit automatischer NAV-Meldung und Kontaktsynchronisation aus Ihrem Billingo-Adressbuch.
Voraussetzungen
- Aktives Billingo-Konto (mit API-Zugang)
- Billingo v3 API-Schlüssel (siehe unten)
- Mindestens ein konfigurierter Rechnungsblock (számlablokk) in Billingo
- CADENSA-Einheit mit mindestens Admin-Rolle
Schritt 1 — Billingo-API-Schlüssel generieren
- Anmelden bei app.billingo.hu
- Im linken Menü auf Beállítások (Einstellungen) klicken
- Auf API im Einstellungsmenü klicken
- Auf + Új API kulcs létrehozása (Neuen API-Schlüssel erstellen) klicken
- Namen vergeben (z.B.
CADENSA) - Den generierten Schlüssel sofort kopieren — er wird nur einmal angezeigt
Teilen Sie Ihren API-Schlüssel niemals und committen Sie ihn nicht in die Versionsverwaltung. Jeder mit dem Schlüssel kann Rechnungen in Ihrem Namen erstellen.
Schritt 2 — In CADENSA konfigurieren
- Einstellungen → Rechnung in CADENSA öffnen
- Billingo 🇭🇺 als Anbieter auswählen
- Ein Infofeld erscheint:
Ihren Billingo-API-Schlüssel finden Sie unter: app.billingo.hu → Beállítások → API → API kulcs létrehozása
- API-Schlüssel in das API Key-Feld einfügen
- Auf Verbindung testen klicken — ein grünes
bestätigt Gültigkeit - Auf Speichern klicken
Die Speichern-Schaltfläche bleibt deaktiviert, bis der Verbindungstest erfolgreich war.
Schritt 3 — Standardwerte festlegen
| Einstellung | Empfohlener Wert (HU) | Beschreibung |
|---|---|---|
| Standardwährung | HUF | Währung für neue Rechnungen |
| Standard-MwSt. % | 27 | Ungarischer Regelsteuersatz (ÁFA) |
| Zahlungsfrist (Tage) | 8 oder 30 | Tage bis zum Fälligkeitsdatum |
| Standard-Dokumenttyp | Rechnung | Vorauswahl im Rechnungsdialog |
| Ausstellerland | HU | ISO 3166-1 alpha-2 Ländercode Ihres Unternehmens |
Das Feld Ausstellerland aktiviert intelligente MwSt.-Vorschläge (Reverse-Charge, Exporterkennung) im Rechnungsdialog. Ohne dieses Feld verwendet CADENSA den inländischen MwSt.-Satz des Käufers. Siehe Rechnungsgenerierung — MwSt.-Vorschlag für Details.
Schritt 4 — Billingo-spezifische Einstellungen
| Einstellung | Beschreibung |
|---|---|
| Rechnungsblock-ID | Der zu verwendende Billingo-Rechnungsblock. CADENSA wählt automatisch den ersten aktiven Block. Für einen bestimmten Block: ID aus Billingo → Beállítások → Bizonylattömbök eingeben. |
| Bankkonto-ID | Optional. Ihre Billingo-Bankkonto-ID — erscheint auf der Rechnung als Zahlungsdetail. |
| Zahlungsmethode | Standard-Zahlungsmethode (wire_transfer, cash, bankcard usw.). |
| Rechnungssprache | Sprache der ausgestellten Rechnung (hu, en, de usw.). |
Schritt 5 — (Optional) Sandbox / Testmodus
Aktivieren Sie den Sandbox-Modus zum Testen ohne echte NAV-gemeldete Rechnungen auszustellen. Sandbox-Rechnungen:
- Erscheinen nicht in der offiziellen Billingo-Rechnungsliste
- Werden nicht an NAV gemeldet
- Werden nach dem Test verworfen
Umschalter: Einstellungen → Rechnung → Sandbox / Testmodus
Rechnung über Billingo ausstellen
- Berichte öffnen → Datumsbereich und Projektfilter einstellen
- Auf Rechnung generieren klicken
- Im Feld Dokumenttyp Rechnung auswählen — der Ausgabekanal zeigt
Billingo - (Optional) Über den Partner-Picker einen Kunden aus dem Billingo-Adressbuch auswählen
- Kundendaten, MwSt.-Satz und Fälligkeitsdatum ausfüllen
- Auf Vorschau klicken → Positionen und Gesamtbeträge prüfen
- Auf Rechnung ausstellen (Billingo) klicken
- Eine neue Rechnung wird erstellt und sofort abgeschlossen (wodurch die Billingo-Rechnungsnummer vergeben wird)
- Die Rechnung wird automatisch an NAV Online Számla 3.0 gemeldet
- Die Rechnung erscheint in Billingo unter Számlák → Kimenő számlák
Partner-Picker
Wenn Billingo konfiguriert ist, zeigt der Rechnungsdialog einen Partner-Picker — ein durchsuchbares Dropdown Ihrer Billingo-Kontakte.
Bei Auswahl eines Kontakts werden automatisch ausgefüllt:
- Firmenname
- Adresse (Straße, PLZ, Stadt, Land)
- Steuernummer
- E-Mail-Adresse
Wenn der Kunde nicht in Ihrem Billingo-Adressbuch existiert, erstellt CADENSA ihn automatisch. Kontakte werden über den Billingo-Endpunkt /partners abgerufen (bis zu 100 Partner).
CADENSA gleicht Partner ohne Berücksichtigung der Groß-/Kleinschreibung anhand des Namens ab. Existiert bereits ein Partner mit demselben Namen, wird der bestehende Datensatz mit neu angegebenen Adressdetails aktualisiert.
MwSt.-Sätze
| Satz | Verwendung |
|---|---|
| 27% | Ungarischer Regelsteuersatz (ÁFA) |
| 5% | Ermäßigter Satz (bestimmte Lebensmittel, Medikamente) |
| 0% | Steuerfrei, innergemeinschaftliche Lieferung, Export |
| AAM | Allgemeine Steuerbefreiung |
| TAM | Sachliche Steuerbefreiung |
| EU | Innergemeinschaftliche Warenlieferung |
| EUK | Innergemeinschaftliche Lieferung (Sonderfall EU) |
| MAA | Landwirtschaftliche Pauschalausgleichszahlung |
| F.AFA | Reverse-Charge-Verfahren |
| K.AFA | Kassenbuchhaltungs-MwSt. |
| KBAUK | Export außerhalb der EU |
Geben Sie einen MwSt.-Satz ein, der nicht in der obigen Liste steht, verwendet CADENSA standardmäßig 27%. Nutzen Sie die numerischen Sätze (0, 5, 27) für Standardfälle und die String-Codes für steuerliche Sonderfälle.
Rechnungen in Fremdwährung
Billingo arbeitet nativ in HUF. Bei Rechnungen in anderen Währungen (EUR, USD, GBP usw.):
- CADENSA ruft automatisch den aktuellen HUF-Wechselkurs von der Frankfurter API ab (EZB-Daten)
- Der Wechselkurs (
conversion_rate) wird wie von Billingo gefordert in die Rechnungsanfrage aufgenommen - Der Kurs wird im CADENSA-Rechnungsdatensatz für Prüfzwecke gespeichert
Ist die Wechselkurs-API nicht erreichbar, verwendet CADENSA ungefähre Fallback-Kurse (EUR ~400 HUF, USD ~370 HUF). Stellen Sie für den produktiven Einsatz sicher, dass eine ausgehende Verbindung zu api.frankfurter.app möglich ist.
Belegweiterleitung
| Dokumenttyp | Ausgabe |
|---|---|
| Proforma | Interne PDF (nie an Billingo gesendet) |
| Arbeitszusammenfassung | Interne PDF (nie an Billingo gesendet) |
| Rechnung | An Billingo-API gesendet → PDF zurückgegeben |
Nur Dokumente vom Typ „Rechnung" werden an Billingo gesendet. Proforma und Arbeitszusammenfassung werden unabhängig von der Anbieter-Einstellung immer intern erzeugt.
Rechnungsstorno
So stornieren Sie eine Billingo-Rechnung aus CADENSA:
- Abrechnung → Rechnungsverlauf öffnen
- Rechnung suchen und auf Rechnung stornieren klicken
- Stornierung bestätigen
CADENSA ruft POST /documents/{id}/cancel auf. In Billingo wird automatisch eine Stornorechnung erstellt und an NAV gemeldet.
Stornierte Rechnungen können nicht wiederhergestellt werden. Für eine erneute Rechnungsstellung erstellen Sie eine neue Rechnung über die Berichte-Seite.
Rechnungsverlauf & PDF-Download
Nach erfolgreicher Rechnungserstellung:
- Die Rechnung erscheint unter Abrechnung → Rechnungsverlauf in CADENSA
- Die Rechnung erscheint auch in Ihrem Billingo-Konto unter Számlák → Kimenő számlák
- Sie können die PDF jederzeit von beiden Stellen erneut herunterladen
Verbindung testen
Nutzen Sie die Schaltfläche Verbindung testen nach Eingabe des API-Schlüssels. CADENSA ruft den Billingo-Endpunkt /utils/time auf, um Folgendes zu prüfen:
- Der API-Schlüssel ist gültig und aktiv
- Der Schlüssel besitzt die erforderlichen Berechtigungen
Ein erfolgreicher Test zeigt:
✓ Verbindung erfolgreich
Fehlerbehebung
„Ungültiger API-Schlüssel" / 401 Unauthorized
Der API-Schlüssel ist ungültig, abgelaufen oder widerrufen.
Lösung: Neuen Schlüssel in Billingo generieren (Beállítások → API → + Új API kulcs) und in CADENSA neu eingeben.
„Keine Rechnungsblöcke gefunden"
Kein Rechnungsblock in Billingo konfiguriert.
Lösung: In Billingo unter Beállítások → Bizonylattömbök mindestens einen aktiven Rechnungsblock erstellen.
„INVOICE_NO_BILLABLE_ITEMS"-Fehler
Alle Positionen haben amount = 0 — es sind keine Stundensätze konfiguriert.
Lösung: Einstellungen → Tarife öffnen und Stundensätze für Projekte konfigurieren.
„Partner nicht gefunden"-Fehler
Die automatische Partner-Erstellung ist fehlgeschlagen — meist wegen eines fehlenden Pflichtfelds (Postleitzahl, Stadt oder Adresse).
Lösung: Stellen Sie sicher, dass der Kundendatensatz in CADENSA mindestens einen Ländercode und eine Stadt enthält. Alternativ den Partner zunächst manuell in Billingo anlegen und über den Partner-Picker auswählen.
PDF ohne Rechnungsnummer
Der Billingo-API-Aufruf war erfolgreich, aber die aus CADENSA heruntergeladene PDF enthält keine externe Rechnungsnummer.
Lösung: Die PDF erneut unter Abrechnung → Rechnungsverlauf herunterladen — der gespeicherte Datensatz enthält die korrekte Rechnungsnummer von Billingo.
Rate-Limit überschritten (429 Too Many Requests)
Billingo erlaubt 120 Anfragen pro Minute. Werden viele Rechnungen in schneller Folge erzeugt, kann dieses Limit überschritten werden.
Lösung: 60 Sekunden warten und erneut versuchen. Bei Massenrechnungsstellung die Anfragen zeitlich staffeln.
Fremdwährungsrechnung: „conversion_rate required"
Billingo verlangt für alle Nicht-HUF-Währungen einen HUF-Umrechnungskurs.
Lösung: Dies wird von CADENSA automatisch gehandhabt (über die Frankfurter API). Erscheint dieser Fehler dennoch, prüfen Sie die Netzwerkverbindung zu api.frankfurter.app. Ist die API blockiert, verwendet CADENSA fest hinterlegte Fallback-Kurse.
Billingo vs. Lexoffice
| Funktion | Billingo 🇭🇺 | Lexoffice 🇩🇪 |
|---|---|---|
| Markt | Ungarn | DE / AT / CH |
| Rechtlicher Standard | NAV Online Számla 3.0 | ZUGFeRD / E-Rechnung |
| Authentifizierung | API-Schlüssel (v3) | Bearer-Token (API-Schlüssel) |
| Sandbox-Modus | Verfügbar |  Nicht verfügbar |
| Partner-Picker | /partners-Endpunkt | /contacts-Endpunkt |
| PDF-Erstellung | Synchron | Asynchron (Polling bis 30s) |
| Rechnungsabschluss | Automatisch | Explizit (?finalize=true) |
| Fremdwährung | Automatischer Umrechnungskurs (MNB via Frankfurter) | Nativ unterstützt |
Verwandte Seiten
- Rechnungsanbieter-Einstellungen — alle Anbieter vergleichen, API-Schlüssel und Standardwerte konfigurieren
- Rechnungsgenerierung — Rechnungen aus Zeiteinträgen generieren
- Abonnementpläne — welcher CADENSA-Plan erforderlich ist