codecell-germany/sevdesk-agent-skill

sevdesk-agent-cli

Quando usar

Use esta skill quando as tarefas envolvem acesso à API Sevdesk a partir deste espaço de trabalho, especialmente quando um agente precisar:

• inspecionar o estado comercial/contábil por meio de endpoints somente leitura,
• pesquisar contatos, faturas, vouchers ou transações sem improvisar filtros brutos da API,
• criar ou atualizar contatos, orçamentos, faturas e vouchers por meio de fluxos de trabalho tipados,
• conciliar vouchers contra transações bancárias e preparar ou executar lançamentos contábeis,
• executar endpoints de gravação rapidamente, mantendo operações DELETE explicitamente protegidas,
• produzir um instantâneo de contexto para execuções posteriores do agente.

Pré-condições

• Garanta que o CLI esteja globalmente disponível no PATH uma vez por máquina:
  • preferido: npm install -g @codecell-germany/sevdesk-agent-skill
  • auxiliar de bootstrap para Codex: npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent-skill install --force
  • verificar: sevdesk-agent --help
• Se sevdesk-agent ainda não for encontrado após a instalação:
  • verifique o prefixo global do npm: npm config get prefix
  • adicione <prefix>/bin ao PATH do shell atual se necessário
• Fallback temporário sem instalação global:
  • npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent --help
• Para ambientes de agente com suporte a skill, instale o payload da skill explicitamente:
  • sevdesk-agent-skill install --force
• Token da API disponível em env:
  • SEVDESK_API_TOKEN=<token>
