codecell-germany/sevdesk-agent-skill

sevdesk-agent-cli

使用タイミング

次のタスクがsevdesk APIへのアクセスを伴う場合にこのスキルを使用します。特に、エージェントが以下の操作を行う必要がある場合に推奨します。

• 読み取り専用エンドポイントを介してビジネス/会計の状態を確認する
• 生のAPIフィルターをアドホックに構築せずに、連絡先、請求書、証憑、取引を検索する
• 型付けされたワークフローを通じて連絡先、見積書、請求書、証憑を作成・更新する
• 証憑を銀行取引とマッチングし、予約の準備または実行を行う
• DELETE操作を明示的にガードしながら書き込みエンドポイントを迅速に実行する
• 後続のエージェント実行のためにコンテキストスナップショットを生成する

前提条件

• CLIがマシンごとに一度、PATH上でグローバルに利用可能であることを確認します。
  • 推奨方法: npm install -g @codecell-germany/sevdesk-agent-skill
  • Codexブートストラップヘルパー: npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent-skill install --force
  • 確認コマンド: sevdesk-agent --help
• インストール後もsevdesk-agentが見つからない場合:
  • npmのグローバルプレフィックスを確認: npm config get prefix
  • 必要に応じて<prefix>/binを現在のシェルのPATHに追加します
• グローバルインストールしない場合の一時的な代替方法:
  • npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent --help
• AIエージェント環境でスキルに対応している場合は、スキルペイロードを明示的にインストールします:
  • sevdesk-agent-skill install --force
• APIトークンが環境変数に設定されている必要があります:
  • SEVDESK_API_TOKEN=<token>
