Pläne und Ausnahmen¶

Diese Seite zeigt, wie Sie den Dienst einer Organisation ansehen und wie Sie für eine Organisation unter Ihrer eigenen Pläne vergeben und entfernen, Ausnahmen setzen, einen Testzeitraum einrichten und das Enddatum einer Demo festlegen. Was der Dienst, Pläne, Ausnahmen und Demos sind, steht unter Der Dienst Ihrer Organisation.

Der Dienst hat in OS noch keinen Bildschirm: Sie verwalten ihn über die API. Die Beispiele nutzen $OS, $TOKEN und $ORG wie unter Gruppen verwalten und zusätzlich $CUSTOMER, die ID der Organisation unter Ihrer eigenen, deren Dienst Sie einstellen.

Wer was darf¶

Den Dienst einer Organisation ändern Sie also immer aus der Organisation darüber, nie in der Organisation selbst. Ein Partner stellt so den Dienst seiner Kunden ein und ein Kunde mit Abteilungen den seiner Abteilungen. Was Sie vergeben, liegt innerhalb des Dienstes Ihrer eigenen Organisation: Einen Plan oder einen hinzugefügten Bestandteil, der darüber hinausreicht, lehnt OS ab. Eine Ausnahme, die etwas wegnimmt, ist immer erlaubt, denn sie macht den Dienst nur kleiner.

Was Artific bei einem Ihrer Kunden gesetzt hat, nehmen Sie als Partner nicht weg: Das geht nur aus der Organisation, die es gesetzt hat, oder einer darüber. Fragen Sie dann Artific.

Die Pläne selbst stellt Artific zusammen. Fehlt in einem Plan etwas, was Ihre Kunden brauchen, fragen Sie Ihre Ansprechperson bei Artific.

Den Dienst ansehen¶

curl -s "$OS/api/v1/organisations/$CUSTOMER/service" -H "Authorization: Bearer $TOKEN"

{"organisation_id": "org_...",
 "items": [{"kind": "agent", "actions": ["see", "use"]},
           {"kind": "knowledge_collection", "actions": null},
           {"kind": "thread", "actions": null}],
 "demo_ends_at": null,
 "allowed_actions": ["see", "write"],
 "parent_allowed_actions": ["see", "write"]}

• items ist, was der Dienst jetzt enthält: ihre Pläne und Ausnahmen, die jetzt gelten, innerhalb des Dienstes der Organisation darüber. actions: null ist jede Aktion, die die Art kennt. Was jeder Dienst enthält (immer im Dienst), steht nicht dabei.
• demo_ends_at ist das Enddatum einer Demo und null für jede andere Organisation.
• allowed_actions sagt, was Sie mit dem Dienst in der Organisation selbst dürfen: see ist ihn lesen.
• parent_allowed_actions sagt, was Sie mit dem Dienst in der Organisation darüber dürfen. Steht write darin, dürfen Sie Pläne und Ausnahmen vergeben und entfernen und das Enddatum einer Demo setzen.

Mit Ihrer eigenen $ORG lesen Sie so den Dienst Ihrer eigenen Organisation.

Welche Pläne Sie vergeben können¶

curl -s "$OS/api/v1/organisations/$ORG/assignable-plans" -H "Authorization: Bearer $TOKEN"

Das sind die Pläne von Artific, die innerhalb des Dienstes Ihrer eigenen Organisation liegen: was Sie den Organisationen unter Ihrer vergeben können. Jeder Plan hat eine id (pln_...), einen name und seine items. Die Liste kommt seitenweise; eine Seite kann weniger Zeilen als limit haben, während next_cursor trotzdem weitergeht.

Einen Plan vergeben¶

curl -s -X POST "$OS/api/v1/organisations/$CUSTOMER/service/plans" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"plan_id": "pln_..."}'

OS antwortet 201 mit dem vergebenen Plan:

{"id": "opl_...", "plan_id": "pln_...", "plan_name": "Assistenten",
 "starts_at": "2026-11-01T00:00:00Z", "ends_at": null, "in_force": true,
 "set_by": "...", "created_at": "2026-11-01T00:00:00Z",
 "allowed_actions": ["see", "write"]}

