xrechnung 0.1.0__tar.gz

xrechnung-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+build/

xrechnung-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xrechnung.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xrechnung-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: xrechnung
+Version: 0.1.0
+Summary: Python client for the xrechnung.dev API: generate, validate (official KoSIT rules) and parse XRechnung and ZUGFeRD e-invoices. Zero dependencies, no JVM required.
+Project-URL: Homepage, https://xrechnung.dev
+Project-URL: Documentation, https://xrechnung.dev/xrechnung-api/
+Project-URL: API reference, https://xrechnung.dev/docs
+Project-URL: Error codes, https://xrechnung.dev/xrechnung-fehlercodes/
+Author-email: "xrechnung.dev" <dev@xrechnung.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: e-rechnung,einvoice,en16931,factur-x,kosit,validator,xrechnung,zugferd
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Natural Language :: German
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# xrechnung
+
+Python client for the [xrechnung.dev](https://xrechnung.dev) REST API: **generate, validate and parse**
+German EN 16931 e-invoices — XRechnung 3.0 XML and ZUGFeRD 2.x PDF/A-3 — with one function call.
+
+- **No JVM required.** Validation runs server-side; you don't install the KoSIT validator or Java.
+- **Always validated with the current official KoSIT rules (XRechnung 3.0.2, Schematron 2.6.0).**
+  Every generated document is checked before it is returned, so you never receive an invalid invoice.
+- **Zero dependencies.** Standard library only (`urllib`), Python 3.9+, fully typed.
+- **Free tier:** 10 documents per month without an API key.
+- Every error links to a plain-language explanation, e.g. `BR-DE-15` → https://xrechnung.dev/fehler/br-de-15/
+
+```bash
+pip install xrechnung
+```
+
+## Validate
+
+```python
+import xrechnung
+
+result = xrechnung.validate("rechnung.xml")      # path, or raw bytes; XML or ZUGFeRD PDF
+print(result.valid, result.scenario)
+for e in result.errors:
+    print(e.code, e.message, e.location)
+    print("  how to fix:", e.doc_url)             # https://xrechnung.dev/fehler/br-de-15/
+```
+
+`result.warnings` has the same shape; `result.raw` is the full JSON report.
+
+## Generate
+
+```python
+invoice = {
+    "number": "RE-2026-0001", "issue_date": "2026-09-07",
+    "seller": {"name": "Beispiel GmbH", "vat_id": "DE123456789", "email": "rechnung@beispiel.de",
+               "phone": "+49 30 1234567", "contact_name": "Erika Muster",
+               "address": {"street": "Musterstr. 1", "postcode": "10115", "city": "Berlin"}},
+    "buyer": {"name": "Kunde AG", "address": {"street": "Kundenweg 9", "postcode": "80331", "city": "München"}},
+    "buyer_reference": "04011000-12345-67",
+    "lines": [{"description": "Beratung", "quantity": "10", "unit": "HUR", "unit_price": "120.00", "vat_rate": "19"}],
+    "payment": {"iban": "DE02120300000000202051", "due_date": "2026-09-21", "terms": "14 Tage netto"},
+}
+
+xml = xrechnung.generate(invoice)                                   # XRechnung (CII XML) as bytes
+pdf = xrechnung.generate(invoice, format="zugferd", language="en")  # ZUGFeRD PDF/A-3 as bytes
+report = xrechnung.generate(invoice, output="json")                 # dict: base64 file + validation report
+```
+
+`Decimal` and `date` values are serialised as strings, so you can pass them directly.
+The invoice fields follow the [OpenAPI schema](https://xrechnung.dev/docs) (tax categories S/Z/E/AE/K/G/O,
+`small_business` for §19 UStG, credit notes via `type_code` 381 and `preceding_invoice_number`).
+
+## Parse
+
+```python
+data = xrechnung.parse("eingang.pdf")   # {"syntax": "CII", "number": ..., "seller": {...}, "lines": [...], ...}
+```
+
+## API key, usage, errors
+
+```python
+client = xrechnung.Client(api_key="xr_live_...")   # or set XRECHNUNG_API_KEY
+client.validate(b"<Invoice ...>")
+client.usage()                                      # this month's usage
+```
+
+| HTTP | Exception | Meaning |
+|------|-----------|---------|
+| 401 | `xrechnung.AuthenticationError` | invalid or inactive API key |
+| 402 | `xrechnung.PaymentRequiredError` | payment / plan required |
+| 429 | `xrechnung.RateLimitError` | monthly limit reached or too many requests |
+| other | `xrechnung.XRechnungError` | base class; `.status`, `.message` (the server's text), `.body` |
+
+Limits: 5 MB per document, 60 s timeout. Plans: Free 10 / Developer 200 / Business 1,000 / Unlimited
+documents per month — see https://xrechnung.dev/#pricing.
+
+The same client is also published as [`zugferd`](https://pypi.org/project/zugferd/) (`import zugferd`).
+
+---
+
+## Deutsch
+
+Python-Client für die [xrechnung.dev](https://xrechnung.dev)-API: **E-Rechnungen erzeugen, prüfen und lesen**
+— XRechnung 3.0 (XML) und ZUGFeRD 2.x (PDF/A-3).
+
+- **Keine JVM nötig.** Sie installieren weder Java noch den KoSIT-Validator.
+- **Immer mit den aktuellen offiziellen KoSIT-Regeln geprüft (XRechnung 3.0.2, Schematron 2.6.0).**
+  Jede erzeugte Rechnung wird vor der Auslieferung validiert.
+- **Keine Abhängigkeiten**, nur Standardbibliothek, Python ab 3.9.
+- **Kostenlos:** 10 Dokumente pro Monat ohne API-Schlüssel.
+- Zu jedem Fehlercode gibt es eine Erklärung mit Lösung, z. B. https://xrechnung.dev/fehler/br-de-15/
+
+```python
+import xrechnung
+
+ergebnis = xrechnung.validate("rechnung.xml")
+if not ergebnis.valid:
+    for f in ergebnis.errors:
+        print(f.code, f.message, f.doc_url)
+
+pdf = xrechnung.generate(rechnung, format="zugferd")   # ZUGFeRD-PDF
+open("RE-2026-0001.pdf", "wb").write(pdf)
+```
+
+Fehler 401 (Schlüssel ungültig), 402 (Zahlung erforderlich) und 429 (Monatslimit erreicht) werden als
+eigene Exceptions mit der Meldung des Servers ausgelöst.
+
+## License
+
+MIT

xrechnung-0.1.0/README.md

@@ -0,0 +1,111 @@
+# xrechnung
+
+Python client for the [xrechnung.dev](https://xrechnung.dev) REST API: **generate, validate and parse**
+German EN 16931 e-invoices — XRechnung 3.0 XML and ZUGFeRD 2.x PDF/A-3 — with one function call.
+
+- **No JVM required.** Validation runs server-side; you don't install the KoSIT validator or Java.
+- **Always validated with the current official KoSIT rules (XRechnung 3.0.2, Schematron 2.6.0).**
+  Every generated document is checked before it is returned, so you never receive an invalid invoice.
+- **Zero dependencies.** Standard library only (`urllib`), Python 3.9+, fully typed.
+- **Free tier:** 10 documents per month without an API key.
+- Every error links to a plain-language explanation, e.g. `BR-DE-15` → https://xrechnung.dev/fehler/br-de-15/
+
+```bash
+pip install xrechnung
+```
+
+## Validate
+
+```python
+import xrechnung
+
+result = xrechnung.validate("rechnung.xml")      # path, or raw bytes; XML or ZUGFeRD PDF
+print(result.valid, result.scenario)
+for e in result.errors:
+    print(e.code, e.message, e.location)
+    print("  how to fix:", e.doc_url)             # https://xrechnung.dev/fehler/br-de-15/
+```
+
+`result.warnings` has the same shape; `result.raw` is the full JSON report.
+
+## Generate
+
+```python
+invoice = {
+    "number": "RE-2026-0001", "issue_date": "2026-09-07",
+    "seller": {"name": "Beispiel GmbH", "vat_id": "DE123456789", "email": "rechnung@beispiel.de",
+               "phone": "+49 30 1234567", "contact_name": "Erika Muster",
+               "address": {"street": "Musterstr. 1", "postcode": "10115", "city": "Berlin"}},
+    "buyer": {"name": "Kunde AG", "address": {"street": "Kundenweg 9", "postcode": "80331", "city": "München"}},
+    "buyer_reference": "04011000-12345-67",
+    "lines": [{"description": "Beratung", "quantity": "10", "unit": "HUR", "unit_price": "120.00", "vat_rate": "19"}],
+    "payment": {"iban": "DE02120300000000202051", "due_date": "2026-09-21", "terms": "14 Tage netto"},
+}
+
+xml = xrechnung.generate(invoice)                                   # XRechnung (CII XML) as bytes
+pdf = xrechnung.generate(invoice, format="zugferd", language="en")  # ZUGFeRD PDF/A-3 as bytes
+report = xrechnung.generate(invoice, output="json")                 # dict: base64 file + validation report
+```
+
+`Decimal` and `date` values are serialised as strings, so you can pass them directly.
+The invoice fields follow the [OpenAPI schema](https://xrechnung.dev/docs) (tax categories S/Z/E/AE/K/G/O,
+`small_business` for §19 UStG, credit notes via `type_code` 381 and `preceding_invoice_number`).
+
+## Parse
+
+```python
+data = xrechnung.parse("eingang.pdf")   # {"syntax": "CII", "number": ..., "seller": {...}, "lines": [...], ...}
+```
+
+## API key, usage, errors
+
+```python
+client = xrechnung.Client(api_key="xr_live_...")   # or set XRECHNUNG_API_KEY
+client.validate(b"<Invoice ...>")
+client.usage()                                      # this month's usage
+```
+
+| HTTP | Exception | Meaning |
+|------|-----------|---------|
+| 401 | `xrechnung.AuthenticationError` | invalid or inactive API key |
+| 402 | `xrechnung.PaymentRequiredError` | payment / plan required |
+| 429 | `xrechnung.RateLimitError` | monthly limit reached or too many requests |
+| other | `xrechnung.XRechnungError` | base class; `.status`, `.message` (the server's text), `.body` |
+
+Limits: 5 MB per document, 60 s timeout. Plans: Free 10 / Developer 200 / Business 1,000 / Unlimited
+documents per month — see https://xrechnung.dev/#pricing.
+
+The same client is also published as [`zugferd`](https://pypi.org/project/zugferd/) (`import zugferd`).
+
+---
+
+## Deutsch
+
+Python-Client für die [xrechnung.dev](https://xrechnung.dev)-API: **E-Rechnungen erzeugen, prüfen und lesen**
+— XRechnung 3.0 (XML) und ZUGFeRD 2.x (PDF/A-3).
+
+- **Keine JVM nötig.** Sie installieren weder Java noch den KoSIT-Validator.
+- **Immer mit den aktuellen offiziellen KoSIT-Regeln geprüft (XRechnung 3.0.2, Schematron 2.6.0).**
+  Jede erzeugte Rechnung wird vor der Auslieferung validiert.
+- **Keine Abhängigkeiten**, nur Standardbibliothek, Python ab 3.9.
+- **Kostenlos:** 10 Dokumente pro Monat ohne API-Schlüssel.
+- Zu jedem Fehlercode gibt es eine Erklärung mit Lösung, z. B. https://xrechnung.dev/fehler/br-de-15/
+
+```python
+import xrechnung
+
+ergebnis = xrechnung.validate("rechnung.xml")
+if not ergebnis.valid:
+    for f in ergebnis.errors:
+        print(f.code, f.message, f.doc_url)
+
+pdf = xrechnung.generate(rechnung, format="zugferd")   # ZUGFeRD-PDF
+open("RE-2026-0001.pdf", "wb").write(pdf)
+```
+
+Fehler 401 (Schlüssel ungültig), 402 (Zahlung erforderlich) und 429 (Monatslimit erreicht) werden als
+eigene Exceptions mit der Meldung des Servers ausgelöst.
+
+## License
+
+MIT

xrechnung-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xrechnung"
+version = "0.1.0"
+description = "Python client for the xrechnung.dev API: generate, validate (official KoSIT rules) and parse XRechnung and ZUGFeRD e-invoices. Zero dependencies, no JVM required."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "xrechnung.dev", email = "dev@xrechnung.dev" }]
+keywords = ["xrechnung", "zugferd", "factur-x", "e-rechnung", "einvoice", "en16931", "kosit", "validator"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Natural Language :: German",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://xrechnung.dev"
+Documentation = "https://xrechnung.dev/xrechnung-api/"
+"API reference" = "https://xrechnung.dev/docs"
+"Error codes" = "https://xrechnung.dev/xrechnung-fehlercodes/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xrechnung"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/xrechnung", "tests", "README.md", "LICENSE"]

xrechnung-0.1.0/src/xrechnung/__init__.py

@@ -0,0 +1,186 @@
+"""Python client for the xrechnung.dev REST API.
+
+Generate, validate (official KoSIT rules) and parse German EN 16931 e-invoices:
+XRechnung 3.0 XML and ZUGFeRD 2.x PDF/A-3. Zero dependencies, no JVM required.
+
+    import xrechnung
+    result = xrechnung.validate("rechnung.xml")
+    for e in result.errors:
+        print(e.code, e.message, e.doc_url)
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import uuid
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client", "Finding", "ValidationResult", "XRechnungError", "AuthenticationError",
+    "PaymentRequiredError", "RateLimitError", "validate", "parse", "generate", "usage", "doc_url",
+]
+
+DEFAULT_BASE_URL = "https://xrechnung.dev"
+FileInput = Union[bytes, bytearray, str, "os.PathLike[str]"]
+
+
+class XRechnungError(Exception):
+    """Any non-2xx answer from the API. `message` is the server's own text."""
+
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status, self.message, self.body = status, message, body
+
+
+class AuthenticationError(XRechnungError):
+    """401: invalid or inactive API key."""
+
+
+class PaymentRequiredError(XRechnungError):
+    """402: plan or payment required."""
+
+
+class RateLimitError(XRechnungError):
+    """429: monthly document limit reached or too many requests per second."""
+
+
+_ERRORS = {401: AuthenticationError, 402: PaymentRequiredError, 429: RateLimitError}
+
+
+def doc_url(code: str) -> str:
+    """Explanation page for a rule code, e.g. BR-DE-15 -> https://xrechnung.dev/fehler/br-de-15/"""
+    return f"https://xrechnung.dev/fehler/{re.sub(r'-[ab]$', '', code.strip().lower())}/"
+
+
+@dataclass
+class Finding:
+    code: str
+    message: str
+    location: str = ""
+
+    @property
+    def doc_url(self) -> str:
+        return doc_url(self.code)
+
+
+def _findings(items: Any) -> List[Finding]:
+    return [Finding(str(i.get("code", "")), str(i.get("message", "")), str(i.get("location") or ""))
+            for i in items or []]
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    scenario: str = ""
+    profile: str = ""
+    errors: List[Finding] = field(default_factory=list)
+    warnings: List[Finding] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "ValidationResult":
+        return cls(bool(d.get("valid")), d.get("scenario", ""), d.get("profile", ""),
+                   _findings(d.get("errors")), _findings(d.get("warnings")), d)
+
+
+def _read(file: FileInput) -> "tuple[bytes, str]":
+    if isinstance(file, (bytes, bytearray)):
+        data = bytes(file)
+        return data, "invoice.pdf" if data[:5] == b"%PDF-" else "invoice.xml"
+    p = Path(file)
+    return p.read_bytes(), p.name
+
+
+def _multipart(data: bytes, filename: str) -> "tuple[bytes, str]":
+    boundary = uuid.uuid4().hex
+    name = filename.replace('"', "").replace("\r", "").replace("\n", "")
+    body = (f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{name}"\r\n'
+            f"Content-Type: application/octet-stream\r\n\r\n").encode() + data + f"\r\n--{boundary}--\r\n".encode()
+    return body, f"multipart/form-data; boundary={boundary}"
+
+
+class Client:
+    """API client. `api_key` defaults to $XRECHNUNG_API_KEY; without a key the free tier
+    allows 10 documents per month per IP."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 90):
+        self.api_key = api_key if api_key is not None else os.environ.get("XRECHNUNG_API_KEY") or None
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, method: str, path: str, body: Optional[bytes] = None,
+                 content_type: Optional[str] = None) -> "tuple[bytes, str]":
+        headers = {"Accept": "application/json, application/xml, application/pdf",
+                   "User-Agent": f"xrechnung-python/{__version__}"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        if self.api_key:
+            headers["X-Api-Key"] = self.api_key
+        req = urllib.request.Request(self.base_url + path, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return r.read(), r.headers.get("Content-Type", "")
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            try:
+                payload: Any = json.loads(raw)
+                detail = payload.get("detail", payload) if isinstance(payload, dict) else payload
+            except ValueError:
+                payload = detail = raw.decode("utf-8", "replace")
+            if isinstance(detail, list):  # 422 from request validation
+                detail = "; ".join(f"{'.'.join(map(str, d.get('loc', [])))}: {d.get('msg')}"
+                                   if isinstance(d, dict) else str(d) for d in detail)
+            raise _ERRORS.get(e.code, XRechnungError)(e.code, str(detail) or str(e.reason), payload) from None
+
+    def _json(self, method: str, path: str, body: Optional[bytes] = None, ct: Optional[str] = None) -> Any:
+        return json.loads(self._request(method, path, body, ct)[0])
+
+    def validate(self, file: FileInput) -> ValidationResult:
+        """Validate an XRechnung / ZUGFeRD / EN 16931 document (XML or PDF): bytes or a path."""
+        return ValidationResult.from_dict(self._json("POST", "/v1/validate", *_multipart(*_read(file))))
+
+    def parse(self, file: FileInput) -> Dict[str, Any]:
+        """Read an e-invoice (XML or ZUGFeRD PDF) into a dict."""
+        return self._json("POST", "/v1/parse", *_multipart(*_read(file)))
+
+    def generate(self, invoice: Dict[str, Any], format: str = "xrechnung", language: str = "de",
+                 output: str = "binary") -> Any:
+        """Generate a KoSIT-validated invoice.
+
+        format: "xrechnung" (CII XML) or "zugferd" (PDF/A-3); language: "de"/"en" (zugferd PDF only).
+        output="binary" returns the file as bytes; output="json" returns a dict with base64 + validation report.
+        """
+        body = json.dumps({"invoice": invoice, "format": format, "language": language, "output": output},
+                          default=str).encode()
+        data, _ = self._request("POST", "/v1/invoices", body, "application/json")
+        return json.loads(data) if output == "json" else data
+
+    def usage(self) -> Dict[str, Any]:
+        """Current month usage for your key (or your IP on the free tier)."""
+        return self._json("GET", "/v1/usage")
+
+
+def validate(file: FileInput, api_key: Optional[str] = None) -> ValidationResult:
+    return Client(api_key).validate(file)
+
+
+def parse(file: FileInput, api_key: Optional[str] = None) -> Dict[str, Any]:
+    return Client(api_key).parse(file)
+
+
+def generate(invoice: Dict[str, Any], format: str = "xrechnung", language: str = "de",
+             output: str = "binary", api_key: Optional[str] = None) -> Any:
+    return Client(api_key).generate(invoice, format, language, output)
+
+
+def usage(api_key: Optional[str] = None) -> Dict[str, Any]:
+    return Client(api_key).usage()

xrechnung-0.1.0/tests/test_client.py

@@ -0,0 +1,167 @@
+"""Offline tests: urllib.request.urlopen is mocked, no network calls."""
+import io
+import json
+import os
+import tempfile
+import unittest
+import urllib.error
+from email.message import Message
+from unittest import mock
+
+import xrechnung
+
+REPORT = {"valid": False, "scenario": "EN16931 XRechnung (CII)",
+          "errors": [{"code": "BR-DE-15", "message": "Buyer reference fehlt", "location": "/rsm:CII"},
+                     {"code": "BR-CO-10-a", "message": "Summe", "location": "/x"}],
+          "warnings": [{"code": "PEPPOL-EN16931-R005", "message": "w", "location": None}],
+          "counts": {"errors": 2, "warnings": 1}}
+
+
+class FakeResp(io.BytesIO):
+    def __init__(self, data, ctype="application/json"):
+        super().__init__(data)
+        self.headers = {"Content-Type": ctype}
+
+    def __enter__(self): return self
+    def __exit__(self, *a): self.close()
+
+
+def http_error(code, body):
+    return urllib.error.HTTPError("https://xrechnung.dev/x", code, "err", Message(), io.BytesIO(body))
+
+
+class Base(unittest.TestCase):
+    def setUp(self):
+        p = mock.patch("urllib.request.urlopen")
+        self.urlopen = p.start()
+        self.addCleanup(p.stop)
+        os.environ.pop("XRECHNUNG_API_KEY", None)
+
+    def reply(self, data, ctype="application/json"):
+        self.urlopen.return_value = FakeResp(json.dumps(data).encode() if not isinstance(data, bytes) else data, ctype)
+
+    @property
+    def req(self):
+        return self.urlopen.call_args[0][0]
+
+
+class TestValidate(Base):
+    def test_bytes_result_and_doc_urls(self):
+        self.reply(REPORT)
+        r = xrechnung.validate(b"<Invoice/>")
+        self.assertFalse(r.valid)
+        self.assertFalse(r)
+        self.assertEqual(r.scenario, "EN16931 XRechnung (CII)")
+        self.assertEqual([e.code for e in r.errors], ["BR-DE-15", "BR-CO-10-a"])
+        self.assertEqual(r.errors[0].location, "/rsm:CII")
+        self.assertEqual(r.errors[0].doc_url, "https://xrechnung.dev/fehler/br-de-15/")
+        self.assertEqual(r.errors[1].doc_url, "https://xrechnung.dev/fehler/br-co-10/")
+        self.assertEqual(r.warnings[0].location, "")
+        self.assertEqual(r.raw["counts"]["errors"], 2)
+        req = self.req
+        self.assertEqual(req.full_url, "https://xrechnung.dev/v1/validate")
+        self.assertEqual(req.get_method(), "POST")
+        self.assertIsNone(req.get_header("X-api-key"))  # free tier: no key sent
+        ct = req.get_header("Content-type")
+        self.assertTrue(ct.startswith("multipart/form-data; boundary="))
+        boundary = ct.split("=", 1)[1]
+        self.assertIn(b'name="file"; filename="invoice.xml"', req.data)
+        self.assertIn(b"\r\n\r\n<Invoice/>\r\n--" + boundary.encode() + b"--\r\n", req.data)
+
+    def test_path_and_pdf_sniff_and_key(self):
+        self.reply({"valid": True, "errors": [], "warnings": []})
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "rechnung.pdf")
+            with open(p, "wb") as f:
+                f.write(b"%PDF-1.7 x")
+            r = xrechnung.Client(api_key="xr_live_k").validate(p)
+        self.assertTrue(r.valid)
+        self.assertIn(b'filename="rechnung.pdf"', self.req.data)
+        self.assertEqual(self.req.get_header("X-api-key"), "xr_live_k")
+        self.reply({"valid": True})
+        xrechnung.validate(b"%PDF-1.7")
+        self.assertIn(b'filename="invoice.pdf"', self.req.data)
+
+    def test_env_key(self):
+        os.environ["XRECHNUNG_API_KEY"] = "envkey"
+        self.addCleanup(os.environ.pop, "XRECHNUNG_API_KEY", None)
+        self.reply({"valid": True})
+        xrechnung.validate(b"<x/>")
+        self.assertEqual(self.req.get_header("X-api-key"), "envkey")
+
+
+class TestOther(Base):
+    def test_parse(self):
+        self.reply({"syntax": "CII", "number": "RE-1"})
+        self.assertEqual(xrechnung.parse(b"<x/>")["number"], "RE-1")
+        self.assertEqual(self.req.full_url, "https://xrechnung.dev/v1/parse")
+
+    def test_generate_binary(self):
+        self.reply(b"%PDF-1.7 data", "application/pdf")
+        inv = {"number": "RE-1", "issue_date": "2026-09-07"}
+        out = xrechnung.generate(inv, format="zugferd", language="en")
+        self.assertEqual(out, b"%PDF-1.7 data")
+        self.assertEqual(self.req.full_url, "https://xrechnung.dev/v1/invoices")
+        self.assertEqual(self.req.get_header("Content-type"), "application/json")
+        self.assertEqual(json.loads(self.req.data),
+                         {"invoice": inv, "format": "zugferd", "language": "en", "output": "binary"})
+
+    def test_generate_json_and_decimal(self):
+        from decimal import Decimal
+        self.reply({"file": "PD94", "validation": {"valid": True}})
+        out = xrechnung.generate({"lines": [{"unit_price": Decimal("120.00")}]}, output="json")
+        self.assertEqual(out["validation"]["valid"], True)
+        self.assertEqual(json.loads(self.req.data)["invoice"]["lines"][0]["unit_price"], "120.00")
+
+    def test_usage_and_base_url(self):
+        self.reply({"used": 3, "limit": 10})
+        self.assertEqual(xrechnung.Client(base_url="http://localhost:8000/").usage()["used"], 3)
+        self.assertEqual(self.req.full_url, "http://localhost:8000/v1/usage")
+        self.assertEqual(self.req.get_method(), "GET")
+
+
+class TestErrors(Base):
+    def check(self, code, cls, body, msg):
+        self.urlopen.side_effect = http_error(code, body)
+        with self.assertRaises(cls) as cm:
+            xrechnung.validate(b"<x/>")
+        self.assertIsInstance(cm.exception, xrechnung.XRechnungError)
+        self.assertEqual(cm.exception.status, code)
+        self.assertEqual(cm.exception.message, msg)
+
+    def test_401(self):
+        self.check(401, xrechnung.AuthenticationError, b'{"detail":"invalid or inactive API key"}',
+                   "invalid or inactive API key")
+
+    def test_402(self):
+        self.check(402, xrechnung.PaymentRequiredError, b'{"detail":"payment required"}', "payment required")
+
+    def test_429(self):
+        m = "monthly limit reached (10 documents on the Free plan). Upgrade at https://xrechnung.dev/#pricing"
+        self.check(429, xrechnung.RateLimitError, json.dumps({"detail": m}).encode(), m)
+
+    def test_422_list_and_non_json(self):
+        self.check(422, xrechnung.XRechnungError,
+                   b'{"detail":[{"loc":["body","invoice","number"],"msg":"Field required","type":"missing"}]}',
+                   "body.invoice.number: Field required")
+        self.check(500, xrechnung.XRechnungError, b"Internal Server Error", "Internal Server Error")
+
+
+class TestDocUrl(unittest.TestCase):
+    def test_slugs(self):
+        self.assertEqual(xrechnung.doc_url("BR-DE-15"), "https://xrechnung.dev/fehler/br-de-15/")
+        self.assertEqual(xrechnung.doc_url("BR-CO-10-b"), "https://xrechnung.dev/fehler/br-co-10/")
+        self.assertEqual(xrechnung.doc_url("BR-AE-10"), "https://xrechnung.dev/fehler/br-ae-10/")
+
+
+class TestZugferdAlias(unittest.TestCase):
+    def test_reexport(self):
+        import sys
+        sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "zugferd", "src"))
+        import zugferd
+        self.assertIs(zugferd.validate, xrechnung.validate)
+        self.assertIs(zugferd.Client, xrechnung.Client)
+
+
+if __name__ == "__main__":
+    unittest.main()

xrechnung-0.1.0/zugferd/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xrechnung.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xrechnung-0.1.0/zugferd/README.md

@@ -0,0 +1,26 @@
+# zugferd
+
+Generate, validate and parse **ZUGFeRD 2.x / Factur-X** (PDF/A-3) and **XRechnung** e-invoices from Python
+through the [xrechnung.dev](https://xrechnung.dev) API.
+
+This package is a thin alias of [`xrechnung`](https://pypi.org/project/xrechnung/) — same API, same code.
+Zero dependencies beyond it, **no JVM required**, and every document is always validated with the current
+official KoSIT rules (XRechnung 3.0.2, Schematron 2.6.0).
+
+```bash
+pip install zugferd
+```
+
+```python
+import zugferd
+
+pdf = zugferd.generate(invoice, format="zugferd", language="de")   # PDF/A-3 with embedded EN 16931 XML
+open("rechnung.pdf", "wb").write(pdf)
+
+result = zugferd.validate("rechnung.pdf")
+for e in result.errors:
+    print(e.code, e.message, e.doc_url)
+```
+
+Free tier: 10 documents per month without an API key. See the full documentation in the
+[`xrechnung` README](https://pypi.org/project/xrechnung/). MIT licensed.