Sandbox: KI-Agenten an einer Kopie der Buchhaltung testen

So richten Sie die Sandbox ein

• In den Einstellungen der Buchhaltung (im EÜR-Modul: in den EÜR-Einstellungen) die Karte „Sandbox (Testumgebung)“ öffnen und „Sandbox einrichten“ wählen. Dafür brauchen Sie Bearbeiterrechte an der echten Gesellschaft und bestätigen mit dem zweiten Faktor.
• Die Software legt eine Kopie der Gesellschaft mit ihren Buchungen an. Bei großen Beständen dauert das einige Minuten; die Karte zeigt, wie viele Buchungen schon kopiert sind. Danach steht dort „Sandbox bereit“ mit dem Stand der Kopie.
• „Sandbox öffnen“ wechselt in den Zwilling; ein kleiner Hinweis zeigt, dass Sie in der Sandbox arbeiten, „Zur echten Gesellschaft“ führt zurück.
• In der Sandbox im Bereich „KI-Agent & API“ einen Schlüssel anlegen. Die Seite sagt dort ausdrücklich: „Diese Schlüssel gelten nur für die Sandbox.“ Rechte, Laufzeit und zweiter Faktor funktionieren wie bei jedem anderen Schlüssel.
• Den Sandbox-Schlüssel in Ihrem KI-Programm unter einem eigenen Servernamen eintragen, etwa buchhaltung-test, damit echte und Test-Verbindung nie verwechselt werden.

Woran Agent und Programm die Sandbox erkennen

Jede Antwort an einen Sandbox-Schlüssel trägt den Kopf X-Jab-Sandbox; GET /v1/entity und GET /v1/ nennen zusätzlich die Sandbox-Felder:

curl -i -H "Authorization: Bearer $JAB_SANDBOX_KEY" \
  "https://api.jahresabschluss.io/functions/v1/bookkeeping-api/v1/entity"

HTTP/2 200
x-jab-sandbox: true
…
{
  "entity": { … },
  "sandbox": true,
  "sandbox_quelle_entity_id": "…",
  "sandbox_stand": "bereit",
  "sandbox_kopiert_am": "…"
}

Über den MCP-Server liefert get_entity dieselben Felder, und jede Werkzeugantwort aus der Sandbox enthält einen zusätzlichen Hinweis, dass die echten Bücher unberührt bleiben. Die Anweisung des Servers verlangt außerdem, dass der Agent Ihnen bei jeder Buchung sagt, dass sie nur in der Sandbox steht. Ein eigenes Programm sollte vor jedem Testlauf X-Jab-Sandbox prüfen.

Was in der Sandbox geht – und was gesperrt ist

Die Sperre greift an mehreren Stellen: Die API lehnt jeden Aufruf, der nach außen wirkt, vor der eigentlichen Verarbeitung ab, und die Funktionen dahinter prüfen selbst noch einmal. Kann die Software nicht feststellen, ob ein Schlüssel zur Sandbox gehört, führt sie nichts aus (503 sandbox_nicht_pruefbar) – im Zweifel gesperrt.

Ein Testlauf, Schritt für Schritt

Ein Auftrag im Chat: „Wir testen den Monatsimport in der Sandbox. Importiere die Buchungen aus der Datei, erst als Probelauf, und versuche danach, die Rechnung RE-1007 zu versenden.“ Der Agent geht so vor:

• get_entity: Er bestätigt sandbox: true und nennt Ihnen den Stand der Kopie (sandbox_kopiert_am).
• import_journal_batch mit dry_run: true: Er zeigt die Buchungszeilen, ihre Wirkung auf die Konten und welche Zeilen als Dublette übersprungen würden.
• import_journal_batch ohne dry_run: Der Stapel wird im Zwilling gebucht; list_journal_batches zeigt seine stapel_id.
• send_outgoing_invoice (mit einem Sandbox-Schlüssel, der das Recht send hat): Die Antwort ist 409 mit dem Code sandbox_ausgang_gesperrt – genau das wollten Sie sehen.
• storno_journal_batch: Er nimmt den Teststapel in einer Transaktion zurück, damit Sie den nächsten Lauf sauber beginnen; alternativ setzen Sie die Sandbox zurück.

Zurücksetzen und entfernen

