codecell-germany/sevdesk-agent-skill

sevdesk-agent-cli

Wann verwenden

Verwenden Sie diese Fertigkeit, wenn Aufgaben den SevDesk-API-Zugriff von diesem Arbeitsbereich aus erfordern – insbesondere wenn ein Agent:

• den Geschäfts-/Buchhaltungsstatus über Nur-Lese-Endpunkte inspizieren muss,
• Kontakte, Rechnungen, Belege oder Transaktionen suchen muss, ohne rohe API-Filter improvisieren zu müssen,
• Kontakte, Angebote, Rechnungen und Belege über typisierte Workflows erstellen oder aktualisieren muss,
• Belege mit Banktransaktionen abgleichen und Buchungen vorbereiten oder ausführen muss,
• Schreibendpunkte schnell ausführen muss, während DELETE-Operationen explizit geschützt bleiben,
• eine Kontext-Momentaufnahme für spätere Agentenläufe erstellen muss.

Voraussetzungen

• Stellen Sie sicher, dass die CLI pro Maschine einmal global über PATH verfügbar ist:
  • Bevorzugt: npm install -g @codecell-germany/sevdesk-agent-skill
  • Codex-Bootstrap-Hilfe: npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent-skill install --force
  • Überprüfung: sevdesk-agent --help
• Wenn sevdesk-agent nach der Installation immer noch nicht gefunden wird:
  • Überprüfen Sie das npm globale Präfix: npm config get prefix
  • Fügen Sie <prefix>/bin bei Bedarf dem PATH der aktuellen Shell hinzu
• Temporärer Fallback ohne globale Installation:
  • npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent --help
• Für skill-fähige Agentenumgebungen installieren Sie das Skill-Paket explizit:
  • sevdesk-agent-skill install --force
• API-Token ist in der Umgebung verfügbar:
  • SEVDESK_API_TOKEN=<token>
