facturx-api 0.1.0__py3-none-any.whl

facturx_api/__init__.py

@@ -0,0 +1,39 @@
+"""FacturX API Python SDK (standard library only)."""
+
+from ._client import FacturX, Transport, __version__, urllib_transport
+from ._errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    ConversionPendingError,
+    FacturXError,
+    InvalidRequestError,
+    NotDeliveredError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    TransportError,
+)
+from ._results import ConvertResult, DryRunResult
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "ConflictError",
+    "ConversionPendingError",
+    "ConvertResult",
+    "DryRunResult",
+    "FacturX",
+    "FacturXError",
+    "InvalidRequestError",
+    "NotDeliveredError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "Transport",
+    "TransportError",
+    "__version__",
+    "urllib_transport",
+]

facturx_api/_client.py

@@ -0,0 +1,354 @@
+"""FacturX API client: Python standard library only, no automatic retry."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+from ._errors import (
+    ConversionPendingError,
+    FacturXError,
+    NotDeliveredError,
+    TransportError,
+    api_error,
+)
+from ._results import ConvertResult, DryRunResult
+
+__version__ = "0.1.0"
+
+Response = tuple[int, dict[str, str], bytes]
+Transport = Callable[[str, str, Mapping[str, str], bytes | None], Response]
+FileInput = bytes | str | Path
+
+OUTPUTS = ("facturx_pdfa3", "xml_cii")
+TARGETS = ("en16931", "france_2026")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None  # A redirect must never carry the API key elsewhere.
+
+
+def urllib_transport(timeout: float = 120.0) -> Transport:
+    """Default transport: one HTTP request, no redirect, no retry."""
+    opener = urllib.request.build_opener(_NoRedirect)
+
+    def send(method: str, url: str, headers: Mapping[str, str], body: bytes | None) -> Response:
+        request = urllib.request.Request(url, data=body, headers=dict(headers), method=method)
+        try:
+            response = opener.open(request, timeout=timeout)
+        except urllib.error.HTTPError as exc:
+            response = exc
+        with response:
+            return (
+                response.status,
+                {k.lower(): v for k, v in response.headers.items()},
+                response.read(),
+            )
+
+    return send
+
+
+class FacturX:
+    """Client for the FacturX API.
+
+    There is deliberately no default host: pass ``base_url`` (for example
+    ``https://api.facturxapi.com``) or set ``FACTURX_BASE_URL``.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        *,
+        timeout: float = 120.0,
+        transport: Transport | None = None,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("FACTURX_API_KEY", "")
+        base = base_url if base_url is not None else os.environ.get("FACTURX_BASE_URL", "")
+        if not base:
+            raise ValueError("base_url is required (or set FACTURX_BASE_URL).")
+        if urllib.parse.urlparse(base).scheme != "https":
+            raise ValueError("base_url must use https.")
+        self.base_url = base.rstrip("/")
+        self._send = transport or urllib_transport(timeout)
+
+    # ------------------------------------------------------------------ public
+
+    def dry_run(
+        self,
+        invoice_data: Mapping[str, Any] | str | None = None,
+        *,
+        file: FileInput | None = None,
+        output: str = "facturx_pdfa3",
+        validation_target: str = "en16931",
+        options: Mapping[str, Any] | None = None,
+        lang: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> DryRunResult:
+        """Check an invoice without producing a deliverable (does not consume quota)."""
+        key = idempotency_key or str(uuid.uuid4())
+        data = self._convert_call(
+            invoice_data, file, output, validation_target, options, lang, key, dry_run=True
+        )[0]
+        return DryRunResult(raw=data, idempotency_key=key)
+
+    def convert(
+        self,
+        invoice_data: Mapping[str, Any] | str | None = None,
+        *,
+        file: FileInput | None = None,
+        output: str = "facturx_pdfa3",
+        validation_target: str = "en16931",
+        options: Mapping[str, Any] | None = None,
+        lang: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ConvertResult:
+        """Final conversion (1 processed invoice on the quota, refunded without deliverable).
+
+        Keep ``idempotency_key`` (on the result or on the raised error) to resend
+        the identical request safely; reusing it with a different payload is a
+        ``409 idempotency_conflict``.
+        """
+        key = idempotency_key or str(uuid.uuid4())
+        data, headers = self._convert_call(
+            invoice_data, file, output, validation_target, options, lang, key, dry_run=False
+        )
+        failed = _final_checks(data, output)
+        if failed:
+            raise NotDeliveredError(data, failed, idempotency_key=key)
+        result = data["result"]
+        try:
+            xml = base64.b64decode(result["xml"], validate=True)
+            pdf = self._pdf(result) if output == "facturx_pdfa3" else None
+        except (ValueError, KeyError) as exc:
+            raise NotDeliveredError(
+                data, ["result.xml/pdf decodable"], idempotency_key=key
+            ) from exc
+        return ConvertResult(
+            raw=data, idempotency_key=key, xml=xml, pdf=pdf, output=output, headers=headers
+        )
+
+    def validate(
+        self,
+        file: FileInput,
+        *,
+        validation_target: str | None = None,
+        validation_profile: str | None = None,
+        lang: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Validate an existing Factur-X PDF or XML. Returns the API report as is."""
+        query = _query(
+            validation_target=validation_target, validation_profile=validation_profile, lang=lang
+        )
+        filename, content = _read_file(file)
+        body, content_type = _multipart({}, ("file", filename, content), seed=idempotency_key)
+        headers = {"Content-Type": content_type}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return self._request("POST", "/api/v1/validate" + query, body, headers, idempotency_key)[0]
+
+    def extract(
+        self,
+        file: FileInput,
+        *,
+        validate: bool = False,
+        lang: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Extract the XML embedded in a Factur-X PDF (``result`` as returned by the API).
+
+        The response carries ``xml`` (base64), ``xmlSize`` and the detected ``profile``;
+        ``validate=True`` also runs validation in the same processed-invoice call.
+        """
+        query = _query(validate="true" if validate else None, lang=lang)
+        filename, content = _read_file(file)
+        body, content_type = _multipart({}, ("file", filename, content), seed=idempotency_key)
+        headers = {"Content-Type": content_type}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return self._request("POST", "/api/v1/extract" + query, body, headers, idempotency_key)[0]
+
+    def meta(self) -> dict[str, Any]:
+        """``GET /meta``: public versions, limits and capabilities."""
+        return self._request("GET", "/meta", None, {}, None, auth=False)[0]
+
+    def integration_contract(self) -> dict[str, Any]:
+        """``GET /api/v1/integration-contract``: public ERP integration contract."""
+        return self._request("GET", "/api/v1/integration-contract", None, {}, None, auth=False)[0]
+
+    # ----------------------------------------------------------------- private
+
+    def _convert_call(
+        self,
+        invoice_data: Mapping[str, Any] | str | None,
+        file: FileInput | None,
+        output: str,
+        validation_target: str,
+        options: Mapping[str, Any] | None,
+        lang: str | None,
+        key: str,
+        *,
+        dry_run: bool,
+    ) -> tuple[dict[str, Any], dict[str, str]]:
+        if output not in OUTPUTS:
+            raise ValueError(f"output must be one of {OUTPUTS}")
+        if validation_target not in TARGETS:
+            raise ValueError(f"validation_target must be one of {TARGETS}")
+        if invoice_data is None and file is None:
+            raise ValueError("Provide invoice_data, file, or both.")
+        fields: dict[str, str] = {"output": output, "validation_target": validation_target}
+        if invoice_data is not None:
+            fields["invoice_data"] = _json(invoice_data)
+        if options is not None:
+            fields["options"] = _json(options)
+        upload = ("file", *_read_file(file)) if file is not None else None
+        body, content_type = _multipart(fields, upload, seed=key)
+        query = _query(dry_run="true" if dry_run else None, lang=lang)
+        headers = {"Content-Type": content_type, "Idempotency-Key": key}
+        data, response_headers, status = self._request(
+            "POST", "/api/v1/convert" + query, body, headers, key
+        )
+        if status == 202:
+            raise ConversionPendingError(data, idempotency_key=key)
+        return data, response_headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: bytes | None,
+        headers: dict[str, str],
+        idempotency_key: str | None,
+        *,
+        auth: bool = True,
+    ) -> tuple[dict[str, Any], dict[str, str], int]:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"facturx-api-python/{__version__}",
+            **headers,
+        }
+        if auth:
+            if not self.api_key:
+                raise ValueError("api_key is required (or set FACTURX_API_KEY).")
+            headers["X-API-Key"] = self.api_key
+        try:
+            status, response_headers, raw = self._send(method, self.base_url + path, headers, body)
+        except (OSError, TimeoutError) as exc:
+            raise TransportError(
+                f"{method} {path}: transport failed, outcome unknown ({exc})",
+                idempotency_key=idempotency_key,
+            ) from exc
+        try:
+            data = json.loads(raw) if raw else {}
+        except ValueError:
+            data = {"detail": {"message": raw[:500].decode("utf-8", "replace")}}
+            if 200 <= status < 300:
+                raise FacturXError(f"HTTP {status}: non-JSON response") from None
+        if not 200 <= status < 300:
+            raise api_error(status, data, response_headers, idempotency_key=idempotency_key)
+        return data, response_headers, status
+
+    def _pdf(self, result: dict[str, Any]) -> bytes:
+        inline, url = result.get("pdf"), result.get("pdfUrl")
+        if bool(inline) == bool(url):
+            raise KeyError("expected exactly one of result.pdf / result.pdfUrl")
+        if inline:
+            pdf = base64.b64decode(inline, validate=True)
+        else:
+            if urllib.parse.urlparse(url).scheme != "https":
+                raise ValueError("pdfUrl is not https")
+            # Presigned URL: the API key is NEVER sent to it.
+            status, _, pdf = self._send("GET", url, {}, None)
+            if status != 200:
+                raise ValueError(f"pdfUrl download HTTP {status}")
+        if not pdf.startswith(b"%PDF-"):
+            raise ValueError("deliverable is not a PDF")
+        return pdf
+
+
+def _final_checks(data: dict[str, Any], output: str) -> list[str]:
+    """Documented success fields; HTTP 200 alone does not prove a conversion."""
+    result = data.get("result") or {}
+    checks = {
+        "dry_run is not true": data.get("dry_run") is not True,
+        "success == true": data.get("success") is True,
+        "result.conversionSuccessful == true": result.get("conversionSuccessful") is True,
+        "target.status == verified": (data.get("target") or {}).get("status") == "verified",
+        "result.xml present": bool(result.get("xml")),
+    }
+    if output == "facturx_pdfa3":
+        generated = data.get("finalGeneratedValidation") or {}
+        packaging = (generated.get("validationReadiness") or {}).get("packaging") or {}
+        checks.update(
+            {
+                "result.packagingPerformed == true": result.get("packagingPerformed") is True,
+                "finalGeneratedValidation.status == passed": generated.get("status") == "passed",
+                "finalGeneratedValidation.artifactAvailable == true": generated.get(
+                    "artifactAvailable"
+                )
+                is True,
+                "packaging.status == passed": packaging.get("status") == "passed",
+            }
+        )
+    return [name for name, ok in checks.items() if not ok]
+
+
+def _json(value: Mapping[str, Any] | str) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _query(**params: str | None) -> str:
+    kept = {k: v for k, v in params.items() if v is not None}
+    return "?" + urllib.parse.urlencode(kept) if kept else ""
+
+
+def _read_file(file: FileInput) -> tuple[str, bytes]:
+    if isinstance(file, bytes):
+        return ("invoice.xml" if file.lstrip().startswith(b"<") else "invoice.pdf"), file
+    path = Path(file)
+    return path.name, path.read_bytes()
+
+
+def _multipart(
+    fields: Mapping[str, str],
+    upload: tuple[str, str, bytes] | None = None,
+    seed: str | None = None,
+) -> tuple[bytes, str]:
+    # Same idempotency key + same fields => byte-identical body on a resend.
+    token = hashlib.sha256((seed or uuid.uuid4().hex).encode()).hexdigest()[:32]
+    boundary = "facturx-sdk-" + token
+    parts: list[bytes] = []
+    for name, value in fields.items():
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n'.encode()
+            + value.encode()
+            + b"\r\n"
+        )
+    if upload is not None:
+        name, filename, content = upload
+        mime = "application/pdf" if content.startswith(b"%PDF-") else "application/xml"
+        safe = filename.replace('"', "_").replace("\r", "_").replace("\n", "_")
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; '
+            f'filename="{safe}"\r\nContent-Type: {mime}\r\n\r\n'.encode()
+            + content
+            + b"\r\n"
+        )
+    parts.append(f"--{boundary}--\r\n".encode())
+    body = b"".join(parts)
+    if body.count(boundary.encode()) != len(parts):
+        raise ValueError("multipart boundary collides with the payload")
+    return body, "multipart/form-data; boundary=" + boundary

