API : Définir une collecte

Vous souhaitez recueillir des informations auprès de vos signataires. Que ce soit pour ajouter des annexes ou pour remplir un formulaire à votre dossier de preuves, vous pouvez réaliser une collecte en attribuant à chaque élément un caractère obligatoire ou optionnel.

Vous pouvez alors attribuer un type de fichier particulier, tout comme un type de champ spécifique, pour prédéfinir et encadrer l’information à recueillir, avec par exemple : date, choix multiple, texte, nombre, etc.

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

Collecter des annexes

Vous devez connaître l’identifiant du contrat (id de l’objet), et faire l’appel suivant en POST.

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

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

    {
    "contract_id": 123,
    "field_type": "IMAGE",
    "gatherable_by": "first_contractor",
    "id": -1,
    "input_filter": "{"filetype" : ["*"], "size" : "100", 
    "nbfile" :1}",
    "key": "CNI",
    "placeholder": "CNI",
    "required": false,
    "to_fill_by_user": false,
    "used_by_contract": false,
    "value": "",
}

    En retour vous recevrez une structure identique mais avec un id constitué.

      • contract_id correspond à l’identifiant du contrat pour lequel vous souhaitez obtenir une collecte d’informations.
      • field_type “IMAGE” sera toujours à cette valeur pour les annexes, même si vous avez besoin de collecter un autre type de binaire.
      • gatherable_by actuellement toujours défini à la valeur “first_contractor” pour spécifier à quel signataire l’information doit être demandée. Réservé pour un usage futur.
      • id permettrait de mettre à jour les données, mais ici, nous recherchons une création.
      • input_filter permet de stocker ici une description du type de fichier attendu à travers son filetype (qui peut être un Content-Type ou une extension), la taille maximale ou la quantité maximale de fichiers.
      • key est votre identifiant de propriété.
      • placeholder votre label qui apparaîtra lors de la collecte auprès du signataire
      • required true ou false permettant de rendre la demande obligatoire ou non pour réaliser la signature.
      • to_fill_by_user false <deprecated> permettait de piloter l’interface v3 et la collecte n’est pas supportée par cette version v3.
      • used_by_contract false dans le cas d’une demande de collecte d’annexes car elles ne seront pas utilisées comme élément dans le fichier pdf ‘contrat’.
      • value vide dans le cas d’une collecte d’annexes.

    Collecter des champs avec les Smartfields®

    L’ajout de Smartfields® dans vos documents est une fonctionnalité exclusive proposée par la solution SELL&SIGN. Inclue gratuitement dans toutes nos offres. Ils vous permettront de gagner un temps précieux et rendront vos documents, envoyés pour signature dans l’application, puissants.

    Lorsque vous envoyez votre contrat pour collecte, c’est le premier signataire qui est chargé de fournir les informations. Vous utilisez un HTTP POST pour appeler la méthode getOrCreateContractProperty.

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

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

    {
	"contract_id" : 123,
	"field_type" : "TEXT",
	"gatherable_by" : "first_contractor",
	"id" : 1234,
	"input_filter" : "[]",
	"key" : "Nom",
	"placeholder" : "Nom",
	"required" : false,
	"to_fill_by_user" : true,
	"used_by_contract" : true,
	"value" : "",
}

    En retour vous recevrez une structure identique mais avec un id constitué.

      • contract_id correspond à l’identifiant du contrat pour lequel vous souhaitez obtenir une collecte d’annexes.
      • field_type “TEXT” pour exprimer la saisie d’un texte.
      • gatherable_by actuellement toujours défini à la valeur “first_contractor” pour spécifier à quel signataire l’information doit être demandé. Réservé pour un usage futur.
      • id permettrait de mettre à jour les données, mais ici, nous recherchons une création.
      • input_filter pas de filtre prévu pour ce type de champ.
      • key est votre identifiant de propriété.
      • placeholder votre label qui apparaîtra lors de la collecte auprès du signataire.
      • required true ou false permettant de rendre la demande obligatoire ou non pour réaliser la signature.
      • to_fill_by_user true <deprecated> permettait de piloter l’interface v3.
      • used_by_contract true : dans ce cas la valeur peut être exploitée sous la forme d’un smartfield prenant place dans le contenu du fichier pdf ‘contrat’.
      • value vide ou éventuellement votre valeur par défaut.

    Collecte d’informations auprès du signataire

    Il faut tout d’abord définir l’information à collecter au niveau de la personne qui sera signataire.

    On va ici demander la collecte du code postal du signataire. Nous pourrions faire la même chose avec n’importe quel autre champ signataire parmi « firstname », « lastname », « companyName », « registrationNumber », « civility », « email », « cellPhone », « address1 », « address2 », « postalCode », « city », « country », « phone », « jobTitle », « birthdate », « birthplace », « localisation ».

    Vous pouvez aussi demander la saisie de n’importe quel autre champ de votre choix, ou même de document tel que la CNI, ou autre.

    Utilisez un HTTP POST pour appeler la méthode createContractorProofDefiniton.

    https://[host]/calinda/hub/selling/model/contractproofdefinition/insert?action=createContractorProofDefinition

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

    {
	"contractor_id" : 1234,
	"file_amount" : 0,
	"file_extension_regex : "“,
	"file_size_max" : 0,
	"name: "postalCode",
	"required": false,
	"type": 0,
	"validity_duration":
}
      • 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.
      • file_amount permet de spécifier le nombre de fichiers attendus dans le cadre d’une demande de fichiers.
      • file_extension_regex permet de spécifier le type de fichiers attendus dans le cadre d’une demande de fichiers.
      • file_extension_regex permet de spécifier la taille maximale par fichier dans le cadre d’une demande de fichiers.
      • name le nom du champ parmi les noms disponibles par défaut (voir liste plus haut).
      • required true ou false pour désigner le caractère obligatoire de la saisie de ce champ.
      • type 0 pour un champ de la liste, ou 1 pour un fichier.
      • validity_duration durée en milliseconds pendant laquelle l’information sera valable.

    En retour vous recevrez une structure identique mais avec un id pour l’objet contractor_proof_definition constitué. Cet identifiant sera utilisé durant l’appel suivant.

    Ensuite, il faut désigner lors de quelle transaction/quel contrat nous allons demander l’information à la personne signataire.

    Utilisez un HTTP POST pour appeler la méthode createRequestProof.

    https://[host]/calinda/hub/selling/model/requestproof/insert?action=createRequestProof

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

    {
	"contract_id" : 12345
	"contractor_proof_definition_id" : 123,
}
      • contractor_id correspond à l’identifiant du contrat durant lequel l’information sera demandée au signataire.
      • contractor_proof_definition_id correspond à l’identifiant récupéré lors de l’appel précédent.

    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.