API : Définition des valeurs des options et Smartfields

Les options et leurs définitions
Lorsque le contrat est généré par SELL&SIGN sur la base d’un contrat type, il est fréquent que certaines parties soient à remplir. SELL&SIGN propose la possibilité de définir des types de contrat en spécifiant son contenu. Dès lors qu’un contrat de ce type est créé, toutes les options le composant peuvent contenir une valeur.

Il est possible de définir la valeur de ces options via l’API.

https://[host]/calinda/hub/selling/model/option/update?action=getOrCreateOption

input json:
{
  'contract_id' : [identifiant du contrat],
  'element_definition_id': [identifiant de l'element pour notre option],
  'value': [la valeur que nous voulons donner à notre option]

Pour définir cette valeur, nous avons donc besoin d’un identifiant d’élément. Cet identifiant pourra être gardé aussi longtemps que le contrat type ne sera pas modifié.
Pour le trouver, il faudra d’abord résoudre l’option que l’on veut adresser.

Récupération d’une option à remplir
Un contrat type est donc composé de définition d’option. Pour définir la valeur associée pour un contrat donné, il faut donc déjà récupérer la définition d’option concernée :

https://[host]/calinda/hub/selling/model/optiondefinition/read?action=getOptionDefinitionByName

json input:
{ 
  'option_definition_name': [ clé de la definition ],
  'contract_definition_id': [ identifiant du contrat type]
}

On obtient une retour structurée de la façon suivante :

{
    "id": 34,
    "name": "calinda_EDL_dossier",
    "type": "TEXT",
    "description": "",
    "page_id": 20,
    "optionDefGroupId": 0,
    "syncTimer": 1469626143968,
    "helpId": 1,
    "userIdentifier": "",
    "lastModificationPlace": "SERVER",
    "required": false
}

Une option pouvant être, comme dans l’exemple ci dessus, un simple champ texte ou bien une liste à choix multiple, chaque définition d’option va être décomposée en élément. Un seul élément dans le cas d’un champ texte, ou bien N éléments dans le cas d’une liste.
Nous allons donc avoir besoin de savoir à quel élément, la valeur de notre option va être assignée.

Récupération de l’élément concerné par la valeur de notre option

https://[host]/calinda/hub/selling/model/elementdefinition/read?action=getElementDefinitionByName

json input:
{
  'element_definition_name': [ clé de l'élément ],
  'option_definition_id': [ identifiant de l'option definition récupéré plus haut]
}

On obtient la réponse suivante :

{
    "id": 90,
    "name": "calinda_EDL_dossier",
    "type": "TEXT",
    "description": "none",
    "option_definition_id": 34,
    "sync_timer": 1469626143971,
    "lastModificationPlace": "SERVER",
    "value": "",
    "range": "",
    "image_token": ""
}

Nous avons donc obtenu l’identifiant que nous recherchions. Cette information peut être gardée aussi longtemps que le contrat type n’est pas modifié. Il n’est donc pas nécessaire de réaliser toutes ces étapes à chaque nouveau contrat!

Assignons une valeur à notre champ de type TEXT
Comme nous l’avons vu au début la méthode à utiliser est :

https://[host]/calinda/hub/selling/model/option/update?action=getOrCreateOption

input json:
{
  'contract_id' : [identifiant du contrat],
  'element_definition_id': [identifiant de l'element pour notre option],
  'value': [la valeur que nous voulons donner à notre option]
}

L’identifiant du contrat est donc celui que l’on obtient sur la création du contrat (voir Création du contrat à faire signer)
Pour notre cas, avec un contrat créé d’identifiant 100, nous obtiendrons l’appel suivant :

{
  'contract_id': 100,
  'element_definition_id': 34,
  'value': 'la valeur de notre option'
}

On obtient en retour si tout s’est bien passé :

{
    "id": 100,
    "contractId": 100,
    "elementDefinitionId": 34,
    "syncTimer": 1456828557186,
    "value": "la valeur de notre option",
    "lastModificationPlace": "SERVER"
}

Ajout de propriétés
Nommées aussi Smartfields, ces propriétés peuvent être manipulées par l’API. Le nom de la propriété est issue du PDF du contrat. Ainsi un Smartfield représenté par [monChamp/] deviendra la propriété nommée ‘monChamp’ et sera accessible via cette API.

Pour créer une telle propriété réutilisable dans le fichier PDF, il suffit d’appeler :

https://[host]/calinda/hub/selling/model/contractproperty/insert?action=addContractProperty

input json :
{
  'key': [nom de la propriété à associer au contrat],
  'value': [la valeur de la propriété],
  'to_fill_by_user': [true pour que la valeur soit proposée à la saisie pour l'utilisateur, false pour que la propriété reste transparente],
  'contract_id': [identifiant du contrat concerné]
}

La réponse aura alors la forme :

{
    "id": 2815,
    "key": "monChamp",
    "value": "maValeur",
    "contractId": 897,
    "toFillByUser": false,
    "syncTimer": 1475749946068,
    "lastModificationPlace": "SERVER"
}

L’attribut ‘toFillByUser’ permet de laisser l’utilisateur remplir la valeur de la propriété.

Récupérer une propriété
Pour récupérer une propriété réutilisable dans le fichier PDF, il suffit d’appeler :

https://[host]/calinda/hub/selling/model/contractproperty/read?action=getContractPropertyFor

input json :
{
  'key': [nom de la propriété à associer au contrat],
  'contract_id': [id du contrat]
}

La réponse aura alors la forme :

{
    "id": 2815,
    "key": "monChamp",
    "value": "maValeur",
    "contractId": 897,
    "toFillByUser": false,
    "syncTimer": 1475749946068,
    "lastModificationPlace": "SERVER"
}

L’attribut ‘toFillByUser’ permet de laisser l’utilisateur remplir la valeur de la propriété.

Modification d’une propriété
Il est possible de modifier après coup la valeur de la propriété en se basant sur son identifiant :

https://[host]/calinda/hub/selling/model/contractproperty/update?action=setContractPropertyValue

input json :
{
  'id': [identifiant de la propriété],
  'value': [la valeur de la propriété]
}

Cette méthode retourne simplement un 200 OK pour une modification réussie.

API : Définition des valeurs des options et Smartfields
Rate this post