facturx_api/_errors.py

@@ -0,0 +1,155 @@
+"""Typed errors. Code and message are the API's own values, never rewritten."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FacturXError(Exception):
+    """Base class of every error raised by this SDK."""
+
+
+class TransportError(FacturXError):
+    """The request may or may not have reached the API: its outcome is unknown.
+
+    Send the same request again with the same ``idempotency_key`` to learn the
+    outcome without being charged twice. The SDK never does it for you.
+    """
+
+    def __init__(self, message: str, *, idempotency_key: str | None = None) -> None:
+        super().__init__(message)
+        self.idempotency_key = idempotency_key
+
+
+class ApiError(FacturXError):
+    """The API answered with a non-success HTTP status.
+
+    Attributes mirror the response body: ``code`` is ``detail.error`` (or
+    ``detail.code``), ``message`` is ``detail.message``. ``retryable`` and
+    ``retry_after`` are only what the server said; ``None`` means it said nothing.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        body: Any,
+        headers: dict[str, str],
+        *,
+        idempotency_key: str | None = None,
+    ) -> None:
+        self.status = status
+        self.body = body
+        self.headers = headers
+        self.idempotency_key = idempotency_key
+        data = body if isinstance(body, dict) else {}
+        detail = data.get("detail", data)
+        if not isinstance(detail, dict):
+            detail = {"message": detail} if isinstance(detail, str) else {}
+        self.detail: dict[str, Any] = detail
+        self.code: str | None = detail.get("error") or detail.get("code") or data.get("error")
+        self.message: str | None = detail.get("message")
+        self.issues: list[Any] = list(detail.get("issues") or [])
+        self.retryable: bool | None = detail.get("retryable")
+        self.request_id: str | None = data.get("request_id") or headers.get("x-request-id")
+        self.retry_after: float | None = _retry_after(headers, detail)
+        super().__init__(
+            f"HTTP {status} {self.code or 'unknown_error'}: {self.message or ''}".strip()
+        )
+
+
+class AuthenticationError(ApiError):
+    """401 / 403: missing, invalid or unauthorised API key."""
+
+
+class QuotaExceededError(ApiError):
+    """402: monthly quota of processed invoices reached."""
+
+
+class RateLimitError(ApiError):
+    """429: too many requests."""
+
+
+class InvalidRequestError(ApiError):
+    """400 / 413 / 415 / 422: the request must be fixed; ``issues`` names the fields."""
+
+
+class ConflictError(ApiError):
+    """409: idempotency or context conflict. Read ``code`` before doing anything."""
+
+
+class ServerError(ApiError):
+    """5xx returned by the API."""
+
+
+class ServiceUnavailableError(ServerError):
+    """503: a dependency of the API is unavailable."""
+
+
+class ConversionPendingError(FacturXError):
+    """202: the API accepted the conversion for asynchronous processing.
+
+    No final file is available yet. ``job_id`` and ``idempotency_key`` are kept
+    so the caller decides what to do; the SDK does not poll.
+    """
+
+    def __init__(self, response: dict[str, Any], *, idempotency_key: str | None) -> None:
+        result = response.get("result") or {}
+        self.response = response
+        self.job_id: str | None = result.get("jobId")
+        self.request_id: str | None = response.get("request_id")
+        self.idempotency_key = idempotency_key
+        super().__init__(f"Conversion accepted for async processing (jobId={self.job_id})")
+
+
+class NotDeliveredError(FacturXError):
+    """HTTP 200 without a verified final deliverable.
+
+    HTTP 200 alone does not prove a successful conversion: ``failed_checks``
+    lists which documented fields were not in the required state, ``response``
+    holds the full body.
+    """
+
+    def __init__(
+        self,
+        response: dict[str, Any],
+        failed_checks: list[str],
+        *,
+        idempotency_key: str | None,
+    ) -> None:
+        self.response = response
+        self.failed_checks = failed_checks
+        self.request_id: str | None = response.get("request_id")
+        self.idempotency_key = idempotency_key
+        super().__init__("No verified final file: " + ", ".join(failed_checks))
+
+
+_BY_STATUS: dict[int, type[ApiError]] = {
+    400: InvalidRequestError,
+    401: AuthenticationError,
+    402: QuotaExceededError,
+    403: AuthenticationError,
+    409: ConflictError,
+    413: InvalidRequestError,
+    415: InvalidRequestError,
+    422: InvalidRequestError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}
+
+
+def api_error(
+    status: int, body: Any, headers: dict[str, str], *, idempotency_key: str | None
+) -> ApiError:
+    cls = _BY_STATUS.get(status) or (ServerError if status >= 500 else ApiError)
+    return cls(status, body, headers, idempotency_key=idempotency_key)
+
+
+def _retry_after(headers: dict[str, str], detail: dict[str, Any]) -> float | None:
+    for raw in (headers.get("retry-after"), detail.get("retry_after_seconds")):
+        if raw is None:
+            continue
+        try:
+            return float(raw)
+        except (TypeError, ValueError):
+            continue  # An HTTP-date stays readable in ``headers``; not converted here.
+    return None

