sevdesk-agent-cli

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
• 스킬 인식 에이전트 환경의 경우, 스킬 페이로드를 명시적으로 설치:
  • 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 타임스탬프(초)로 처리합니다. 2026-01-01과 같은 ISO 날짜는 빈 결과를 반환할 수 있습니다. 예시: 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

표준 실행 가이드: 연락처 + 견적 + 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 모드).
• --decode-pdf <path>를 사용하면 jq/base64 없이 직접 PDF 파일 출력이 가능합니다.
• --decode-pdf와 함께 --suppress-content(기본값)를 사용하면 큰 base64 페이로드가 CLI 출력에 포함되지 않습니다.
• create-voucher-from-pdf, book-voucher 및 assign-voucher-to-transaction은 기본적으로 dry-run 모드입니다. 실제 쓰기는 --execute와 함께만 수행됩니다.
• voucher book-existing 및 expense process-paid도 기본적으로 dry-run 모드입니다. 파생된 페이로드를 확인한 후에만 --execute를 사용하세요.
• order edit, contact edit 및 invoice recreate는 일반 PUT/POST 흐름처럼 직접 실행됩니다. --verify를 사용하여 결과를 즉시 검증하세요.
• 쓰기 응답 또는 내장 검증이 ok: false를 반환하면, CLI는 이제 0이 아닌 셸 상태로 종료됩니다. 자동화에서 이를 성공으로 처리하지 마십시오.
• 서버가 비-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