E-Rechnungen als Serienrechnung

Hallo!
Ich ich nutze Lexware Office und habe viele Behörden als Kunden, die regelmäßig Serienrechnungen erhalten. Nach und nach stellen diese Kunden jetzt auf XRechnung um. Unter Kontakte habe ich am Kunden die Leitweg-ID und Lieferantennummer eingetragen. Wenn ich nun eine einzelne Rechnung für den Kunden erstellen möchte, erscheint auch die blaue Banderole. Aber wenn ich eine Serienrechnung erstellen möchte, erscheint die Banderole nicht und die Serienrechnung geht auch nicht als XRechnung, sondern als pdf raus. Obwohl der Kunde als XRechnungsempfänger angelegt ist. Was übersehe ich?
Aktuell muß ich XRechnungen einzeln erstellen, was bei über 1.000 Rechnungen pro Jahr zu umständlich ist.

Danke schonmal für die Unterstützung.

Wenn hier jemand eine Antwort auf meine Frage hat, freue ich mich über entsprechende Rückmeldung. Grüße

Hi,

zu dem Thema habe ich das hier gefunden:

Hilft Dir das weiter?

Danke, aber das hilft mir leider nicht weiter. Die Voraussetzungen für XRechnungen sind alle erfüllt. Einzelrechnungen kann ich damit rausschicken. Aber sobald ich versuche eine Serienrechnung für den gleichen Kunden zu erstellen, wird das nicht als XRechnung vorgesehen, sondern als herkömmliche Rechnung. Einzelrechnungen funktionieren - Serienrechnungen nicht. Was übersehe ich?

Mir ist das Thema von elementarer Bedeutung. Wenn Lexware Office diese Funktion nicht bietet, muß ich mich leider nach einem anderen Tool umsehen. Daher bin ich um Hilfe dankbar.

In dem Falle kann man via Forum eher wenig tun. Bitte in Lexware Office im eingloggten Zustand oben rechts ? → Support kontaktieren anklicken und das Thema mit dem Support besprechen. Die können im Zweifel den Account prüfen und Details dazu sagen.

Gern ein Feedback hier, wenn es geklärt ist. Danke.

Leider scheint es in Lexware Office einfach nicht möglich zu sein, X-Rechnungen als Serienrechnungen anzulegen. Hier die Antwort vom Support-Bot:

"In Lexware Office wird eine XRechnung nur für eine einzelne Rechnung erstellt, wenn es sich beim Kunden um eine öffentliche Behörde handelt und sowohl die Leitweg-ID als auch Ihre Lieferantennummer gespeichert sind.

Für Serienrechnungen erstellt Lexware Office derzeit keine XRechnung (XML).

Deshalb sehen Sie auch nicht die blaue Banderole und die Serienrechnung wird nur als PDF erstellt.

Das bedeutet für Sie: Erstellen Sie XRechnungen vorerst als einzelne Rechnungen, wenn Sie das XML-Format benötigen."

Das ist mir unbegreiflich, weshalb diese wichtige Funktion nicht berücksichtigt wird.

Ich glaube, die Support-Antwort beschreibt das richtig, und daraus ergibt sich auch der Weg drumherum: Die XRechnung entsteht in Lexware Office nur beim Anlegen einer einzelnen Rechnung an einen Kontakt mit Leitweg-ID und Lieferantennummer. Die Serienrechnung läuft an dieser Stelle einfach vorbei, sie erzeugt ihre Rechnungen im nächtlichen Lauf als normale PDF, egal wie der Kunde angelegt ist. Es fehlt also nicht an deinen Einstellungen, sondern die Serienfunktion nutzt den E-Rechnungs-Generator schlicht nicht.

Was aber geht, ohne das Tool zu wechseln: die öffentliche Lexware-Office-API (developers.lexware.io). Die kann zwei Dinge, die zusammen dein Problem lösen. Erstens liest sie deine Serienvorlagen aus (recurring-templates, nur lesend, mit Kontakt, Positionen, Steuerbedingungen). Zweitens legt sie einzelne Rechnungen an, und wenn du dabei die contactId des Behördenkunden mitgibst, übernimmt Lexware die Leitweg-ID aus dem Kontakt und erzeugt die Rechnung als XRechnung. Die XML holst du dir dann per API ab (Accept: application/xml), das ist laut Doku ausdrücklich vorgesehen. Lexware baut die XML also selbst, du musst nichts nachbauen und nichts validieren.

