API : Gérer les périmètres

Lorsque vous souscrivez à la version Enterprise de SELL&SIGN, les périmètres vous permettent de gérer la confidentialité de vos contrats. Ceux qui se trouvent dans un périmètre spécifique ne sont accessibles que par les utilisateurs du périmètre.

Ainsi, vous pouvez délimiter votre activité contractuelle selon des périmètres que vous définissez, via le Back Office, ou directement avec des appels API, à votre convenance. Vos périmètres peuvent être définis selon un secteur géographique, un service de votre entreprise, un modèle de document, un commercial en particulier, etc.

Ces périmètres s’appliquent alors soit sur les utilisateurs, soit sur les clients, soit sur les signataires, soit sur les contrats eux-mêmes.

Dans ce chapitre, vous aurez besoin des identifiants uniques de vos utilisateurs que vous pourrez retrouver avec les méthodes explicitées ici : https://doc.sellandsign.com/fr/api-gestion-des-utilisateurs/

Gérer les périmètres

Pour ajouter un périmètre, vous pouvez utiliser la méthode HTTP POST pour appeler la méthode getOrCreatePerimeter.

https://[host]/calinda/hub/selling/model/perimeter/update?action=getOrCreatePerimeter

    INPUT json à mettre en payload de la requête :

    {
"id" : -1,
"key" : "name of perimeter",
"description" : "description of perimeter",
}
    • id doit rester à -1 en création
    • key permet de nommer votre périmètre
    • description permet de décrire plus précisément l’usage de votre périmètre

    Pour récupérer un périmètre à partir de sa key, vous utiliser un HTTP POST pouvez appeler la méthode getPerimeterByKey.

    https://[host]/calinda/hub/selling/model/perimeter/read?action=getPerimeterByKey

    INPUT json à mettre en payload de la requête : 

    {
"key" : "name of perimeter"
}

    Vous obtiendrez en retour : 

    {
"id":1541,
"key":"test",
"description":"test",
"syncTimer":0,
"lastModificationPlace":"SERVER"
}
    • key permet de nommer votre périmètre.

    Pour lister les périmètres disponibles, vous pouvez appeler avec un POST la méthode getPerimeter.

    https://[host]/calinda/hub/selling/model/perimeter/list?action=getPerimeters

    INPUT json à mettre en payload de la requête :

    {
"keyword" :"",
"offset" : 0,
"size" : 10,
}
    • keyword permet de chercher par mot clé. Cette méthode retournera tous les périmètres contenant le mot clé saisi.
    • offset index du premier résultat (avec size, cela permet de se déplacer par bloc dans le résultat).
    • size taille du bloc de résultat à retourner.

    Les périmètres liés aux utilisateurs

    Pour gérer les périmètres de vos utilisateurs, vous pouvez ajouter un périmètre à un utilisateur avec la méthode addLimitToPerimeter, le supprimer avec la méthode removeLimitToPerimeter ou, encore, lister l’ensemble des périmètres d’un ou plusieurs utilisateurs avec la méthode getPerimeterForUser.

    Ajouter un périmètre à un utilisateur

    Avec un POST, vous pouvez appeler la méthode addLimitToPerimeter.

    https://[host]/calinda/hub/selling/model/limittoperimeter/insert?action=addLimitToPerimeter

    INPUT json à mettre en payload de la requête :

    {
"actor_id" : 10,
"perimeter_id" : 100,
}
      • perimeter_id est l’identifiant du périmètre (cet identifiant peut être retrouvé en utilisant la méthode getPerimeterForKey)

    Supprimer un périmètre associé à un utilisateur

    Supprimer un périmètre implique d’utiliser un HTTP POST pour accéder à la méthode removeLimitToPerimeter.

    https://[host]/calinda/hub/selling/model/limittoperimeter/insert?action=removeLimitToPerimeter

    INPUT json à mettre en payload de la requête :

    {
"actor_id" : 10,
"perimeter_id" : 100,
}
      • perimeter_id est l’identifiant du périmètre (cet identifiant peut être retrouvé en utilisant la méthode getPerimeterForKey)

    Accéder à la liste des périmètres d’un utilisateur

    Cette fois-ci, c’est avec un GET que vous accédez à la méthode getPerimeterForUser.

    https://[host]/calinda/hub/selling/ model/perimeter/list?action=getPerimeterForUser

    Query String Parameters :

    {
"action" : getPerimeterForUser,
"actor_id" : 433406,
"offset" : 0,
"size" : 12,
"keyword" : ""
}
      • action concerne la méthode que vous êtes en train d’utiliser.
      • actor_id correspond à l’utilisateur pour lequel vous souhaitez supprimer un périmètre.
      • offset index du premier résultat (avec size, cela permet de se déplacer par bloc dans le résultat).
      • size taille du bloc de résultat à retourner.
      • keyword permet de faire un tri par mot-clé parmi l’ensemble des périmètres existants.

    Les périmètres liés aux clients

    Vous pouvez attribuer un ou plusieurs périmètres à vos clients. Pour les gérer via API, vous pouvez utiliser la méthode addCustomerIsIn pour ajouter un client à un périmètre et la méthode removeCustomerIsIn pour le supprimer.

    Ajouter un périmètre à un client

    Avec un POST, vous pouvez appeler la méthode addCustomerIsIn.

    https://[host]/calinda/hub/selling/model/customerisin/insert?action=addCustomerIsIn

    INPUT json à mettre en payload de la requête :

    {
"customer_number" : Mi4hNTgzNjA0NzMwMTI4LjgxNTUw,
"perimeter_id" : 11,
}
      • customer_number correspond au numéro du client auquel vous ajoutez un périmètre. Celui-ci aura été récupéré auparavant lors de sa création.
      • perimeter_id correspond au périmètre que vous souhaitez associer au client.

    Supprimer un périmètre associé à un client

    Supprimer un périmètre implique d’utiliser un HTTP POST pour accéder à la méthode removeCustomerIsIn.

    https://[host]/calinda/hub/selling/model/customerisin/delete?action=removeCustomerIsIn

    INPUT json à mettre en payload de la requête :

    {
"customer_number" : Mi4hNTgzNjA0NzMwMTI4LjgxNTUw,
"perimeter_id" : 11,
}
      • customer_number correspond au numéro du client auquel vous ajoutez un périmètre. Celui-ci aura été récupéré auparavant lors de sa création.
      • perimeter_id correspond au périmètre que vous souhaitez dissocier du client.

    Les périmètres liés aux signataires

    Comme pour les clients, vous pouvez attribuer un ou plusieurs périmètres à vos signataires. Pour les gérer via API, vous pouvez utiliser la méthode addContractorIsIn pour ajouter un périmètre à un signataire et la méthode removeContractorIsIn pour le supprimer.

    Cette fonctionnalité est disponible à partir de SELL&SIGN version 4.0.

    Ajouter un périmètre à un signataire

    Avec un POST, vous pouvez appeler la méthode addContractorIsIn.

    https://[host]/calinda/hub/selling/model/contractorisin/create?action=addContractorIsIn

    INPUT json à mettre en payload de la requête :

    {
"contractor_id" : 123,
"perimeter_id" : 12,
}
      • contractor_id correspond à l’identifiant de la personne qui va signer. Son identifiant aura été récupéré auparavant lors de la création de celui-ci.
      • perimeter_id correspond au périmètre que vous souhaitez associer au signataire.

      Supprimer un périmètre associé à un signataire

      Supprimer un périmètre implique d’utiliser un HTTP POST pour accéder à la méthode removeContractorIsIn.

      https://[host]/calinda/hub/selling/model/contractorisin/delete?action=removeContractorIsIn

      INPUT json à mettre en payload de la requête :

      {
"contractor_id" : 123,
"perimeter_id" : 12,
}
        • contractor_id correspond à l’identifiant de la personne qui va signer. Son identifiant aura été récupéré auparavant lors de la création de celui-ci.
        • perimeter_id correspond au périmètre que vous souhaitez dissocier du signataire.

        Les périmètres liés aux contrats

        Même les contrats peuvent être affectés à un périmètre. Pour cela, vous pouvez utiliser la méthode addContractIsIn pour ajouter un périmètre à un contrat et la méthode removeContractIsIn pour le supprimer.

        Cette fonctionnalité est disponible à partir de SELL&SIGN version 4.0.

        Ajouter un périmètre à un contrat

        Avec un POST, vous pouvez appeler la méthode addContractIsIn.

        https://[host]/calinda/hub/selling/model/contractisin/create?action=addContractIsIn

        INPUT json à mettre en payload de la requête :

        {
"contract_id" : 12345,
"perimeter_id" : 12,
}
          • contract_id correspond à l’identifiant du contrat à signer. Son identifiant aura été récupéré auparavant lors de la création de celui-ci.
          • perimeter_id correspond au périmètre que vous souhaitez associer au contrat.

        Supprimer un périmètre associé à un contrat

        Supprimer un périmètre implique d’utiliser un HTTP POST pour accéder à la méthode removeContractIsIn.

        https://[host]/calinda/hub/selling/model/contractorisin/delete?action=removeContractIsIn

        INPUT json à mettre en payload de la requête :

        {
"contract_id" : 12345,
"perimeter_id" : 12,
}
          • contract_id correspond à l’identifiant du contrat à signer. Son identifiant aura été récupéré auparavant lors de la création de celui-ci.
          • perimeter_id correspond au périmètre que vous souhaitez dissocier du contrat.

        En cas d'erreur HTTP

        Une erreur HTTP 400 peut indiquer le manque d’un attribut, d’une valeur inappropriée. Le message joint à l’erreur vous permettra de trouver sa cause. En cas d’erreur HTTP 500, vous pouvez contacter le support ici : https://support.sellandsign.com en insérant votre requête dans le ticket.