• Optionale Umgebungsvariablen:
  • SEVDESK_BASE_URL (Standard: https://my.sevdesk.de/api/v1)
  • SEVDESK_USER_AGENT
• SEVDESK_ALLOW_WRITE=true (nur für DELETE-Operationen erforderlich, es sei denn, --allow-write wird verwendet)

Erstausführungserkennung

Führen Sie dies vor dem ersten echten Buchhaltungs-Workflow auf einem Rechner aus:

sevdesk-agent --help
sevdesk-agent doctor --json
sevdesk-agent read bookkeepingSystemVersion --output json

Behandeln Sie die Umgebung als nicht bereit, wenn einer der folgenden Punkte zutrifft:

• sevdesk-agent ist nicht über PATH verfügbar
• SEVDESK_API_TOKEN fehlt
• doctor meldet einen fehlgeschlagenen Check
• bookkeepingSystemVersion kann nicht erfolgreich gelesen werden

Wenn die Einrichtung unvollständig ist, installieren Sie zuerst das öffentliche Paket, überprüfen Sie den Token und fahren Sie erst dann mit read, find-* oder Schreib-Workflows fort.

Kern-Workflow

1. Operations-IDs ermitteln:
   • sevdesk-agent ops list --read-only
   • sevdesk-agent op-show <operationId>
   • sevdesk-agent ops-quirks
   • Stabile Parser-Ausgabe: sevdesk-agent ops-quirks --json-array
2. Zuerst Leseaufrufe ausführen:
   • sevdesk-agent read <operationId> --query key=value
   • sevdesk-agent read find-contact --query term="<name>" --output json (Alias für Top-Level-Suche nach Kontakten)
   • sevdesk-agent read resolve-billing-contact --query term="<name>" --output json (Alias für Hilfsbefehl)
   • sevdesk-agent read find-invoice --query term="<text>" --query deepScan=true --output json (Alias für Hilfsbefehl)
   • sevdesk-agent read find-transaction --query amount=119 --query booked=false --output json (Alias für Hilfsbefehl)
   • sevdesk-agent read match-transaction --query voucherId=<id> --output json (Alias für Hilfsbefehl)
   • Lokale Kontaktsuche-Hilfe: sevdesk-agent find-contact <term> --output json
   • Abrechnungshilfe: sevdesk-agent resolve-billing-contact <term> --output json
   • Rechnungstextsuche: sevdesk-agent find-invoice <term> --deep-scan --output json
   • Transaktionssuche: sevdesk-agent find-transaction "<text>" --amount <n> --booked false --output json
   • Beleg-zu-Transaktionsabgleich: sevdesk-agent match-transaction --voucher-id <id> --output json
   • Semantischer Transaktionsabgleich: sevdesk-agent transaction find-match --supplier "<name>" --amount <n> --date <yyyy-mm-dd> --direction expense --output json
   • Beleginspektion: sevdesk-agent voucher inspect --id <id> --output json
   • Standardmäßig werden Leseantworten für bekannte Live-API-Besonderheiten normalisiert
   • Shell-Zitierung: Parameter wie contact[id] sollten in Anführungszeichen gesetzt werden: --query 'contact[id]=123'
   • Rechnungsdatumsfilter (beobachtet): In unseren Tests funktioniert getInvoices mit startDate/endDate als Unix-Timestamps (Sekunden). ISO-Daten wie 2026-01-01 können leere Ergebnisse zurückgeben. Beispiel: sevdesk-agent read getInvoices --query startDate=1767225600 --query endDate=1769903999 --output json
   • Erstellen Sie ein vollständiges Referenzdokument für Leseoperationen: sevdesk-agent docs read-ops --output knowledge/READ_OPERATIONS.md
3. Für Schreibaufrufe:
   • POST / PUT / PATCH: sevdesk-agent write <operationId> ...
   • Ergonomische Entity-Bearbeitungen:
     • sevdesk-agent order edit --order-id <id> ... --verify
     • sevdesk-agent contact edit --contact-id <id> ... --verify
   • Mehrteilige Schreibvorgänge sind verfügbar mit --form-field key=value und --form-file file=/pfad/zu/datei
   • DELETE: sevdesk-agent write <operationId> --execute --confirm-execute yes --allow-write ...
   • Für createContact / createOrder wird standardmäßig eine lokale Preflight-Validierung ausgeführt
   • Für createInvoiceByFactory validiert der Preflight auch die Rechnungs-/Lieferdaten-Konsistenz (--auto-fix-delivery-date verfügbar)
   • Für voucherFactorySaveVoucher und bookVoucher validiert der lokale Preflight die risikoreichen Buchhaltungsfelder vor dem API-Aufruf
   • Fügen Sie --verify hinzu, um Nur-Lese-Post-Write-Prüfungen auszuführen (einschließlich createInvoiceByFactory, voucherFactorySaveVoucher und bookVoucher)
   • Für createContact-Workflows bevorzugen Sie --verify-contact (beinhaltet customerNumber-Abweichungsprüfungen; automatische Korrektur ist standardmäßig aktiviert und kann über --no-fix-contact deaktiviert werden)
4. Agenten-Übergabekontext speichern:
   • stdout (Standard): sevdesk-agent context snapshot
   • Optionaler Dateiexport: sevdesk-agent context snapshot --output .context/sevdesk-context-snapshot.json

Standard-Runbook: Kontakt + Angebot + PDF

1. Discovery:
   • sevdesk-agent ops list --read-only
   • sevdesk-agent op-show createContact
   • sevdesk-agent op-show createOrder
2. Kontakt finden/erstellen:
   • sevdesk-agent find-contact "<name oder customerNumber>" --output json
   • sevdesk-agent write createContact ... --verify-contact
3. Angebot erstellen:
   • sevdesk-agent write createOrder ... --verify
4. PDF-Export ohne Status-Nebeneffekt:
   • sevdesk-agent read orderGetPdf --path orderId=<id> --decode-pdf output/<datei>.pdf --suppress-content
   • preventSendBy=1 wird standardmäßig gesetzt (--no-safe-pdf deaktiviert das)
5. Übergabe:
   • sevdesk-agent context snapshot --include-default

Zusätzliche Rechnungshilfen

• Teilzahlung von bestehender Rechnung:
  • sevdesk-agent create-invoice-installment --from-invoice <id> --percent 70 --label "..." [--execute --verify]
• Rechnung für wiederkehrende Workflows klonen:
  • sevdesk-agent invoice clone --from <id> --date <...> --period <...> with selective position overrides
• Sichere Rechnungsersetzung, wenn generische Rechnungsmutation nicht verfügbar ist:
  • sevdesk-agent invoice recreate --from <id> --patch-file payloads/invoice.patch.json --verify
• Belegerfassung aus lokalem PDF:
  • sevdesk-agent create-voucher-from-pdf --file /absoluter/pfad/zu/beleg.pdf ... [--execute --verify]
• Belegbuchungs-Hilfen:
  • sevdesk-agent voucher inspect --id <id> --output json
  • sevdesk-agent voucher book-existing --voucher-id <id> --transaction-id <id> [--execute --verify]
  • sevdesk-agent book-voucher --voucher-id <id> --check-account-id <id> --amount <n> [--transaction-id <id>] [--execute --verify]
  • sevdesk-agent assign-voucher-to-transaction --voucher-id <id> --check-account-id <id> --transaction-id <id> --amount <n> [--execute --verify]
  • sevdesk-agent expense process-paid --file /absoluter/pfad/zu/beleg.pdf --transaction-id <id> ... [--execute --verify]
• Selbsttest und Befehlssynchronisation:
  • sevdesk-agent doctor --json

Schutzmaßnahmen

• Standardverhalten ist workflow-freundlich: POST/PUT/PATCH werden direkt ausgeführt; DELETE wird blockiert, es sei denn, Schutzflags sind gesetzt.
• Bevorzugen Sie in Produktions-Workflows zuerst Nur-Lese-Tests und Nur-Lese-Probes.
• Für *GetPdf-Endpunkte sind Antworten typischerweise JSON, eingeschlossen in data.objects (oft mit filename, mimetype und base64 content).
• Für orderGetPdf / invoiceGetPdf wendet die CLI jetzt standardmäßig preventSendBy=1 an (sicherer PDF-Modus).
• Verwenden Sie --decode-pdf <pfad> für die direkte PDF-Dateiausgabe ohne jq/base64.
• Mit --decode-pdf verwenden Sie --suppress-content (Standard), um große base64-Payloads aus der CLI-Ausgabe herauszuhalten.
• create-voucher-from-pdf, book-voucher und assign-voucher-to-transaction sind standardmäßig Trockenläufe; echte Schreibvorgänge erfolgen nur mit --execute.
• voucher book-existing und expense process-paid sind ebenfalls standardmäßig Trockenläufe; verwenden Sie --execute nur nach Prüfung der abgeleiteten Payload.
• order edit, contact edit und invoice recreate werden direkt wie normale PUT/POST-Abläufe ausgeführt; verwenden Sie --verify, um das Ergebnis sofort zu validieren.
• Wenn eine Schreibantwort oder eine integrierte Verifizierung ok: false zurückgibt, beendet sich die CLI jetzt mit einem von Null verschiedenen Shell-Status. Behandeln Sie dies in der Automatisierung nicht als Erfolg.
• Wenn der Server einen Nicht-JSON-Binär-Content-Type (pdf/xml/zip/csv) zurückgibt, gibt die CLI Metadaten (binary, bytes, contentType) anstelle von Rohbytes aus.
• Laufzeitrelevante Abfrage-Besonderheiten werden für ausgewählte Operationen erzwungen (z. B. erfordert contactCustomerNumberAvailabilityCheck zur Laufzeit customerNumber).
• Verwenden Sie op-show oder ops-quirks, um operationsspezifische Laufzeit-Besonderheiten zu sehen.
• ops-quirks --json gibt ein Objekt-Mapping zurück; für stabiles Array-Parsing verwenden Sie ops-quirks --json-array.
• Wenn Sie Rechnungsmutation-Hilfe benötigen und updateInvoice fehlt, führen Sie sevdesk-agent docs invoice-edit aus.
• Wenn Sie Rechnungsinhalte ändern müssen, bevorzugen Sie sevdesk-agent invoice recreate --from <id> ... gegenüber dem Erraten einer rohen updateInvoice-Payload.
• Für die Nummerierungs-/Finalisierungssequenz nach der Rechnungserstellung führen Sie sevdesk-agent docs invoice-finalize aus.

Referenzen

• Befehlsspickzettel: references/command-cheatsheet.md
• Angebots-/Bestell-Schreibnotizen (Live-Verhalten): knowledge/SEVDESK_ORDER_WRITE_LEARNINGS.md