API-Referenz

Die REST-API von xTool wird für die Integration genutzt: Erstellen und Verwalten von Dokumenten, Validieren und Konvertieren von Formaten, Auflisten von Transaktionen usw. Die Basis-URL wird über Ihre Umgebung bereitgestellt (z. B. durch Ihren Administrator). Siehe Setup und API-Schlüssel und Logs.

Moderne API-Referenz (Scalar) Klassisches Swagger

Die interaktive Dokumentation (Scalar oder Swagger) ermöglicht das Durchsuchen aller Endpoints, das Senden von Testanfragen und das Anzeigen von Request-/Response-Schemas. Im Folgenden eine kurze Einführung: API-Versionierung, Authentifizierung und allgemeine Konventionen.

Versionierung

v1 — Unterstützt. Siehe Migration für den Wechsel zu v2.
v2 — Aktuell. Verwenden Sie v2 für alle neuen Anwendungen. Endpoints liegen unter /api/v2/.

Authentifizierung

Senden Sie Ihren API-Schlüssel mit jeder Anfrage. Der Schlüssel ist an eine Organisation und einen Satz erlaubter API-Methoden gebunden. Übliche Übergabe:

Header: x-api-key: YOUR_API_KEY

Aktive Organisation (X-Active-Org-Id). Optionaler Header mit der Organisations-UUID. Legt fest, im Kontext welcher Organisation die Anfrage ausgeführt wird: Dokumente, Transaktionen, Organisationsliste usw. beziehen sich auf die aktive Organisation. Ohne Header ist die aktive Organisation diejenige, der der API-Schlüssel zugeordnet ist. Wenn der Header gesetzt ist, wird diese Organisation als aktiv verwendet; sie muss die Organisation des Schlüssels oder eine Nachfolger-Organisation in der Hierarchie sein (ein Schlüssel einer übergeordneten Organisation kann im Namen einer untergeordneten Organisation agieren). Format: X-Active-Org-Id: <organisation_uuid>.

Verwenden Sie die in Ihrer Installation vorgesehene Methode. Siehe API-Schlüssel und Logs.

Konventionen

Request/Response — Die meisten Endpoints nutzen JSON. Dokumentinhalte können XML oder PDF sein (z. B. XML abrufen, PDF abrufen, XML hochladen).
Statuscodes — 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation Error, 500 Server Error.
Pagination — Listen-Endpoints unterstützen limit und offset.
Sortierung — sort_by und sort_order wo anwendbar.
Suche — Query-Parameter search wo anwendbar.
IDs — Ressourcen verwenden UUID (z. B. document_id, organisation_id, transaction_id).

Fehlerbehandlung

Bei 4xx- oder 5xx-Antworten enthält der Body eine Fehlerstruktur. Typischerweise ein detail-Feld mit einer Meldung. Bei 422 Validation Error kann die Antwort eine Liste von Validierungsfehlern enthalten (z. B. Ort und Meldung). Nutzen Sie diese zur Korrektur der Anfrage und zum erneuten Senden.

Wichtigste API-Gruppen

Bereich	Endpoints (Beispiele)	Version
Auth	aktueller Kontext (Organisation, Benutzer)	v2
Documents	list, get, get model, get xml, upload model/xml, update model/xml, send, delete	v2
Format	transform (Modell↔XML, Modell→PDF, XML→Modell, XML→PDF), validate (Modell, XML), detect XML, convert (Modell, XML)	v2
Transactions	list, get (mit optionalem status_log)	v2
Organisations	list	v2
Peppol Lookup	check-existence, business-card, document-types, endpoints	v2
PDF	merge (mehrere PDFs in eine Datei)	v2
v1	documents, invoice convert, PDF — unterstützt	v1

Übergang von v1 auf v2 siehe Migration.