• Env opcionais:
  • SEVDESK_BASE_URL (padrão https://my.sevdesk.de/api/v1)
  • SEVDESK_USER_AGENT
• SEVDESK_ALLOW_WRITE=true (necessário apenas para operações DELETE, a menos que --allow-write seja usado)

Detecção de primeira execução

Execute estes comandos antes do primeiro fluxo de trabalho real de contabilidade em uma máquina:

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

Trate o ambiente como não pronto se qualquer um destes for verdadeiro:

• sevdesk-agent não está disponível no PATH
• SEVDESK_API_TOKEN está ausente
• doctor relata uma verificação falha
• bookkeepingSystemVersion não pode ser lido com sucesso

Se a configuração estiver incompleta, instale o pacote público primeiro, verifique o token e só então prossiga para fluxos de read, find-* ou gravação.

Fluxo de trabalho principal

1. Descobrir IDs de operação:
   • sevdesk-agent ops list --read-only
   • sevdesk-agent op-show <operationId>
   • sevdesk-agent ops-quirks
   • saída estável do parser: sevdesk-agent ops-quirks --json-array
2. Executar chamadas de leitura primeiro:
   • sevdesk-agent read <operationId> --query key=value
   • sevdesk-agent read find-contact --query term="<nome>" --output json (atalho para find-contact de nível superior)
   • sevdesk-agent read resolve-billing-contact --query term="<nome>" --output json (atalho para comando auxiliar)
   • sevdesk-agent read find-invoice --query term="<texto>" --query deepScan=true --output json (atalho para comando auxiliar)
   • sevdesk-agent read find-transaction --query amount=119 --query booked=false --output json (atalho para comando auxiliar)
   • sevdesk-agent read match-transaction --query voucherId=<id> --output json (atalho para comando auxiliar)
   • auxiliar de pesquisa local de contatos: sevdesk-agent find-contact <termo> --output json
   • auxiliar de faturamento: sevdesk-agent resolve-billing-contact <termo> --output json
   • pesquisa textual de faturas: sevdesk-agent find-invoice <termo> --deep-scan --output json
   • pesquisa de transações: sevdesk-agent find-transaction "<texto>" --amount <n> --booked false --output json
   • conciliação voucher-transação: sevdesk-agent match-transaction --voucher-id <id> --output json
   • conciliação semântica de transações: sevdesk-agent transaction find-match --supplier "<nome>" --amount <n> --date <aaaa-mm-dd> --direction expense --output json
   • inspeção de voucher: sevdesk-agent voucher inspect --id <id> --output json
   • por padrão, as respostas de leitura são normalizadas para peculiaridades conhecidas da API ativa
   • Citação no shell: parâmetros como contact[id] devem ser citados: --query 'contact[id]=123'
   • Filtros de data de fatura (observados): em nossos testes, getInvoices funciona com startDate/endDate como timestamps Unix (segundos). Datas ISO como 2026-01-01 podem retornar resultados vazios. Exemplo: sevdesk-agent read getInvoices --query startDate=1767225600 --query endDate=1769903999 --output json
   • Gerar um documento de referência completo de operações de leitura: sevdesk-agent docs read-ops --output knowledge/READ_OPERATIONS.md
3. Para chamadas de gravação:
   • POST / PUT / PATCH: sevdesk-agent write <operationId> ...
   • edições ergonômicas de entidades:
     • sevdesk-agent order edit --order-id <id> ... --verify
     • sevdesk-agent contact edit --contact-id <id> ... --verify
   • gravações multipart estão disponíveis com --form-field key=value e --form-file file=/caminho/para/arquivo
   • DELETE: sevdesk-agent write <operationId> --execute --confirm-execute yes --allow-write ...
   • para createContact / createOrder, a validação local de preflight é executada por padrão
   • para createInvoiceByFactory, o preflight também valida a consistência das datas de fatura/entrega (--auto-fix-delivery-date disponível)
   • para voucherFactorySaveVoucher e bookVoucher, o preflight local valida os campos contábeis de alto risco antes da chamada da API
   • adicione --verify para executar verificações pós-gravação somente leitura (incluindo createInvoiceByFactory, voucherFactorySaveVoucher e bookVoucher)
   • para fluxos de createContact, prefira --verify-contact (inclui verificações de incompatibilidade de customerNumber; correção automática habilitada por padrão e pode ser desabilitada via --no-fix-contact)
4. Persistir contexto de handoff do agente:
   • stdout (padrão): sevdesk-agent context snapshot
   • exportação opcional de arquivo: sevdesk-agent context snapshot --output .context/sevdesk-context-snapshot.json

Runbook padrão: Contato + Orçamento + PDF

1. Descoberta:
   • sevdesk-agent ops list --read-only
   • sevdesk-agent op-show createContact
   • sevdesk-agent op-show createOrder
2. Encontrar/Criar Contato:
   • sevdesk-agent find-contact "<nome ou customerNumber>" --output json
   • sevdesk-agent write createContact ... --verify-contact
3. Criar Orçamento:
   • sevdesk-agent write createOrder ... --verify
4. Exportação PDF sem efeito colateral de status:
   • sevdesk-agent read orderGetPdf --path orderId=<id> --decode-pdf output/<arquivo>.pdf --suppress-content
   • preventSendBy=1 é definido por padrão (--no-safe-pdf desativa isso)
5. Handoff:
   • sevdesk-agent context snapshot --include-default

Auxiliares adicionais de fatura

• Parcelamento a partir de fatura existente:
  • sevdesk-agent create-invoice-installment --from-invoice <id> --percent 70 --label "..." [--execute --verify]
• Clonar fatura para fluxos recorrentes:
  • sevdesk-agent invoice clone --from <id> --date <...> --period <...> with selective position overrides
• Substituição segura de fatura quando a mutação genérica de fatura não está disponível:
  • sevdesk-agent invoice recreate --from <id> --patch-file payloads/invoice.patch.json --verify
• Captura de voucher a partir de PDF local:
  • sevdesk-agent create-voucher-from-pdf --file /caminho/absoluto/para/beleg.pdf ... [--execute --verify]
• Auxiliares de lançamento de voucher:
  • 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 /caminho/absoluto/para/beleg.pdf --transaction-id <id> ... [--execute --verify]
• Auto-verificação e sincronização de comandos:
  • sevdesk-agent doctor --json

Salvaguardas

• O comportamento padrão é favorável ao fluxo de trabalho: POST/PUT/PATCH são executados diretamente; DELETE é bloqueado a menos que flags de proteção sejam definidas.
• Em fluxos de trabalho de produção, prefira testes somente leitura e sondas somente leitura primeiro.
• Para endpoints *GetPdf, as respostas são tipicamente JSON encapsuladas em data.objects (muitas vezes contendo filename, mimetype e conteúdo content em base64).
• para orderGetPdf / invoiceGetPdf, o CLI agora aplica preventSendBy=1 por padrão (modo PDF seguro).
• use --decode-pdf <caminho> para saída direta de arquivo PDF sem jq/base64.
• com --decode-pdf, use --suppress-content (padrão) para manter grandes payloads base64 fora da saída do CLI.
• create-voucher-from-pdf, book-voucher e assign-voucher-to-transaction são dry-run por padrão; gravações reais ocorrem apenas com --execute.
• voucher book-existing e expense process-paid também são dry-run por padrão; use --execute somente após verificar o payload derivado.
• order edit, contact edit e invoice recreate são executados diretamente como fluxos PUT/POST normais; use --verify para validar o resultado imediatamente.
• Quando uma resposta de gravação ou verificação embutida retorna ok: false, o CLI sai com status de shell não zero. Não trate isso como sucesso em automação.
• Se o servidor retornar um tipo de conteúdo binário não JSON (pdf/xml/zip/csv), o CLI imprime metadados (binary, bytes, contentType) em vez de bytes brutos.
• Peculiaridades de consulta exigidas em tempo de execução são aplicadas para operações selecionadas (por exemplo, contactCustomerNumberAvailabilityCheck requer customerNumber em tempo de execução).
• Use op-show ou ops-quirks para ver peculiaridades de tempo de execução específicas da operação.
• ops-quirks --json retorna um objeto de mapeamento; para análise de array estável, use ops-quirks --json-array.
• se você precisar de orientação sobre mutação de fatura e updateInvoice estiver ausente, execute sevdesk-agent docs invoice-edit.
• se você precisar alterar o conteúdo de uma fatura, prefira sevdesk-agent invoice recreate --from <id> ... em vez de adivinhar um payload updateInvoice bruto.
• para sequência de numeração/finalização após a criação da fatura, execute sevdesk-agent docs invoice-finalize.

Referências

• Folha de consulta de comandos: references/command-cheatsheet.md
• Notas de gravação de oferta/pedido (comportamento ativo): knowledge/SEVDESK_ORDER_WRITE_LEARNINGS.md