API : Création du contrat à faire signer

Pour créer un contrat, on peut utiliser la méthode createContract de la classe Contract.

Une façon rapide d’appeler cette méthode est d’utiliser l’API REST sous la forme d’un HTTP GET (la solution à privilégier étant d’utiliser un HTTP POST) :

https://[host]/calinda/hub/selling/model/contract/create?action=createContract&[paramètres]

Paramètres obligatoires
- date : date de démarrage de la transaction (nombre de ms depuis le 1 jan 1970)
- vendor_email : adresse e-mail du vendeur (personne qui fait signer). Doit correspondre à une licence utilisateur SELL&SIGN.
- customer_number : numéro du client auquel est associé le contrat (voir étape de création du client)
- contract_definition_id : identifiant du modèle de contrat. Pour un contrat sans options dont vous fournissez le PDF, utiliser l’identifiant du modèle de contrat générique dans votre licence (voir comment le récupérer sur cette page)
- closed : utiliser false
- customer_entity_id : mettre -1
- keep_on_move : false sauf si vous souhaitez permettre de synchroniser le contrat et le faire signer sur tablette hors connexion avec l’application SELL&SIGN en face à face
Paramètres facultatifs
- message_title : le sujet du courriel envoyé (pour une signature avec SELL&SIGN à distance). Si vide, le sujet par défaut est utilisé.
- message_body : le corps du courriel envoyé (hors en-têtes et pieds de page définis par votre licence). Si vide, le corps de texte par défaut est utilisé.
- filename : le nom à utiliser pour le fichier PDF signé.
- transaction_id : laisser vide

Exemple :

https://cloud.sellandsign.com/calinda/hub/selling/model/contract/create?action=createContract&date=1455794147546&vendor_email=amermod%40calindasoftware.com&closed=false&customer_number=AM201603021055&contract_definition_id=1&message_title=&message_body=&filename=&keep_on_move=false&transaction_id=&customer_entity_id=-1&j_token=[votre token d'authentification]

Retour :

{"id":18758,
"date":1455794147546,
"documentToken":"",
"vendorEmail":"amermod@calindasoftware.com",
"closed":false,
"transactionId":"",
"status":"OPEN",
"customerEntityId":-1,
"contractDefinitionId":1,
"customerNumber":"AM201603021055",
"syncTimer":1456933757841,
"messageTitle":"",
"messageBody":"",
"filename":"",
"keepOnMove":0}

Mémorisez l’id du contrat retourné par cet appel, afin de l’utiliser pour charger le document PDF et démarrer la signature.

Chargement du document PDF à faire signer

Dans le cas général, le modèle de contrat que vous avez désigné peut générer lui-même le contrat PDF à partir d’un contrat type et d’options.

Si vous fournissez le document PDF à faire signer, utilisez la définition de contrat « PDF ADHOC » (l’identifiant de ce modèles de contrat dans votre licence peut être retrouvé en utilisant la requête présentée en exemple ici), et chargez votre PDF comme suit par un HTTP POST :

HTTP POST 

https://[host]/calinda/hub/selling/do?m=uploadContract&id=[contract id]&j_token=[votre token d'authentification]

[Avec le fichier PDF en HTTP Part (multipart/form-data)]

Exemple :

https://cloud.sellandsign.com/calinda/hub/selling/do?m=uploadContract&id=18758&j_token=[votre token d'authentification]
Content-Length 98094	 	
Content-Type multipart/form-data; 
boundary=---------------------------17051144681837078108139936823737

[le fichier PDF "Devis auto.pdf"]

Retour :

{"id":18758,
"date":1455794147546,
"documentToken":"[Token généré automatiquement]",
"vendorEmail":"amermod@calindasoftware.com",
"closed":false,
"transactionId":"",
"status":"OPEN",
"customerEntityId":0,
"contractDefinitionId":1,
"customerNumber":"AM201603021055",
"syncTimer":1456933757841,
"messageTitle":"",
"messageBody":"",
"filename":"Devis auto.pdf",
"keepOnMove":0}

