Pakketten en uitzonderingen¶

Deze pagina laat zien hoe je de dienst van een organisatie bekijkt, en hoe je voor een organisatie onder de jouwe pakketten geeft en weghaalt, uitzonderingen zet, een proefperiode instelt en de einddatum van een demo bepaalt. Wat de dienst, pakketten, uitzonderingen en demo's zijn, staat in De dienst van je organisatie.

De dienst heeft nog geen scherm in OS: je beheert hem via de API. De voorbeelden gebruiken $OS, $TOKEN en $ORG zoals in Groepen beheren, en daarnaast $KLANT, het id van de organisatie onder de jouwe waarvan je de dienst instelt.

Wie wat mag¶

Je wijzigt de dienst van een organisatie dus altijd vanuit de organisatie erboven, nooit in de organisatie zelf. Een partner stelt zo de dienst van zijn klanten in, en een klant met afdelingen die van zijn afdelingen. Wat je geeft, ligt binnen de dienst van je eigen organisatie: een pakket of een toegevoegd onderdeel dat daarbuiten reikt, weigert OS. Een uitzondering die iets weghaalt, mag altijd, want die maakt de dienst alleen kleiner.

Wat Artific op een van je klanten zette, haal jij als partner niet weg: dat kan alleen vanuit de organisatie die het zette, of een daarboven. Vraag het dan aan Artific.

De pakketten zelf stelt Artific samen. Mist een pakket iets wat je klanten nodig hebben, vraag het dan aan je contactpersoon bij Artific.

De dienst bekijken¶

curl -s "$OS/api/v1/organisations/$KLANT/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 is wat de dienst nu bevat: haar pakketten en uitzonderingen die nu gelden, binnen de dienst van de organisatie erboven. actions: null is elke actie die de soort kent. Wat elke dienst bevat (altijd in de dienst) staat er niet bij.
• demo_ends_at is de einddatum van een demo, en null voor elke andere organisatie.
• allowed_actions zegt wat jij met de dienst mag in de organisatie zelf: see is hem lezen.
• parent_allowed_actions zegt wat jij met de dienst mag in de organisatie erboven. Staat write erin, dan mag je pakketten en uitzonderingen geven en weghalen en de einddatum van een demo zetten.

Met je eigen $ORG lees je zo de dienst van je eigen organisatie.

Welke pakketten je kunt geven¶

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

Dit zijn de pakketten van Artific die binnen de dienst van je eigen organisatie liggen: wat je de organisaties onder de jouwe kunt geven. Elk pakket heeft een id (pln_...), een name en zijn items. De lijst komt per pagina; een pagina kan minder rijen hebben dan limit terwijl next_cursor toch verder gaat.

Een pakket geven¶

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

OS antwoordt 201 met het gegeven pakket:

{"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 is optioneel: wanneer het pakket ingaat. Zonder is dat nu.
• ends_at is optioneel: wanneer het pakket stopt. Met een einddatum is het een proefperiode.
• in_force zegt of het pakket nu geldt.
• id (opl_...) is het id van dit pakket bij deze organisatie; je gebruikt het om het weer weg te halen.
• set_by is wie het pakket gaf. De beheerders van de organisatie zelf zien hier null.

Een organisatie heeft hoogstens 20 pakketten, verlopen pakketten meegeteld.

De pakketten van een organisatie bekijken¶

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

De lijst toont ook verlopen pakketten en pakketten die nog moeten ingaan; in_force zegt welke nu gelden. Eén pakket lees je met GET .../service/plans/opl_....

Een pakket weghalen¶

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

OS antwoordt 204. De dienst van de organisatie krimpt meteen. Haal je haar laatste pakket weg, dan heeft ze weer de dienst van de organisatie erboven (waarom).

Een uitzondering zetten¶

Een uitzondering voegt één onderdeel toe (add) of haalt er één weg (remove):

curl -s -X POST "$OS/api/v1/organisations/$KLANT/service/exceptions" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"effect": "add", "kind": "toolbox",
         "reason": "Pilot met de AI Toolbox voor het juridische team"}'

OS antwoordt 201 met de uitzondering, met een id (svx_...), in_force, set_by en reason. De beheerders van de organisatie zelf zien in set_by en reason null. Een uitzondering die iets weghaalt, wint van wat de pakketten geven. Een organisatie heeft hoogstens 100 uitzonderingen, verlopen meegeteld.

De uitzonderingen van een organisatie bekijk je met GET .../service/exceptions, één met GET .../service/exceptions/svx_.... Je haalt er een weg met DELETE op dat adres; OS antwoordt 204.

Een proefperiode instellen¶

Een proefperiode is een pakket of een toegevoegde uitzondering met ends_at:

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

De einddatum ligt na de begindatum, of na nu als je geen begindatum noemt. Op de einddatum stopt de proefperiode vanzelf; je hoeft niets te doen. De AI-functies volgen binnen enkele minuten, en het logboek van de organisatie noemt het einde. Het verlopen pakket blijft in de lijst staan, met in_force: false. Wil de klant verder, geef dan het pakket opnieuw zonder einddatum en haal het verlopen pakket weg.

De einddatum van een demo¶

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

Dit maakt de organisatie een demo: op de einddatum wordt ze opgeschort, en dertig dagen later gewist, behalve als er nog organisaties onder haar bestaan (Demo's). De datum ligt in de toekomst. Je kunt hem verschuiven door hem opnieuw te zetten. OS antwoordt met de dienst, zoals bij De dienst bekijken.

Een demo omzetten in een gewone organisatie doe je door de einddatum weg te halen, met {"ends_at": null}, en haar een gewoon pakket te geven. Dat mag ieder die haar dienst mag wijzigen. De einddatum weghalen hervat een opgeschorte demo niet: hervat haar dan ook, zoals elke andere organisatie.

Als OS weigert¶