Der Ablauf wäre dann pro Abrechnungslauf: Skript liest die fälligen Serienvorlagen, legt daraus je eine echte Rechnung an, lädt die XML herunter, fertig zum Einreichen. Bei über 1.000 Rechnungen im Jahr ist das der Unterschied zwischen einmal klicken und tausendmal. Zwei Dinge musst du dabei beachten. Die automatische Ausführung der jeweiligen Serienvorlage solltest du pausieren, sonst hast du nachts zusätzlich die PDF-Rechnung. Und vor dem ersten echten Lauf würde ich mit einer einzelnen Test-Rechnung an einen Behördenkunden prüfen, dass die per API angelegte Rechnung wirklich das Profil XRechnung bekommt (die blaue Banderole bzw. electronicDocumentProfile in der API-Antwort). Die Doku sagt ja, ich habe es aber nicht selbst gegen einen Account laufen lassen, weil ich Lexware Office nicht nutze.

Ich habe mir das genauer angeschaut, weil mir solche Fragen beruflich öfter begegnen (Schnittstellen und Automatisierung), und habe den Ablauf als kleines Python-Skript aufgeschrieben, das die Vorlagen liest, im Trockenlauf zeigt, was es anlegen würde, und im Echtlauf die XML-Dateien in einen Ordner legt. Wenn dir das etwas bringt, sag Bescheid, dann stelle ich es hier ein. Ohne API-Key läuft es natürlich nicht, den holst du dir in Lexware Office unter Erweiterungen.

Ich stelle das Skript unten mal ein, vielleicht hilft es ja jemandem, der später über den Thread stolpert.

Es liest über die API die Serienvorlagen, deren nächster Ausführungstermin erreicht ist, und legt daraus je eine einzelne Rechnung an. Die XRechnung erzeugt dabei Lexware selbst, weil die contactId des Kunden an der Rechnung hängt. Im Echtlauf lädt das Skript die fertigen XML-Dateien anschließend herunter, voreingestellt ist aber ein Trockenlauf, der nur ausgibt, was angelegt würde.

Die Rechnung verlangt shippingConditions, die Serienvorlagen laut Doku nicht haben. Das Skript setzt sie aus dem shippingType und dem Intervall der Vorlage zusammen.

Gegen einen echten Account gelaufen ist es nicht. Eine Testumgebung gibt es bei Lexware nicht, und ich nutze Lexware Office selbst nicht. Geprüft habe ich es gegen die Doku und gegen selbst gebaute Beispieldaten. Ich würde deshalb mit einer einzelnen, vorher pausierten Vorlage anfangen und prüfen, ob die Rechnung wirklich als XRechnung herauskommt.

serien_xrechnung.py (zum Aufklappen)
# /// script
# requires-python = ">=3.11"
# dependencies = ["requests"]
# ///
"""Serienrechnungen als XRechnung, über die öffentliche Lexware-Office-API.

Liest die fälligen Serienvorlagen (nur lesend), legt daraus je eine einzelne Rechnung an und
lädt die XML herunter, die Lexware dafür erzeugt. Die XML baut Lexware, nicht dieses Skript.

  LEXWARE_API_KEY=... uv run serien_xrechnung.py --dry-run
  LEXWARE_API_KEY=... uv run serien_xrechnung.py --live --yes --template <id> --out ./xml

Der API-Key kommt aus Lexware Office unter Erweiterungen, Public API.
Ohne --template nimmt das Skript alle Vorlagen, deren nextExecutionDate erreicht ist.
"""
from __future__ import annotations

import argparse
import calendar
import datetime as dt
import json
import os
import pathlib
import sys
import time
from zoneinfo import ZoneInfo

import requests

BASE = "https://api.lexware.io/v1"
TZ = ZoneInfo("Europe/Berlin")
MIN_INTERVAL = 0.55  # Doku: max. 2 Requests pro Sekunde
_last_call = 0.0

