Offres et exceptions¶

Cette page montre comment consulter le service d'une organisation, et comment, pour une organisation située sous la vôtre, donner et retirer des offres, poser des exceptions, configurer une période d'essai et fixer la date de fin d'une démo. Ce que sont le service, les offres, les exceptions et les démos est expliqué dans Le service de votre organisation.

Le service n'a pas encore d'écran dans OS : vous le gérez via l'API. Les exemples utilisent $OS, $TOKEN et $ORG comme dans Gérer les groupes, et en plus $CUSTOMER, l'identifiant de l'organisation située sous la vôtre dont vous configurez le service.

Qui peut faire quoi¶

Vous modifiez donc toujours le service d'une organisation depuis l'organisation au-dessus, jamais dans l'organisation elle-même. Un partenaire configure ainsi le service de ses clients, et un client avec des services celui de ses services. Ce que vous donnez reste dans le service de votre propre organisation : OS refuse une offre ou un élément ajouté qui le dépasse. Une exception qui retire quelque chose est toujours possible, car elle ne fait que réduire le service.

Ce qu'Artific a posé sur l'un de vos clients, vous ne le retirez pas en tant que partenaire : cela n'est possible que depuis l'organisation qui l'a posé, ou une organisation au-dessus. Demandez-le alors à Artific.

Les offres elles-mêmes sont composées par Artific. Si une offre manque de quelque chose dont vos clients ont besoin, demandez-le à votre contact chez Artific.

Consulter le service¶

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 est ce que le service contient maintenant : ses offres et exceptions qui valent actuellement, dans le service de l'organisation au-dessus. actions: null signifie toutes les actions que connaît le type. Ce que contient chaque service (toujours dans le service) n'y figure pas.
• demo_ends_at est la date de fin d'une démo, et null pour toute autre organisation.
• allowed_actions indique ce que vous pouvez faire avec le service dans l'organisation elle-même : see est le lire.
• parent_allowed_actions indique ce que vous pouvez faire avec le service dans l'organisation au-dessus. Si write y figure, vous pouvez donner et retirer des offres et des exceptions et fixer la date de fin d'une démo.

Avec votre propre $ORG, vous lisez ainsi le service de votre propre organisation.

Quelles offres vous pouvez donner¶

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

Ce sont les offres d'Artific qui se trouvent dans le service de votre propre organisation : ce que vous pouvez donner aux organisations situées sous la vôtre. Chaque offre a un id (pln_...), un name et ses items. La liste vient par pages ; une page peut avoir moins de lignes que limit alors que next_cursor continue.

Donner une offre¶

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 répond 201 avec l'offre donnée :

{"id": "opl_...", "plan_id": "pln_...", "plan_name": "Assistants",
 "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 est facultatif : quand l'offre commence. Sans lui, c'est maintenant.
• ends_at est facultatif : quand l'offre s'arrête. Avec une date de fin, c'est une période d'essai.
• in_force indique si l'offre vaut maintenant.
• id (opl_...) est l'identifiant de cette offre pour cette organisation ; vous l'utilisez pour la retirer.
• set_by est qui a donné l'offre. Les administrateurs de l'organisation elle-même voient ici null.

Une organisation a 20 offres au maximum, offres expirées comprises.

Consulter les offres d'une organisation¶

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

La liste montre aussi les offres expirées et celles qui doivent encore commencer ; in_force indique lesquelles valent maintenant. Vous lisez une seule offre avec GET .../service/plans/opl_....

Retirer une offre¶

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

OS répond 204. Le service de l'organisation se réduit aussitôt. Si vous retirez sa dernière offre, elle a de nouveau le service de l'organisation au-dessus (pourquoi).

Poser une exception¶

Une exception ajoute un élément (add) ou en retire un (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": "Pilote de l AI Toolbox pour l equipe juridique"}'

OS répond 201 avec l'exception, avec un id (svx_...), in_force, set_by et reason. Les administrateurs de l'organisation elle-même voient null dans set_by et reason. Une exception qui retire quelque chose l'emporte sur ce que donnent les offres. Une organisation a 100 exceptions au maximum, expirées comprises.

Vous consultez les exceptions d'une organisation avec GET .../service/exceptions, une seule avec GET .../service/exceptions/svx_.... Vous en retirez une avec DELETE sur cette adresse ; OS répond 204.

Configurer une période d'essai¶

Une période d'essai est une offre ou une exception ajoutée avec 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"}'

La date de fin est postérieure à la date de début, ou à maintenant si vous n'indiquez pas de date de début. À la date de fin, la période d'essai s'arrête d'elle-même ; vous n'avez rien à faire. Les fonctions d'IA suivent en quelques minutes, et le journal d'audit de l'organisation mentionne la fin. L'offre expirée reste dans la liste, avec in_force: false. Si le client veut continuer, donnez à nouveau l'offre sans date de fin et retirez l'offre expirée.

La date de fin d'une démo¶

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"}'

Cela fait de l'organisation une démo : à la date de fin, elle est suspendue, et trente jours plus tard supprimée, sauf s'il existe encore des organisations en dessous d'elle (Démos). La date est dans le futur. Vous pouvez la déplacer en la fixant à nouveau. OS répond avec le service, comme pour Consulter le service.

Transformer une démo en organisation ordinaire se fait en retirant la date de fin, avec {"ends_at": null}, et en lui donnant une offre ordinaire. Toute personne qui peut modifier son service peut le faire. Retirer la date de fin ne rétablit pas une démo suspendue : rétablissez-la alors aussi, comme n'importe quelle autre organisation.

Quand OS refuse¶