Provisionnement des utilisateurs

Les personnes qui interviennent dans vos parapheurs — gestionnaires, signataires, validateurs — sont des utilisateurs de votre tenant. Avant de les faire intervenir, il faut les provisionner : les créer, ou réutiliser ceux qui existent déjà. Chaque utilisateur appartient à un groupe (fondation Groupes, rôles & droits), qui porte ses droits.

Créer un utilisateur

POST /api/tenants/{tenantId}/users
Authorization: Bearer act_<id>.<secret>
Content-Type: application/json
{
  "groupId": "grp_…",
  "email": "roy.neary@example.org",
  "firstName": "Roy",
  "lastName": "Neary",
  "phoneNumber": "+33 6 12 34 56 78",
  "country": "FR"
}

groupId, email, firstName et lastName sont requis. L’appel s’authentifie avec un jeton d’API dont l’utilisateur porte les droits nécessaires (par ex. Administrateur des utilisateurs, ou une autorisation inter-groupes de création — fondation Groupes, rôles & droits).

Format du phoneNumber. Le numéro doit être international, commençant par + suivi de l’indicatif pays (E.164). Les espaces sont facultatifs : +33612345678 et +33 6 12 34 56 78 sont tous deux acceptés, et l’API renvoie une forme normalisée (regroupée par blocs selon le pays). En revanche :

• un numéro national sans indicatif (0612345678) est rejeté (InvalidRequestField) — la plateforme n’a pas de « pays par défaut » et ne peut pas le déduire ;
• ⚠️ le préfixe d’appel 00 (0033612345678) n’est pas reconnu comme préfixe international : il est accepté sans erreur mais mal interprété (aboutit à un numéro erroné) — n’utilisez jamais 00, toujours +.

Autrement dit, il n’est pas nécessaire de connaître le « format d’affichage » d’un pays : il suffit de fournir +<indicatif><numéro>, la mise en forme est faite par la plateforme.

La réponse renvoie l’utilisateur créé (identifiant préfixé usr_), enrichi de champs calculés :

{
  "id": "usr_LqVk5fa8mxFccrfBRAi433Ry",
  "groupId": "grp_…",
  "email": "roy.neary@example.org",
  "firstName": "Roy", "lastName": "Neary", "name": "Roy Neary",
  "phoneNumber": "+33 6 12 34 56 78", "country": "FR",
  "signAllowed": true, "approveAllowed": true, "comanageAllowed": false,
  "isDisabled": false, "lastLogin": 0,
  "tenantId": "ten_…", "created": 1782821445591, "updated": 1782821445591
}

• name — nom complet calculé (firstName + lastName).
• signAllowed / approveAllowed / comanageAllowed — capacités déduites des rôles du groupe (indicateurs en lecture seule) : l’utilisateur peut-il signer, valider, cogérer.
• viewAuthorizedGroups — groupes autorisés à voir cet utilisateur.

Réutiliser un utilisateur existant (idempotence par e-mail)

Au sein d’un tenant, une adresse e-mail est unique : deux utilisateurs ne peuvent pas partager le même e-mail. Avant de créer l’utilisateur, réfléchissez aux différentes options possibles :

• Ne tenez pas compte de l’existant et créez le compte même s’il existe déjà : cette option est particulièrement pertinente si votre application est la seule à utiliser l’utilisateur en question et vous maîtrisez alors complètement à l’instant t la définition de l’utilisateur avec la requête POST ci-dessus.
• Recherchez l’utilisateur par e-mail et réutilisez le compte s’il existe déjà : cette option est particulièrement pertinente si d’autres applications ont besoin d’accéder à cet utilisateur ou bien si l’utilisateur dispose du droit de se connecter au portail ; dans ce cas utilisez la requête ci-dessous.

GET /api/users?items.email=roy.neary@example.org

→ la réponse contient un tableau items ; si un utilisateur actif correspond, réutilisez son id plutôt que d’en recréer un. Sinon, créez-le (section Créer un utilisateur). Ce contrôle d’idempotence se fait côté application.

Cycle de vie d’un utilisateur

• Consulter — GET /api/users/{id} ; GET /api/users/me renvoie l’utilisateur du jeton d’API courant.
• Modifier — PATCH /api/users/{id} (concurrence optimiste If-Match, fondation Structure > Concurrence : l’en-tête conditionnel If-Match) : mettre à jour l’identité, le téléphone, le pays, le groupe…
• Anonymiser — un utilisateur ne se supprime pas ; il s’anonymise (finalité RGPD), via l’endpoint dédié (Anonymize user).
• Rechercher — GET /api/users avec filtres items.<champ> (items.email, items.groupId, items.isDisabled…) et pagination (fondation Structure > Recherche & pagination).

Contacts : des signataires privés à un utilisateur

Outre les utilisateurs, l’API permet de gérer des contacts propres à un utilisateur. Un contact est une personne (signataire ou validateur) qu’un utilisateur enregistre pour son propre usage :

POST /api/users/{userId}/contacts

Champs : email, firstName, lastName (requis), phoneNumber, country, comments (facultatifs) ; l’identifiant renvoyé est préfixé con_. Créer des contacts requiert le rôle Créateur de contacts (contactCreator, fondation Groupes, rôles & droits). Ainsi, un utilisateur autorisé à créer des parapheurs peut désigner, pour ses étapes de signature ou de validation, soit des utilisateurs, soit ses propres contacts.

