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())