• オプションの環境変数:
  • SEVDESK_BASE_URL (デフォルト: https://my.sevdesk.de/api/v1)
  • SEVDESK_USER_AGENT
• SEVDESK_ALLOW_WRITE=true (DELETE操作にのみ必要。または--allow-writeを使用)

初回実行の検出

マシン上で最初の実際の簿記ワークフローを実行する前に、以下を実行します:

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

次のいずれかが当てはまる場合、環境は準備ができていないと見なします:

• sevdesk-agentがPATH上で利用できない
• SEVDESK_API_TOKENが設定されていない
• doctorでチェックが失敗したと報告される
• bookkeepingSystemVersionが正常に読み取れない

セットアップが不完全な場合は、まず公開パッケージをインストールし、トークンを確認してから、read、find-*、または書き込みワークフローに進みます。

コアワークフロー

1. 操作IDを発見:
   • sevdesk-agent ops list --read-only
   • sevdesk-agent op-show <operationId>
   • sevdesk-agent ops-quirks
   • 安定したパーサー出力: sevdesk-agent ops-quirks --json-array
2. 最初に読み取り呼び出しを実行:
   • sevdesk-agent read <operationId> --query key=value
   • sevdesk-agent read find-contact --query term="<name>" --output json (最上位のfind-contactへのエイリアス)
   • sevdesk-agent read resolve-billing-contact --query term="<name>" --output json (ヘルパーコマンドへのエイリアス)
   • sevdesk-agent read find-invoice --query term="<text>" --query deepScan=true --output json (ヘルパーコマンドへのエイリアス)
   • sevdesk-agent read find-transaction --query amount=119 --query booked=false --output json (ヘルパーコマンドへのエイリアス)
   • sevdesk-agent read match-transaction --query voucherId=<id> --output json (ヘルパーコマンドへのエイリアス)
   • ローカル連絡先検索ヘルパー: sevdesk-agent find-contact <term> --output json
   • 請求先ヘルパー: sevdesk-agent resolve-billing-contact <term> --output json
   • 請求書テキスト検索: sevdesk-agent find-invoice <term> --deep-scan --output json
   • 取引検索: sevdesk-agent find-transaction "<text>" --amount <n> --booked false --output json
   • 証憑-取引マッチング: sevdesk-agent match-transaction --voucher-id <id> --output json
   • 意味論的取引マッチング: sevdesk-agent transaction find-match --supplier "<name>" --amount <n> --date <yyyy-mm-dd> --direction expense --output json
   • 証憑検査: sevdesk-agent voucher inspect --id <id> --output json
   • デフォルトでは、読み取り応答は既知のライブAPIの癖に対して正規化されます
   • シェル引用符: contact[id]のようなパラメータは引用符で囲む必要があります: --query 'contact[id]=123'
   • 請求書日付フィルター (観察結果): テストでは、getInvoicesはstartDate/endDateをUnixタイムスタンプ(秒)で動作します。ISO日付(例: 2026-01-01)は空の結果を返す可能性があります。 例: sevdesk-agent read getInvoices --query startDate=1767225600 --query endDate=1769903999 --output json
   • 完全な読み取り操作リファレンスドキュメントを生成: sevdesk-agent docs read-ops --output knowledge/READ_OPERATIONS.md
3. 書き込み呼び出しの場合:
   • POST / PUT / PATCH: sevdesk-agent write <operationId> ...
   • 人間工学に基づいたエンティティ編集:
     • sevdesk-agent order edit --order-id <id> ... --verify
     • sevdesk-agent contact edit --contact-id <id> ... --verify
   • マルチパート書き込みは --form-field key=value および --form-file file=/path/to/file で利用可能
   • DELETE: sevdesk-agent write <operationId> --execute --confirm-execute yes --allow-write ...
   • createContact / createOrder では、デフォルトでローカルの事前検証が実行されます
   • createInvoiceByFactory では、事前検証で請求書/納品日の整合性も検証します (--auto-fix-delivery-date が利用可能)
   • voucherFactorySaveVoucher および bookVoucher では、ローカルの事前検証でAPI呼び出し前に高リスクな会計フィールドを検証します
   • --verify を追加して、書き込み後の読み取り専用チェックを実行します (createInvoiceByFactory、voucherFactorySaveVoucher、bookVoucher を含む)
   • createContactワークフローでは、--verify-contact を推奨します (customerNumberの不一致チェックを含む。自動修正はデフォルトで有効で、--no-fix-contact で無効化可能)
4. エージェントハンドオフコンテキストを永続化:
   • stdout (デフォルト): sevdesk-agent context snapshot
   • オプションのファイルエクスポート: sevdesk-agent context snapshot --output .context/sevdesk-context-snapshot.json

標準ランブック: Kontakt + Angebot + PDF

1. 発見:
   • sevdesk-agent ops list --read-only
   • sevdesk-agent op-show createContact
   • sevdesk-agent op-show createOrder
2. 連絡先の検索/作成:
   • sevdesk-agent find-contact "<name or customerNumber>" --output json
   • sevdesk-agent write createContact ... --verify-contact
3. 見積書の作成:
   • sevdesk-agent write createOrder ... --verify
4. ステータス副作用なしのPDFエクスポート:
   • sevdesk-agent read orderGetPdf --path orderId=<id> --decode-pdf output/<file>.pdf --suppress-content
   • preventSendBy=1 はデフォルトで設定されます (--no-safe-pdf で無効化)
5. ハンドオフ:
   • sevdesk-agent context snapshot --include-default

追加の請求書ヘルパー

• 既存の請求書からの分割払い:
  • sevdesk-agent create-invoice-installment --from-invoice <id> --percent 70 --label "..." [--execute --verify]
• 定期ワークフローのための請求書の複製:
  • sevdesk-agent invoice clone --from <id> --date <...> --period <...> with selective position overrides
• 一般的な請求書の変更が利用できない場合の安全な請求書置き換え:
  • sevdesk-agent invoice recreate --from <id> --patch-file payloads/invoice.patch.json --verify
• ローカルPDFからの証憑取り込み:
  • sevdesk-agent create-voucher-from-pdf --file /absolute/path/to/beleg.pdf ... [--execute --verify]
• 証憑予約ヘルパー:
  • 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 /absolute/path/to/beleg.pdf --transaction-id <id> ... [--execute --verify]
• セルフチェックとコマンド同期:
  • sevdesk-agent doctor --json

ガードレール

• デフォルトの動作はワークフローに優しい: POST/PUT/PATCH は直接実行されます。DELETE はガードフラグが設定されていない限りブロックされます。
• 本番ワークフローでは、最初に読み取り専用テストと読み取り専用プローブを優先します。
• *GetPdf エンドポイントの場合、応答は通常 data.objects にラップされたJSONです (多くの場合、filename、mimetype、base64 content を含む)。
• orderGetPdf / invoiceGetPdf では、CLIはデフォルトで preventSendBy=1 を適用します (安全なPDFモード)。
• jq / base64 を使用せずに直接PDFファイル出力するには --decode-pdf <path> を使用します。
• --decode-pdf では、--suppress-content (デフォルト) を使用して、大きなbase64ペイロードがCLI出力に含まれないようにします。
• create-voucher-from-pdf、book-voucher、assign-voucher-to-transaction はデフォルトでドライランです。実際の書き込みは --execute でのみ行われます。
• voucher book-existing と expense process-paid もデフォルトでドライランです。派生ペイロードを確認した後にのみ --execute を使用します。
• order edit、contact edit、invoice recreate は通常の PUT/POST フローと同様に直接実行されます。--verify を使用して結果を即座に検証します。
• 書き込み応答または組み込み検証が ok: false を返した場合、CLIは非ゼロのシェルステータスで終了します。自動化において成功として扱わないでください。
• サーバーが非JSONのバイナリコンテンツタイプ (pdf/xml/zip/csv) を返した場合、CLIは生のバイトの代わりにメタデータ (binary、bytes、contentType) を出力します。
• 実行時に必要なクエリの癖は、選択された操作 (例: contactCustomerNumberAvailabilityCheck は実行時に customerNumber が必要) に対して適用されます。
• 操作固有の実行時の癖を確認するには、op-show または ops-quirks を使用します。
• ops-quirks --json はオブジェクトマッピングを返します。安定した配列解析には ops-quirks --json-array を使用します。
• 請求書の変更方法についてのガイダンスが必要で、updateInvoice が利用できない場合は、sevdesk-agent docs invoice-edit を実行します。
• 請求書の内容を変更する必要がある場合は、生の updateInvoice ペイロードを推測するよりも、sevdesk-agent invoice recreate --from <id> ... を推奨します。
• 請求書作成後の番号付け/確定シーケンスについては、sevdesk-agent docs invoice-finalize を実行します。

参照

• コマンドチートシート: references/command-cheatsheet.md
• オファー/注文書き込みに関する注意事項 (ライブ動作): knowledge/SEVDESK_ORDER_WRITE_LEARNINGS.md