Zum Hauptinhalt springen

API — Custom-Aktionen (do:)

Standard-CRUD reicht oft nicht. Für State-Übergänge, Approvals, Bulk-Operationen gibt es Custom-Actions mit do:-Präfix.

Standard-Custom-Actions​

Approve / Reject​

POST /api/absences/:id/approve
{
  "comment": "Genehmigt — Vertretung Lisa Müller"
}

POST /api/absences/:id/reject
{
  "reason": "Personal-Lage zu eng — alternativer Termin vorschlagen"
}

CASL: do:ApproveAbsence, do:RejectAbsence.

Lifecycle-Übergänge (Sales Documents)​

POST /api/sales-documents/:id/handover
{
  "targetType": "order_confirmation",  # oder delivery_note, invoice
  "options": {
    "deliveryDate": "2026-05-10"
  }
}

CASL: do:HandoverSalesDocument.

Erstellt einen neuen Beleg mit Lifecycle-Verknüpfung zur Quelle. Mehr in Workflow-Diagramme.

Storno​

POST /api/sales-documents/:id/cancel
{
  "reason": "Kunde hat storniert"
}

Erstellt eine Storno-Rechnung (negative Beträge), markiert Quelle als storniert. CASL: do:CancelSalesDocument.

Lock / Unlock​

POST /api/sales-documents/:id/lock
POST /api/sales-documents/:id/unlock

Sperrt Beleg gegen Bearbeitung. CASL: do:LockSalesDocument.

Bulk-Import​

POST /api/customers/bulk-import
{
  "format": "csv",
  "data": "...",
  "mapping": { ... },
  "dryRun": true
}

dryRun: true validiert ohne zu schreiben. CASL: do:BulkImportCustomer.

Download (Export)​

GET /api/accountings/:id/download?format=datev

CASL: do:DownloadAccounting.

Compliance-Approve​

POST /api/compliance-checks/:id/approve
{
  "validUntil": "2027-05-05",
  "documents": ["uuid1", "uuid2"]
}

CASL: do:EmployeeComplianceCheck.

Restore (aus Papierkorb)​

POST /api/customers/:id/restore

CASL: do:RestoreCustomer.

Custom-Actions auflisten​

Pro Resource:

GET /api/customers/:id/available-actions

Response:

{
  "actions": [
    {
      "name": "do:DeactivateCustomer",
      "label": "Deaktivieren",
      "available": true
    },
    {
      "name": "do:RestoreCustomer",
      "label": "Wiederherstellen",
      "available": false,
      "reason": "Kunde ist nicht im Papierkorb"
    }
  ]
}

Nützlich für UI-Buttons / KI-Chat — zeigt nur was wirklich möglich ist.

Idempotenz bei do:-Actions​

Wichtig — viele do:-Actions ändern State, also nicht beliebig wiederholbar.

POST /api/sales-documents/:id/handover
Idempotency-Key: my-unique-key

Mehrfaches Senden mit gleichem Key → gleiche Antwort, keine doppelte Aktion.

Bei Fehler​

{
  "error": {
    "code": "INVALID_TRANSITION",
    "message": "Cannot handover from 'sent' to 'order_confirmation'",
    "details": {
      "currentState": "sent",
      "targetState": "order_confirmation",
      "allowedTransitions": ["delivery_note", "invoice"]
    }
  }
}

Verwandte Doku​