Ajout des signataires au contrat

Il suffit à présent d’associer au contrat les signataires définis précédemment, en précisant leur mode de signature.

https://[host]/calinda/hub/selling/model/contractorsforcontract/insert?action=addContractorTo&[paramètres]

Paramètres obligatoires
- contract_id : identifiant du contrat récupéré précédemment
- contractor_id : identifiant du signataire récupéré lors de sa définition à l’étape précédente
- signature_mode : mode de signature du signataire (voir encadré)
- signature_status : mettre la chaîne « NONE »
Paramètres facultatifs
- signature_id : laisser vide
- signature_date : laisser vide

Exemple :

https://cloud.sellandsign.com/calinda/hub/selling/model/contractorsforcontract/insert?action=addContractorTo&contract_id=18758&contractor_id=11522&signature_mode=2&signature_status=&signature_id=&signature_date=&j_token=[votre token d'authentification]

Retour :

{"id":18693,
"contractId":18758,
"contractorId":11522,
"signatureMode":2,
"signatureStatus":"",
"signatureId":"",
"signatureDate":-1,
"lastModificationDate":1456937410346,
"lastModificationPlace":"SERVER"}

Les modes de signature

Pour gérer les différents modes de signature lors de la création d'un contrat, de l'envoi d'un contrat en un seul appel, vous devez renseigner des paramètres obligatoires de type :

signature_mode
mode

Ces paramètres correspondent donc aux modes de signature que vous choisissez en fonction du paramétrage de votre environnement. Ceux-ci peuvent prendre les valeurs de 1 à 12, comme présentées dans le tableaux ci-après.

	Contralia par DOCAPOSTE (avec Certinomis)	La Signature par SELL&SIGN (avec Certinomis)
Face-à-face SMS : Signature par code à usage unique envoyé immédiatement par SMS (INSTANT_OTP)	1	9
Face-à-face PAD : Signature tactile immédiate (INSTANT_PAD)	2	10
Mail + SMS : Envoi d’un mail pour une signature différée par code SMS (MAIL_OTP)	3	11
Mail + Collecte + SMS : Envoi d'un email avec collecte d'informations ou de documents pour une signature différée par code SMS (MAIL_OTP), dans le cas d’un contrat avec collecte. Ce signataire sera sollicité avant les autres signataires à distance.	6	12
Destinataire en copie : Envoi d'un mail à une personne en copie	7	7
Prévalidation : Envoi du contrat à un prévalidateur qui va déterminer si le contrat est valide, il sera par la suite envoyé aux signataires	8	8

Mise à jour du mode de signature

Il faut connaître l’ identifiant du signataire sur le contrat (id de l’objet retourné), et faire l’appel suivant en POST.

https://[host]/calinda/hub/selling/do?m=changeSignatureMode&[paramètres]

Paramètres obligatoires

cfc_id: identifiant du signataire sur le contrat
rank: ordre du signataire
mode : mode de signature du signataire (voir encadré)

Exemple :

https://cloud.sellandsign.com/calinda/hub/selling/do?m=changeSignatureMode&cfc_id=[cfc_id]&rank=1&mode=2&j_token=[votre token d'authentification]

Retour :

{"Succeed":true}

Mise en signature du contrat

Une fois le contrat prêt à être signé, il convient de le soumettre à la ratification par l’utilisation de l’appel contractReady :

https://[host]/calinda/hub/selling/do?m=contractReady&c_id=[contract id]

Cela va notamment provoquer l’envoi du mail pour signature si certains signataires sont définis pour signature à distance (MAIL+OTP). Cela provoquera également la mise à disposition du contrat sur les tablettes à la prochaine synchronisation si des signataires sont en face à face et que l’attribut keep_on_move est défini sur la transaction.

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.