Best Practices für Agenten

Dieser Leitfaden beschreibt die empfohlene Vorgehensweise für KI-Agenten, die fiskaly-APIs integrieren — von der Entdeckung bis zur Produktionsbereitstellung. Er hebt häufige Fehler und länderspezifische Besonderheiten hervor, die bei automatisierten Integrationen zu Problemen führen.

Empfohlener Integrationsablauf

1. Entdecken

   Rufen Sie /products.json ab, um das richtige Produkt für Ihr Zielland zu identifizieren. Prüfen Sie apiArchitecture, um festzustellen, ob Sie mit einer spezialisierten oder unified API arbeiten.

2. Authentifizieren

   Senden Sie POST /auth mit dem vom Benutzer bereitgestellten API-Schlüssel und -Geheimnis. Cachen Sie das Zugriffstoken (24h TTL) — authentifizieren Sie sich nicht bei jeder Anfrage erneut.

3. Provisionieren

   Erstellen Sie die Signing-Infrastruktur für das Zielland: TSS + Client (DE), Steuerpflichtiger + Standort + System (FR/IT) oder Äquivalent. Prüfen Sie /human-interventions.json für Schritte, die menschliche Eingaben erfordern.

4. Transaktionen durchführen

   Signieren Sie Transaktionen über den entsprechenden Endpunkt. SIGN DE verwendet ein Zwei-Aufruf-PUT-Muster (ACTIVE → FINISHED). SIGN FR und SIGN IT verwenden ein Zwei-Aufruf-POST-Muster (Intention → Transaction).

Automatisierbare vs. menschlich erforderliche Aktionen

Nicht jeder Schritt in einer fiskaly-Integration kann automatisiert werden. Prüfen Sie vor dem Aufbau eines Agenten-Workflows, welche Aktionen einen Menschen erfordern:

Kategorie	Anzahl	Beispiele
Vollständig automatisierbar	11	Authentifizierung, TSS-Erstellung, Transaktionssignierung
Teilweise automatisierbar	2	Eingabe von Steuerpflichtigendaten (Mensch liefert Steuer-ID, Agent führt API-Aufruf durch)
Erfordert Menschen	7	Kontoerstellung, API-Schlüsselerstellung, Go-live

Gestalten Sie Ihren Agenten so, dass er bei menschlich erforderlichen Schritten pausiert und den Benutzer auffordert, und dann die Automatisierung fortsetzt. Weitere Details finden Sie im vollständigen Human Intervention Registry.

💡Tip

Die maschinenlesbare Version unter /human-interventions.json kann zur Laufzeit abgefragt werden, um den Workflow Ihres Agenten dynamisch anzupassen.

Häufige Anti-Muster

Basis-URLs hartcodieren

Basis-URLs unterscheiden sich zwischen TEST- und LIVE-Umgebungen sowie zwischen spezialisierten und unified APIs. Rufen Sie sie immer aus /products.json ab, anstatt sie hartzucodieren.

// Nicht so machen
const BASE_URL = "https://kassensichv-middleware.fiskaly.com/api/v2";

// So machen — aus products.json lesen
const product = products.find(p => p.id === "sign-de");
const baseUrl = product.baseUrls.test;

Pro Anfrage neu authentifizieren

Das Zugriffstoken ist 24 Stunden gültig. Cachen Sie es und authentifizieren Sie sich nur bei 401-Antworten erneut. Eine Authentifizierung pro Anfrage verschwendet Zeit und kann Rate-Limits auslösen.

Die TEST-Umgebung überspringen

Entwickeln und testen Sie immer zunächst gegen die TEST-Umgebung (Sandbox). TEST ist kostenlos, verwendet die gleiche API-Oberfläche wie LIVE und ermöglicht Iterationen ohne Auswirkungen auf echte fiskalische Daten.

UUIDs wiederverwenden

Bei spezialisierten APIs (SIGN DE, SIGN AT, SIGN ES) sind Ressourcen-IDs client-generierte UUIDs. Generieren Sie immer frische UUIDs — das Wiederverwenden einer UUID führt zu einem 409 Conflict.

Idempotenz-Schlüssel ignorieren

Bei unified APIs (SIGN FR, SIGN IT) erfordern POST- und PATCH-Anfragen einen X-Idempotency-Key-Header. Generieren Sie eine neue UUID für jede einzigartige Operation. Wiederholungsversuche derselben Operation sollten denselben Schlüssel verwenden.

Exporte synchron abfragen

DSFinV-K und andere Export-Operationen sind asynchron. Lösen Sie den Export aus, dann fragen Sie den Status ab — blockieren Sie nicht auf die erste Anfrage.

Länderspezifische Besonderheiten

Deutschland (SIGN DE)

⚠️Admin-PIN erforderlich

Die TSS-Initialisierung erfordert das Setzen eines Admin-PINs über PATCH /tss/{id}, bevor der Status auf INITIALIZED geändert wird. Der PIN muss sicher gespeichert werden — dessen Verlust erfordert einen TSS-Austausch.

• TSS-Zustandsmaschine: UNINITIALIZED → INITIALIZED → DISABLED
• Client-generierte UUIDs für alle Ressourcen-IDs
• Transaktionen verwenden ein Revisions-Modell: Revision 1 (ACTIVE) → Revision 2 (FINISHED)
• DSFinV-K-Export ist für Audits gesetzlich vorgeschrieben

Frankreich (SIGN FR)

• Erfordert eine Organisationshierarchie: Organization GROUP → Organization UNIT → Subject → Taxpayer → Location → System → Record
• Die Erstellung eines Steuerpflichtigen benötigt eine echte SIREN-Nummer (menschlich bereitgestellt)
• Zwei-Aufruf-Record-Muster: Intention (type: INTENTION) → Transaction (type: TRANSACTION)
• Pflichtliche Header bei jeder Anfrage: X-Api-Version, X-Idempotency-Key, X-Scope-Identifier

Italien (SIGN IT)

• Gleiche unified-API-Architektur wie Frankreich
• Steuerpflichtige benötigen Agenzia delle Entrate (AdE)-Anmeldedaten — diese werden von Menschen bereitgestellt
• Unterstützt Lotteria degli Scontrini (Kassenbon-Lotterie) — fügen Sie lottery_code in Records ein, wenn der Kunde einen bereitstellt
• Echtzeit-Reporting an AdE bedeutet, dass Transaktionssignierung ohne Idempotenz-Schlüssel nicht wiederhol-sicher ist

Österreich (SIGN AT)

• RKSV-Regulierung mit FinanzOnline-Integration
• Separate Basis-URL: rksv-middleware.fiskaly.com/api/v1
• DEP (Datenerfassungsprotokoll)-Export für Audit-Trail

Spanien (SIGN ES)

• TicketBAI- und Verifactu-Regulierungen
• XML-basierte Rechnungssignierung und -übermittlung (nicht JSON wie bei anderen Produkten)
• Regionale Unterschiede zwischen autonomen Gemeinschaften

Quickstart-Skripte

End-to-End-Quickstart-Skripte sind für automatisierte Tests verfügbar:

• scripts/sign-de-quickstart.mjs — Vollständiger SIGN DE-Ablauf: Authentifizierung → TSS → Client → Transaktion
• scripts/sign-fr-quickstart.mjs — Vollständiger SIGN FR-Ablauf: Authentifizierung → Org → Steuerpflichtiger → Standort → System → Record

Diese Skripte demonstrieren den vollständigen Happy Path und können als Referenzimplementierungen für agenten-basierte Integrationen dienen.