facturx_api/_results.py

@@ -0,0 +1,81 @@
+"""Result objects. ``raw`` always holds the full API response, unmodified."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class DryRunResult:
+    """``POST /api/v1/convert?dry_run=true``: free check, no deliverable.
+
+    ``ready`` reads ``generationReadiness.status == "ready"``. It is NOT
+    ``success``: a dry run can report ``success=false`` and still allow the
+    final generation (observed on the staging contract, 05/11/2026).
+    """
+
+    raw: dict[str, Any]
+    idempotency_key: str
+
+    @property
+    def ready(self) -> bool:
+        readiness = self.raw.get("generationReadiness") or {}
+        return self.raw.get("dry_run") is True and readiness.get("status") == "ready"
+
+    @property
+    def generation_readiness(self) -> dict[str, Any]:
+        return dict(self.raw.get("generationReadiness") or {})
+
+    @property
+    def request_id(self) -> str | None:
+        return self.raw.get("request_id")
+
+
+@dataclass(frozen=True)
+class ConvertResult:
+    """Verified final conversion (1 processed invoice on the quota).
+
+    Only built when every documented success field is in its required state;
+    otherwise :class:`~facturx_api.NotDeliveredError` is raised instead.
+    """
+
+    raw: dict[str, Any]
+    idempotency_key: str
+    xml: bytes
+    pdf: bytes | None
+    output: str
+    headers: dict[str, str] = field(default_factory=dict, repr=False)
+
+    @property
+    def request_id(self) -> str | None:
+        return self.raw.get("request_id") or self.headers.get("x-request-id")
+
+    @property
+    def target(self) -> dict[str, Any]:
+        return dict(self.raw.get("target") or {})
+
+    @property
+    def target_profile(self) -> str | None:
+        return (self.raw.get("result") or {}).get("targetProfile")
+
+    @property
+    def xml_sha256(self) -> str:
+        return hashlib.sha256(self.xml).hexdigest()
+
+    @property
+    def pdf_sha256(self) -> str | None:
+        return hashlib.sha256(self.pdf).hexdigest() if self.pdf is not None else None
+
+    def save(self, directory: str | Path, stem: str = "factur-x") -> dict[str, Path]:
+        """Write the deliverable(s) to ``directory`` and return their paths."""
+        out = Path(directory)
+        out.mkdir(parents=True, exist_ok=True)
+        paths = {"xml": out / f"{stem}.xml"}
+        paths["xml"].write_bytes(self.xml)
+        if self.pdf is not None:
+            paths["pdf"] = out / f"{stem}.pdf"
+            paths["pdf"].write_bytes(self.pdf)
+        return paths

facturx_api/cli.py

@@ -0,0 +1,129 @@
+"""``facturx`` command line, built on the SDK. JSON on stdout, one line per run.
+
+Exit codes: 0 success; 1 dry run not ready / no verified file; 2 usage error;
+3 API error; 4 transport failure (outcome unknown: resend with the same key).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._client import OUTPUTS, TARGETS, FacturX, __version__
+from ._errors import (
+    ApiError,
+    ConversionPendingError,
+    NotDeliveredError,
+    TransportError,
+)
+
+EXIT_OK, EXIT_NOT_READY, EXIT_USAGE, EXIT_API, EXIT_TRANSPORT = 0, 1, 2, 3, 4
+
+
+def _parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--base-url", help="API host (default: $FACTURX_BASE_URL)")
+    common.add_argument("--api-key", help="API key (default: $FACTURX_API_KEY)")
+    common.add_argument("--timeout", type=float, default=120.0, help="seconds (default 120)")
+
+    conv = argparse.ArgumentParser(add_help=False)
+    conv.add_argument("invoice", type=Path, help="complete ERP invoice JSON file")
+    conv.add_argument("--target", choices=TARGETS, default="en16931")
+    conv.add_argument("--output", choices=OUTPUTS, default="facturx_pdfa3")
+    conv.add_argument("--idempotency-key", help="reuse it to resend the same operation")
+
+    parser = argparse.ArgumentParser(prog="facturx", description="FacturX API command line")
+    parser.add_argument("--version", action="version", version=f"facturx {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("dry-run", parents=[common, conv], help="free check, no deliverable (no quota)")
+    convert = sub.add_parser(
+        "convert", parents=[common, conv], help="final conversion (1 invoice on the quota)"
+    )
+    convert.add_argument("--out", type=Path, required=True, help="directory for the files")
+    validate = sub.add_parser("validate", parents=[common], help="validate a PDF or XML file")
+    validate.add_argument("file", type=Path)
+    validate.add_argument("--target", choices=TARGETS)
+    return parser
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+
+def _error(exc: Exception) -> dict[str, Any]:
+    out: dict[str, Any] = {"type": type(exc).__name__, "message": str(exc)}
+    for name in ("status", "code", "request_id", "retryable", "retry_after", "issues"):
+        if getattr(exc, name, None) not in (None, []):
+            out[name] = getattr(exc, name)
+    if isinstance(exc, ApiError) and exc.message is not None:
+        out["api_message"] = exc.message
+    for name in ("idempotency_key", "job_id", "failed_checks"):
+        if getattr(exc, name, None):
+            out[name] = getattr(exc, name)
+    return out
+
+
+def main(argv: list[str] | None = None, client: FacturX | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        fx = client or FacturX(args.api_key, args.base_url, timeout=args.timeout)
+        if args.command == "validate":
+            report = fx.validate(args.file, validation_target=args.target)
+            _emit({"ok": True, "command": "validate", "report": report})
+            return EXIT_OK
+        invoice = json.loads(args.invoice.read_text(encoding="utf-8"))
+        kwargs = {
+            "output": args.output,
+            "validation_target": args.target,
+            "idempotency_key": args.idempotency_key,
+        }
+        if args.command == "dry-run":
+            check = fx.dry_run(invoice, **kwargs)
+            _emit(
+                {
+                    "ok": check.ready,
+                    "command": "dry-run",
+                    "ready": check.ready,
+                    "generation_readiness": check.generation_readiness,
+                    "request_id": check.request_id,
+                    "idempotency_key": check.idempotency_key,
+                }
+            )
+            return EXIT_OK if check.ready else EXIT_NOT_READY
+        doc = fx.convert(invoice, **kwargs)
+        paths = doc.save(args.out)
+        files = {kind: {"path": str(path)} for kind, path in paths.items()}
+        files["xml"].update(bytes=len(doc.xml), sha256=doc.xml_sha256)
+        if doc.pdf is not None:
+            files["pdf"].update(bytes=len(doc.pdf), sha256=doc.pdf_sha256)
+        _emit(
+            {
+                "ok": True,
+                "command": "convert",
+                "target": doc.target,
+                "target_profile": doc.target_profile,
+                "files": files,
+                "request_id": doc.request_id,
+                "idempotency_key": doc.idempotency_key,
+            }
+        )
+        return EXIT_OK
+    except (ValueError, OSError) as exc:  # bad arguments, unreadable input, invalid JSON
+        _emit({"ok": False, "command": args.command, "error": _error(exc)})
+        return EXIT_USAGE
+    except (NotDeliveredError, ConversionPendingError) as exc:
+        _emit({"ok": False, "command": args.command, "error": _error(exc)})
+        return EXIT_NOT_READY
+    except ApiError as exc:
+        _emit({"ok": False, "command": args.command, "error": _error(exc)})
+        return EXIT_API
+    except TransportError as exc:
+        _emit({"ok": False, "command": args.command, "error": _error(exc)})
+        return EXIT_TRANSPORT
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

facturx_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: facturx-api
+Version: 0.1.0
+Summary: Python client for the FacturX API: dry run, Factur-X PDF/A-3 conversion, validation.
+License: MIT
+Project-URL: Homepage, https://github.com/facturxapi/sdk
+Project-URL: Source, https://github.com/facturxapi/sdk/tree/main/python
+Project-URL: Issues, https://github.com/facturxapi/sdk/issues
+Keywords: factur-x,facturx,en16931,e-invoicing,facture-electronique
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# facturx-api (Python)
+
+Client Python de FacturX API : simulation gratuite (`dry_run`), conversion finale en
+Factur-X PDF/A-3 (ou XML CII), validation d'un fichier existant. Bibliothèque standard
+uniquement, Python 3.10+.
+
+> Statut 0.1.0 : **non publié sur PyPI.** Installation depuis la wheel construite localement.
+> Parcours facture → fichiers exécuté contre staging le 06/11/2026 (voir « Ce qui est prouvé »).
+
+## Installation (locale)
+
+```bash
+cd sdk/python && python -m build          # produit dist/facturx_api-0.1.0-py3-none-any.whl
+pip install dist/facturx_api-0.1.0-py3-none-any.whl
+```
+
+## Utilisation
+
+```python
+import json
+from facturx_api import FacturX
+
+fx = FacturX(api_key="…", base_url="https://api.facturxapi.com")
+invoice = json.load(open("invoice.json"))  # JSON ERP complet
+
+check = fx.dry_run(invoice)  # gratuit, aucun livrable
+if check.ready:  # generationReadiness.status == "ready"
+    doc = fx.convert(invoice)  # 1 facture traitée sur le quota
+    print(doc.save("out"))  # out/factur-x.pdf et out/factur-x.xml
+```
+
+Il n'y a **pas d'hôte par défaut** : `base_url` (ou `FACTURX_BASE_URL`) est obligatoire.
+`api_key` peut venir de `FACTURX_API_KEY`.
+
+- `ready` lit `generationReadiness.status`, pas `success` : une simulation peut répondre
+  `success=false` et autoriser quand même la génération.
+- `convert` ne renvoie un résultat que si tous les champs de succès documentés sont au bon
+  état (`success`, `result.conversionSuccessful`, `target.status == verified`,
+  `finalGeneratedValidation`, packaging PDF/A-3). Sinon `NotDeliveredError.failed_checks`
+  dit lesquels : un HTTP 200 seul ne prouve rien.
+- Si le PDF arrive par URL signée (`result.pdfUrl`), il est téléchargé **sans** la clé API.
+
+Autres appels : `fx.validate(path_or_bytes, validation_target="en16931")`,
+`fx.extract(pdf)` (XML embarqué d'un PDF Factur-X), `fx.meta()`, `fx.integration_contract()`
+(ces deux derniers sans clé). Exemples exécutés : `sdk/examples/`.
+
+## Ligne de commande `facturx`
+
+Installée avec le paquet. Sortie JSON sur une ligne ; `FACTURX_API_KEY` et `FACTURX_BASE_URL`
+(ou `--api-key`, `--base-url`).
+
+| Commande | Effet | Code de sortie |
+|---|---|---|
+| `facturx dry-run invoice.json` | simulation gratuite | 0 prêt, 1 non prêt |
+| `facturx convert invoice.json --out DIR` | conversion finale, écrit `DIR/factur-x.pdf` et `.xml` | 0, ou 1 sans fichier vérifié |
+| `facturx validate FICHIER [--target en16931]` | rapport de validation de l'API | 0 |
+
+Codes communs : 2 argument ou fichier invalide, 3 erreur API (`code`, `api_message`,
+`request_id` tels que l'API les envoie), 4 transport coupé (résultat inconnu : relancer avec
+`--idempotency-key` égal à la clé affichée). Options `--target`, `--output`, `--idempotency-key`.
+
+Exécution réelle contre staging (release `900685311ea7`, 06/11/2026 15:56Z, clé sandbox de test) :
+
+```text
+$ facturx dry-run invoice.json
+{"ok": true, "command": "dry-run", "ready": true, "generation_readiness": {"status": "ready", "blockingInputCount": 0, "reason": "no_generation_blocking_inputs"}, "request_id": "f0bb01da-564c-49ec-b4f0-2371f578773e", "idempotency_key": "b4aa1cc0-e675-4ffa-8ae6-644b111754f5"}
+$ facturx convert invoice.json --out out-cli
+{"ok": true, "command": "convert", "target": {"requested": "en16931", "executed": "en16931", "status": "verified", "missing_inputs": [], "not_run_reason": null}, "target_profile": "EN16931", "files": {"xml": {"path": "out-cli/factur-x.xml", "bytes": 4584, "sha256": "f332975e12f8dac94c926d8832c6434daf3ae718e3b10fb8acb9758bc940e03c"}, "pdf": {"path": "out-cli/factur-x.pdf", "bytes": 20624, "sha256": "75fd1d5e30ecf539a54ffc639134a17105b3b97e04941079c530cf2bb87ecd80"}}, "request_id": "66739ba5-e3c8-457b-9343-a90a9e836900", "idempotency_key": "df90c5ce-6b58-420d-a46b-4f72224b19e2"}
+$ facturx validate out-cli/factur-x.pdf --target en16931   # extrait du rapport
+ok= True | valid= True | validationStatus= valid | profile= EN16931 | target.status= verified | errors= 0
+$ FACTURX_API_KEY=invalid facturx dry-run invoice.json      # code de sortie 3
+{"ok": false, "command": "dry-run", "error": {"type": "AuthenticationError", "message": "HTTP 401 invalid_api_key: The API key provided is invalid or revoked.", "status": 401, "code": "invalid_api_key", "request_id": "1c393ffb-981e-4bca-b148-57b8170a8240", "api_message": "The API key provided is invalid or revoked.", "idempotency_key": "42b47d9a-8ef4-4b22-90dd-17405957ffa2"}}
+```
+
+## Erreurs
+
+| Exception | Quand |
+|---|---|
+| `AuthenticationError` | 401 / 403 |
+| `QuotaExceededError` | 402 |
+| `RateLimitError` | 429 |
+| `InvalidRequestError` | 400 / 413 / 415 / 422 ; `issues` nomme les champs |
+| `ConflictError` | 409 (idempotence, contexte) |
+| `ServiceUnavailableError` / `ServerError` | 503 / autres 5xx |
+| `ConversionPendingError` | 202 : traitement asynchrone, `job_id` |
+| `NotDeliveredError` | 200 sans fichier final vérifié |
+| `TransportError` | réseau coupé : **résultat inconnu** |
+
+Toute `ApiError` porte `status`, `code` et `message` **tels que l'API les a envoyés**, plus
+`request_id`, `issues`, `detail`, et `retryable` / `retry_after` seulement si le serveur les
+a fournis (`None` sinon).
+
+## Idempotence et reprise
+
+Chaque appel `convert` / `dry_run` envoie un `Idempotency-Key` (UUID généré, ou le vôtre
+via `idempotency_key=`). La clé est rendue sur le résultat **et** sur toute erreur. Pour
+connaître l'issue d'une opération interrompue sans payer deux fois, renvoyez la même
+requête avec la même clé : le corps envoyé est identique à l'octet près. Réutiliser une clé
+avec une autre facture provoque `409 idempotency_conflict`.
+
+**Le SDK ne relance jamais rien automatiquement.** La règle « un 5xx peut-il être renvoyé
+tel quel » est en cours de fixation côté API (api#2111) ; tant qu'elle n'est pas publiée,
+la décision reste à l'appelant.
+
+## Ce qui est prouvé (06/11/2026)
+
+- 24 tests hors réseau (`PYTHONPATH=src python -m unittest discover -s tests`), sockets interdits,
+  dont 8 pour la CLI et le rejeu de la conversion staging réelle (`tests/cassettes/` : réponses réelles réduites aux champs lus, PDF omis, XML réel).
+- Parcours réel contre staging (release `900685311ea7`), clé sandbox de test, facture
+  `tests/fixtures/invoice.json`, même enchaînement que l’exemple « Utilisation », 06/11/2026 15:48Z :
+
+```text
+dry_run.ready = True | generationReadiness.status = ready | success = False | request_id = ea443cc8-30dd-4c17-b991-697d52f97646
+convert: target = {"requested": "en16931", "executed": "en16931", "status": "verified", "missing_inputs": [], "not_run_reason": null} | profile = EN16931 | request_id = 2db8ddcb-8541-48e1-ae99-a1416221f6b3
+pdf bytes = 20624 sha256 = dd9abd2cbab9679abdaf6e397fd0805032413a406bd757de23d009b4108f41f7 | starts b'%PDF-1.7'
+xml bytes = 4584 sha256 = f332975e12f8dac94c926d8832c6434daf3ae718e3b10fb8acb9758bc940e03c
+seconds command -> files = 21.426
+```
+
+  Le XML est identique, octet pour octet, à celui obtenu le 05/11 par `examples/first-file`
+  pour la même facture. PDF/A-3 et EN16931 sont attestés par l'API, pas revérifiés localement.
+- Sans clé : `meta()`, `integration_contract()` et une clé invalide ⇒ `AuthenticationError`
+  401 `invalid_api_key` avec le message de l'API intact.
+- `validate` : exécuté réellement via la CLI sur le PDF produit (voir « Ligne de commande »).
+- `extract` : exécuté réellement, XML extrait identique au XML produit (`sdk/examples/extract-xml/run.txt`).
+- `output="xml_cii"` : exécuté réellement pour EN16931 et EXTENDED (`sdk/examples/urn-par-profil/run.txt`).
+
+**Pas encore prouvé avec ce SDK** : téléchargement par URL signée (`pdfUrl`), réponses 409/503
+réelles (exercées hors ligne uniquement).

facturx_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+facturx_api/__init__.py,sha256=cGkm_9oJhKDRoX65Jlv1BstD40H-hzmEeEQJ1GvkJKY,880
+facturx_api/_client.py,sha256=ngPpItao498ZJFNQl5KA43P4oRbsgHkRo_Poh3flPvs,14147
+facturx_api/_errors.py,sha256=52n8hpnilulJJHOE_XCtRUXmUXFQwIokczxI_wHnjSw,5236
+facturx_api/_results.py,sha256=rQ-qKeUEWUr8w1EmCo_B0YlOD5QMPlYD_BDa613tT_o,2570
+facturx_api/cli.py,sha256=qTG-tFNMXpZ-LbY0axck42ePZf73UplEh90LGnykhRA,5394
+facturx_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+facturx_api-0.1.0.dist-info/licenses/LICENSE,sha256=Nr37-wz5XGkBZfLdQhO2uol5FzQ4EL2WreYs7AcFb00,1064
+facturx_api-0.1.0.dist-info/METADATA,sha256=jE5PiFI_F9Wi0bNDih8WDwCTKiSxqJbKWvA1UxZiIIQ,8558
+facturx_api-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+facturx_api-0.1.0.dist-info/entry_points.txt,sha256=BEzu6AcvDzMCEx7p5gQeMOzd2Q-zGX9rpje4KV7OX8M,49
+facturx_api-0.1.0.dist-info/top_level.txt,sha256=jbHu_aMN1FAwK3fTTGyKuhtVPGrtdg0bIefO7GXL-Gg,12
+facturx_api-0.1.0.dist-info/RECORD,,

facturx_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

facturx_api-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+facturx = facturx_api.cli:main

facturx_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FacturX
+
+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.

facturx_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+facturx_api