Les Smartfields dont représentés dans l'API par de Propriétés des contrats. Vous pouvez donc les gérer avec les appels concernant les ContractProperty.
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.
Ecrire dans une propriété / un smartfield
Pour assigner une valeur à 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é (collecte).
Lire une propriété / un smartfield
Pour récupérer la valeur d'une propriété / un smartfield, 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é (collecte).
Modifier la valeur d'une propriété / un smartfield
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.
Gérer les options des contrats avec parcours
Si vous avez des parcours de signature SELL&SIGN, vous avez à la place des Smartfields / propriétés de contrat des éléments plus structuré : les Options. La différence réside dans le fait que les options sont typées et correspondent à un schema / meta-modèle de données prédéfini dans votre parcours.
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"}