• starts_at ist optional: wann der Plan in Kraft tritt. Ohne ist das jetzt.
• ends_at ist optional: wann der Plan endet. Mit einem Enddatum ist es ein Testzeitraum.
• in_force sagt, ob der Plan jetzt gilt.
• id (opl_...) ist die ID dieses Plans bei dieser Organisation; Sie brauchen sie, um ihn wieder zu entfernen.
• set_by ist, wer den Plan vergeben hat. Die Administratoren der Organisation selbst sehen hier null.

Eine Organisation hat höchstens 20 Pläne, abgelaufene mitgezählt.

Die Pläne einer Organisation ansehen¶

curl -s "$OS/api/v1/organisations/$CUSTOMER/service/plans" -H "Authorization: Bearer $TOKEN"

Die Liste zeigt auch abgelaufene Pläne und Pläne, die noch beginnen müssen; in_force sagt, welche jetzt gelten. Einen Plan lesen Sie mit GET .../service/plans/opl_....

Einen Plan entfernen¶

curl -s -X DELETE "$OS/api/v1/organisations/$CUSTOMER/service/plans/opl_..." \
    -H "Authorization: Bearer $TOKEN"

OS antwortet 204. Der Dienst der Organisation schrumpft sofort. Entfernen Sie ihren letzten Plan, hat sie wieder den Dienst der Organisation darüber (warum).

Eine Ausnahme setzen¶

Eine Ausnahme fügt einen Bestandteil hinzu (add) oder nimmt einen heraus (remove):

curl -s -X POST "$OS/api/v1/organisations/$CUSTOMER/service/exceptions" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"effect": "add", "kind": "toolbox",
         "reason": "Pilot mit der AI Toolbox für das Rechtsteam"}'

OS antwortet 201 mit der Ausnahme, mit einer id (svx_...), in_force, set_by und reason. Die Administratoren der Organisation selbst sehen in set_by und reason null. Eine Ausnahme, die etwas wegnimmt, gewinnt gegenüber dem, was die Pläne geben. Eine Organisation hat höchstens 100 Ausnahmen, abgelaufene mitgezählt.

Die Ausnahmen einer Organisation sehen Sie mit GET .../service/exceptions, eine einzelne mit GET .../service/exceptions/svx_.... Sie entfernen eine mit DELETE auf dieser Adresse; OS antwortet 204.

Einen Testzeitraum einrichten¶

Ein Testzeitraum ist ein Plan oder eine hinzugefügte Ausnahme mit ends_at:

curl -s -X POST "$OS/api/v1/organisations/$CUSTOMER/service/plans" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"plan_id": "pln_...", "ends_at": "2026-12-01T00:00:00Z"}'

Das Enddatum liegt nach dem Startdatum, oder nach jetzt, wenn Sie kein Startdatum nennen. Am Enddatum endet der Testzeitraum von selbst; Sie müssen nichts tun. Die KI-Funktionen folgen innerhalb weniger Minuten, und das Prüfprotokoll der Organisation nennt das Ende. Der abgelaufene Plan bleibt in der Liste stehen, mit in_force: false. Möchte der Kunde weitermachen, vergeben Sie den Plan erneut ohne Enddatum und entfernen den abgelaufenen Plan.

Das Enddatum einer Demo¶

curl -s -X PUT "$OS/api/v1/organisations/$CUSTOMER/service/demo-end" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"ends_at": "2026-12-01T00:00:00Z"}'

Das macht die Organisation zu einer Demo: Am Enddatum wird sie ausgesetzt und dreißig Tage später gelöscht, außer wenn noch Organisationen unter ihr bestehen (Demos). Das Datum liegt in der Zukunft. Sie können es verschieben, indem Sie es erneut setzen. OS antwortet mit dem Dienst, wie unter Den Dienst ansehen.

Eine Demo in eine gewöhnliche Organisation umzuwandeln geschieht, indem Sie das Enddatum mit {"ends_at": null} entfernen und ihr einen gewöhnlichen Plan geben. Das darf jeder, der ihren Dienst ändern darf. Das Entfernen des Enddatums setzt eine ausgesetzte Demo nicht fort: Setzen Sie sie dann auch fort, wie jede andere Organisation.

Wenn OS ablehnt¶