Particularités importantes :

• Un contact est propre et exclusif à l’utilisateur qui l’a créé : personne d’autre n’y a accès, y compris un superadministrateur. Un utilisateur, à l’inverse, est partagé à l’échelle du tenant.
• Un document signé par un contact n’apparaît pas dans le compte Goodflag de cette personne — même si elle en possède un sur le tenant où le parapheur a été créé.

Quand les utiliser ? Les contacts conviennent surtout aux organisations cloisonnées, où l’on ne souhaite pas partager les informations des signataires entre utilisateurs.

Recommandation. Dans un déploiement d’entreprise, préférez provisionner les signataires comme utilisateurs : ils sont réutilisables d’un service à l’autre. Un signataire client qui signe un bon de commande émis par le service commercial pourra ainsi être également signataire d’un accord de confidentialité émis par le service juridique.

Dans la suite de cette documentation et dans les cas d’usage, les signataires et les validateurs sont toujours des utilisateurs.

Organisations & fonction du signataire

Un signataire peut signer au nom d’une organisation (en tant que représentant) et faire apparaître une fonction sur sa signature (par exemple « Membre », « Directeur des achats », « Par délégation de pouvoir de Mme XYZ », …).

Quand le téléphone est-il exigé ?

Le réflexe est d’associer phoneNumber à la seule authentification par OTP SMS. C’est insuffisant : plusieurs pages de consentement l’exigent, pour des raisons différentes. C’est notamment le cas de la page de signature avancée conforme au standard ETSI LCP, qui procède à une vérification de la pièce d’identité — et cela sans que l’authentification passe par un code SMS.

La règle pratique est donc plus simple à retenir dans l’autre sens : renseignez le téléphone dès que vous le connaissez, plutôt que de chercher à deviner si le niveau de signature visé l’imposera. Un numéro inutile ne coûte rien ; un numéro manquant interrompt la signature au moment le plus visible, devant le signataire.

Les organisations

Une organisation se crée au niveau du tenant (identifiant renvoyé préfixé org_) :

POST /api/tenants/{tenantId}/organizations
{ "name": "Goodflag", "organizationIdentifier": "NTRFR-480622257" }

La fonction du signataire

La fonction (titre) est toujours rattachée à une organisation. On peut la définir :

• sur l’utilisateur, via organizationTitles — une liste d’objets { organizationId, title } (section Créer un utilisateur) ;
• sur le destinataire d’une étape, via organizationId + title — ce qui prime pour cette étape (la même personne peut ainsi signer avec une fonction différente d’un parapheur à l’autre).

Le title est le libellé affiché (« Membre », « Président de séance »…). Pour qu’un signataire puisse signer au nom d’une organisation, la page de consentement doit l’autoriser (allowOrganization, voir la fondation Pages de consentement).

Le modèle en une phrase : les organisations existent indépendamment des utilisateurs ; on rattache ensuite un utilisateur à une organisation, et c’est à ce moment qu’on lui donne sa fonction. Un utilisateur peut appartenir à plusieurs organisations, mais il ne peut avoir qu’une seule fonction par organisation — le couple est unique. Pour lui en attribuer une autre au sein de la même organisation, on retire le couple { organizationId, title } et on en recrée un.

⚠️ Le title envoyé sur le destinataire n’est pas restitué. En relisant un parapheur créé avec organizationId et title sur son destinataire, on retrouve l’organizationId mais pas le title. Deux lectures possibles — le champ est ignoré, ou il est conservé sans être renvoyé — et l’API ne permet pas de trancher. Conséquence pratique : ne comptez pas sur une relecture pour vérifier la fonction ; contrôlez-la sur le document signé, où le cartouche l’affiche (fondation Profils de signature).

⚠️ L’organisation n’est pas héritée de la fiche. Désigner un destinataire par son userId reprend bien son identité — e-mail, nom, téléphone, pays — mais ni son organisation ni sa fonction — et pour une raison de fond : une personne peut appartenir à plusieurs organisations, avec une fonction dans chacune. La plateforme ne peut donc pas deviner laquelle s’applique à ce parapheur, et c’est à vous de la choisir. Le destinataire reste sinon dépourvu d’organizationId et de title. La voie « sur le destinataire » n’est donc pas seulement prioritaire, elle est la seule qui fasse réellement porter l’organisation par le parapheur. Renseignez organizationId + title à la création, même lorsque la fiche de l’utilisateur les contient déjà.

La fonction et l’organisation peuvent apparaître sur le cartouche de signature, via le gabarit du profil de signature ({{signerOrganizationTitle}}, {{signerOrganization}}) — voir la fondation Profils de signature.

Bonnes pratiques

• Tenir l’identité à jour (firstName, lastName, phoneNumber, country) avant de faire intervenir l’utilisateur comme signataire : ces informations alimentent la signature (le détail est traité dans les cas d’usage).
• Idempotence : rechercher par e-mail avant de créer (section Réutiliser un utilisateur existant (idempotence par e-mail)).
• Dans un parapheur, référencer un signataire par son userId : l’identité est alors reprise de sa fiche (voir les cas d’usage) — à l’exception de l’organisation et de la fonction, à porter explicitement sur le destinataire (section Organisations & fonction du signataire).