# Serienvorlagen tragen keine shippingConditions, die Rechnung braucht sie aber.
# Die Periode leiten wir aus dem Ausführungsintervall ab.
INTERVAL_MONTHS = {"MONTHLY": 1, "QUARTERLY": 3, "BIANNUALLY": 6, "ANNUALLY": 12}
INTERVAL_DAYS = {"WEEKLY": 7, "BIWEEKLY": 14}
PERIOD_TYPES = {"serviceperiod", "deliveryperiod"}
DATED_TYPES = {"service", "serviceperiod", "delivery", "deliveryperiod"}


def api(path: str, method: str = "GET", **kw) -> requests.Response:
    global _last_call
    key = os.environ.get("LEXWARE_API_KEY")
    if not key:
        raise SystemExit("LEXWARE_API_KEY ist nicht gesetzt")
    headers = {"Authorization": f"Bearer {key}", "Accept": "application/json"}
    headers.update(kw.pop("headers", {}))
    for attempt in range(5):
        wait = MIN_INTERVAL - (time.monotonic() - _last_call)
        if wait > 0:
            time.sleep(wait)
        _last_call = time.monotonic()
        r = requests.request(method, f"{BASE}{path}", headers=headers, timeout=60, **kw)
        if r.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        if r.status_code >= 400:
            raise RuntimeError(f"{method} {path} -> {r.status_code}: {r.text[:600]}")
        return r
    raise RuntimeError(f"{method} {path}: dauerhaft 429, Ratelimit nicht eingehalten")


def list_templates() -> list[dict]:
    out, page = [], 0
    while True:
        r = api(f"/recurring-templates?page={page}&size=250").json()
        out.extend(r.get("content", []))
        if r.get("last", True):
            return out
        page += 1


def is_due(t: dict, on: dt.date) -> bool:
    s = t.get("recurringTemplateSettings") or {}
    nxt = s.get("nextExecutionDate")
    return s.get("executionStatus") == "ACTIVE" and bool(nxt) and dt.date.fromisoformat(nxt) <= on


def add_months(d: dt.date, months: int) -> dt.date:
    m = d.month - 1 + months
    y, m = d.year + m // 12, m % 12 + 1
    return d.replace(year=y, month=m, day=min(d.day, calendar.monthrange(y, m)[1]))


def shipping_conditions(t: dict, start: dt.date) -> dict:
    s = t.get("recurringTemplateSettings") or {}
    stype = s.get("shippingType") or "service"
    sc: dict = {"shippingType": stype}
    if stype in DATED_TYPES:
        sc["shippingDate"] = start.isoformat()
    if stype in PERIOD_TYPES:
        iv = s.get("executionInterval") or "MONTHLY"
        if iv in INTERVAL_MONTHS:
            end = add_months(start, INTERVAL_MONTHS[iv]) - dt.timedelta(days=1)
        else:
            end = start + dt.timedelta(days=INTERVAL_DAYS.get(iv, 30) - 1)
        sc["shippingEndDate"] = end.isoformat()
    return sc


def invoice_payload(t: dict, voucher_date: dt.date) -> dict:
    """Kaufmännischen Inhalt der Vorlage in eine Rechnung übertragen.

    Die contactId ist das entscheidende Feld: darüber zieht Lexware die Leitweg-ID aus dem
    Kontakt und erzeugt die XRechnung. Niemals stattdessen eine freie Adresse senden.
    Read-only-Felder (lineItemAmount, paymentTermLabelTemplate, taxAmounts,
    recurringTemplateSettings) gehören nicht in den POST und werden hier entfernt.
    """
    addr = t.get("address") or {}
    if not addr.get("contactId"):
        raise ValueError(f"Vorlage {t.get('id')} hat keine contactId, ohne Kontakt keine XRechnung")

    items = []
    for li in t.get("lineItems") or []:
        items.append({k: v for k, v in li.items() if k != "lineItemAmount"})

    total = {"currency": (t.get("totalPrice") or {}).get("currency", "EUR")}
    for k in ("totalDiscountAbsolute", "totalDiscountPercentage"):
        if (t.get("totalPrice") or {}).get(k) is not None:
            total[k] = t["totalPrice"][k]

    stamp = dt.datetime.combine(voucher_date, dt.time(0, 0), TZ)
    payload = {
        "archived": False,
        "voucherDate": stamp.strftime("%Y-%m-%dT%H:%M:%S.000") + stamp.strftime("%z")[:3] + ":00",
        "address": {"contactId": addr["contactId"]},
        "lineItems": items,
        "totalPrice": total,
        "taxConditions": {k: v for k, v in t["taxConditions"].items() if v is not None},
        "shippingConditions": shipping_conditions(t, voucher_date),
    }
    if t.get("paymentConditions"):
        payload["paymentConditions"] = {
            k: v for k, v in t["paymentConditions"].items() if k != "paymentTermLabelTemplate"
        }
    for k in ("language", "title", "introduction", "remark"):
        if t.get(k) is not None:
            payload[k] = t[k]
    return payload