• Zurücksetzen füllt die Sandbox mit dem heutigen Stand der echten Gesellschaft neu; alles, was Sie in der Sandbox gebucht haben, entfällt. Die API-Schlüssel der Sandbox bleiben erhalten, Ihr KI-Programm läuft ohne Umstellung weiter.
• Während Einrichtung oder Zurücksetzen antwortet die API mit 409 sandbox_wird_vorbereitet und dem Kopf Retry-After: 60; ist die Kopie gescheitert, mit 409 sandbox_fehler – dann setzen Sie die Sandbox in den Einstellungen zurück.
• Die Kopie hat einen Stichtag: Buchungen der echten Gesellschaft bis zum Beginn der Kopie kommen mit, spätere erst beim nächsten Zurücksetzen.
• Entfernen löscht die Sandbox und alles, was darin gebucht wurde. Die echte Gesellschaft bleibt unverändert; mit der Sandbox entfallen ihre API-Schlüssel.

Wofür sich die Sandbox eignet

• Ein neues KI-Programm oder Modell ausprobieren, bevor es einen Schlüssel für die echten Bücher bekommt.
• Eigene Anweisungen und Freigabe-Einstellungen prüfen: Fragt Ihr Programm wirklich vor jedem schreibenden Aufruf?
• Stapelimporte und Anbindungen eigener Software mit realistischen Daten durchspielen, einschließlich Fehlerfällen wie 409 und 422.
• Mitarbeitende einweisen, ohne dass ein Fehler in den echten Büchern landet – ein Baustein für die KI-Kompetenz nach Art. 4 der KI-Verordnung.

Grenzen

• Derzeit keine Sandbox für Gesellschaften mit Jahresabschluss-Daten: Liegen schon Saldenlisten für den Jahresabschluss, Abschlussbuchungen, Rechnungsabgrenzungen, Rückstellungen, Wertberichtigungen, Sammelposten, Anlagenabgänge oder Sonderbilanzen vor, lehnt die Software die Einrichtung mit dem Hinweis ab, dass die Sandbox für solche Gesellschaften noch nicht zur Verfügung steht.
• Nicht mitkopiert werden unter anderem ELSTER-Übermittlungen und Zertifikate, API-Schlüssel und Protokolle, Anbindungen, KI-Auslesungen und Kontoauszugsdateien.
• Ein Sandbox-Schlüssel kann keine Webhooks abonnieren; Anbindungen über Webhooks testen Sie mit einem Schlüssel der echten Gesellschaft, der nur die Rechte read und webhooks hat.
• Mitarbeitende, deren Zugriff auf bestimmte Gesellschaften beschränkt ist, sehen keine Sandbox.
• Ein gelungener Testlauf beweist nicht, dass derselbe Lauf in den echten Büchern gelingt – der Stand kann sich seit der Kopie geändert haben.

Häufige Fragen

Kann ein Sandbox-Schlüssel die echten Bücher verändern?

Nein. Ein Schlüssel wird in der Sandbox angelegt und gilt nur für sie; die Gesellschaft ergibt sich aus dem Schlüssel. Jede Antwort trägt den Kopf X-Jab-Sandbox: true.

Kann ich in der Sandbox eine Umsatzsteuer-Voranmeldung testen?

Prüfen und Vorbereiten ja: check_tax_filing lässt die Meldung amtlich prüfen, ohne dass etwas übermittelt wird, und prepare_tax_filing friert Werte und Prüfwert ein. Beide nennen das Hindernis sandbox. Eine Übermittlung ist aus der Sandbox gesperrt.

Warum kann ich für meine Gesellschaft keine Sandbox einrichten?

Meist, weil schon Jahresabschluss-Daten vorliegen, etwa Saldenlisten, Abschlussbuchungen oder Rückstellungen – dafür gibt es die Sandbox derzeit noch nicht. Außerdem braucht die Einrichtung Bearbeiterrechte und den zweiten Faktor.

Was passiert mit meinen Sandbox-Schlüsseln beim Zurücksetzen?

Sie bleiben erhalten; nur die Buchungen werden durch den aktuellen Stand der echten Gesellschaft ersetzt. Erst das Entfernen der Sandbox löscht auch ihre Schlüssel.

Woran erkennt mein Programm, dass es in der Sandbox arbeitet?

Am Kopf X-Jab-Sandbox: true jeder Antwort und an den Feldern sandbox, sandbox_quelle_entity_id, sandbox_stand und sandbox_kopiert_am in GET /v1/entity und GET /v1/. Über den MCP-Server liefert get_entity dieselben Angaben.

Kostet die Sandbox extra?

Nein, sie gehört zur Buchhaltung bzw. zur EÜR. Weil die KI-Belegerkennung in der Sandbox ausgeschaltet ist, belastet sie auch nicht Ihr Kontingent der KI-erkannten Belege.