def create_invoice(payload: dict) -> str:
    # finalize=true: nur finalisierte Rechnungen haben ein Dokument, Entwürfe liefern 409.
    # Beim Anlegen prüft Lexware zusätzlich gegen die XRechnung-Spezifikation.
    r = api("/invoices?finalize=true", "POST", json=payload,
            headers={"Content-Type": "application/json"})
    return r.json()["id"]


def download_xml(invoice_id: str, out_dir: pathlib.Path) -> pathlib.Path:
    inv = api(f"/invoices/{invoice_id}").json()
    profile = inv.get("electronicDocumentProfile")
    if profile != "XRechnung":
        raise RuntimeError(f"Rechnung {invoice_id} hat Profil {profile!r} statt XRechnung. "
                           "Leitweg-ID und Lieferantennummer am Kontakt prüfen.")
    r = api(f"/invoices/{invoice_id}/file", headers={"Accept": "application/xml"})
    path = out_dir / f"{inv.get('voucherNumber', invoice_id)}.xml"
    path.write_bytes(r.content)
    return path


def main() -> int:
    ap = argparse.ArgumentParser()
    g = ap.add_mutually_exclusive_group(required=True)
    g.add_argument("--dry-run", action="store_true", help="nur lesen und anzeigen")
    g.add_argument("--live", action="store_true", help="Rechnungen wirklich anlegen")
    ap.add_argument("--yes", action="store_true", help="für --live zwingend erforderlich")
    ap.add_argument("--template", action="append", default=[], help="Vorlagen-ID, mehrfach möglich")
    ap.add_argument("--all", action="store_true", help="auch nicht fällige Vorlagen")
    ap.add_argument("--date", default=dt.date.today().isoformat(), help="Rechnungsdatum JJJJ-MM-TT")
    ap.add_argument("--out", default="./xrechnung-out")
    ap.add_argument("--templates-file", help="JSON-Datei statt API (zum Testen des Trockenlaufs)")
    a = ap.parse_args()

    if a.live and not a.yes:
        raise SystemExit("--live braucht zusätzlich --yes")

    voucher_date = dt.date.fromisoformat(a.date)
    if a.templates_file:
        templates = json.loads(pathlib.Path(a.templates_file).read_text(encoding="utf-8"))
    else:
        templates = list_templates()
    if a.template:
        templates = [t for t in templates if t.get("id") in set(a.template)]
    elif not a.all:
        templates = [t for t in templates if is_due(t, voucher_date)]
    if not templates:
        raise SystemExit("keine passende Serienvorlage gefunden")

    out_dir = pathlib.Path(a.out)
    out_dir.mkdir(parents=True, exist_ok=True)
    for t in templates:
        payload = invoice_payload(t, voucher_date)
        name = (t.get("address") or {}).get("name", "?")
        if a.dry_run:
            print(f"--- Vorlage {t['id']} ({name}) -> POST /invoices?finalize=true")
            print(json.dumps(payload, indent=2, ensure_ascii=False))
            continue
        inv_id = create_invoice(payload)
        print(f"{name}: Rechnung {inv_id} -> {download_xml(inv_id, out_dir)}")
    return 0


if __name__ == "__main__":
    sys.exit(main())