Contrat, mandat et signature

Retrouvez ce scénario dans notre collection Bruno

Gagnez du temps dans votre implémentation en observant l'enchaînement des appels et en récupérant les requêtes directement depuis Bruno.

La documentation suivante décrit la mise en place, via API, d'un mandat de prélèvement attaché à un contact, l'affichage du contrat d'une vente, ainsi que la signature dématérialisée de ces pièces.

Glossaire des notions clés

Avant d'aller plus loin, soyons certains que nous parlons des mêmes notions.

Le contact

Il s'agit du client qui s'abonne au club. Pour ne pas confondre avec son éventuel statut (prospect, client, ancien client ...), on le nommera contact dans ce document.

Le mandat

Le mandat est une autorisation de prélèvement sur un compte bancaire du contact. Elle lie donc un club qui souhaite prélever, à un compte bancaire qui sera prélevé.

Le contrat

Si le produit vendu est associé à un modèle de contrat (la propriété product.contractModel est renseignée) alors un contrat est automatiquement généré avec la vente, contrat qu'il faut signer.

Macro process et prérequis

Comme indiqué précédemment vous devez connaître les 2 principaux protagonistes :

• le club
• le contact

Selon ce qu'il y a à faire signer, le process suit les étapes suivantes :

1. Ajouter le mandat — uniquement si un mandat doit être créé
2. Afficher le contrat à l'usager — uniquement si un contrat a été généré avec la vente
3. Initier le processus de signature par SMS
4. Terminer le processus de signature

Bien sûr le contact doit posséder un numéro de téléphone mobile valide pour être éligible à la signature dématérialisée.

Ajouter le mandat

POST

/{clientToken}/mandates

WARNING

Tous les champs sont requis

paramètre	description	exemple
clubId	Identifiant du club sous forme d'IRI	/{clientToken}/clubs/1
contactId	Identifiant du contact ciblé par le mandat. Il s'agit d'une IRI et non d'un simple identifiant numérique	/{clientToken}/contacts/12345
contactFamilyName	Nom de famille du contact.	Doe
contactGivenName	Prénom du contact.	John
contactNumber	Numéro du contact.	423456
contactAddress[addressCountry]	Pays	France
contactAddress[addressCountryIso]	Pays	FR
contactAddress[addressLocality]	Ville	La Madeleine
contactAddress[postalCode]	Code postal	59110
contactAddress[streetAddress]	Adresse	41 rue du Général de Gaulle
holder	Titulaire du compte	John Doe
iban	Numéro du compte bancaire	DE15843988385047239833
bic	Identifiant de la banque	DEUTDEFF
bank	Nom de la banque	DEUTSCHE BANK AG
validFrom	date de début de validité du mandat	2019-06-21

Exemple

POST /{clientToken}/mandates

Body

{
    "clubId": "/{clientToken}/clubs/22",
    "contactId": "/{clientToken}/contacts/1",
    "contactFamilyName": "Doe",  
    "contactGivenName": "John",  
    "contactNumber": "1",  
    "contactAddress": { 
        "addressCountry": "France",
        "addressCountryIso": "FR",
        "addressLocality": "La Madeleine",
        "postalCode": "59110",
        "streetAddress": "41 Rue du Général de Gaulle"
    },
    "holder": "John Doe",
    "iban": "DE15843988385047239833",
    "bic": "DEUTDEFF",
    "bank": "DEUTSCHE BANK AG",
    "validFrom": "2019-06-21"
}

Réponse 201 Created

{  
   "@context":"\/clientToken\/contexts\/Mandate",
   "@id":"\/clientToken\/mandates\/373969",         // <-- identifiant du mandat
   "@type":"Mandate",
  // ...
}

Afficher le contrat à l'usager

Si le produit vendu est associé à un modèle de contrat (la propriété product.contractModel est renseignée) alors un contrat est automatiquement généré avec la vente, contrat qu'il faut signer.

Pour afficher visuellement le contrat au client, faites simplement un GET /:clientToken/sales/:saleId/contract, en retour vous récupérez le contenu raw du PDF à afficher.

curl --location 'https://.../demoapi/sales/12345/contract' \
--header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJOdDmWEJwl2Zqc' \
--header 'x-user-club-id: /onfit/clubs/2325' \
--header 'x-user-network-node-id: /onfit/network_nodes/2229' \
--header 'x-gravitee-api-key: xxx-yyy-zzz'

Note

Vous obtenez le contenu raw du PDF, c'est donc à vous de créer l'endpoint qui distribue ce contenu (avec les bonnes en-têtes http).

Initier le processus de signature par SMS

Le processus de signature dématérialisée passe donc par l'envoi d'un SMS au contact. Ce SMS contient un code qu'il devra utiliser pour valider la signature dans l'étape suivante.

Ce processus est le même pour le contrat ou pour le mandat :

• Si vous n'avez qu'un contrat, fournissez le saleId (/:clientToken/sales/:id) comme targetId
• Si vous n'avez qu'un mandat, fournissez le mandateId (/:clientToken/mandate/:id) comme targetId
• Si vous avez un contrat et un mandat à signer, vous pouvez signer les deux en un seul appel en renseignant les deux identifiants dans un tableau targetIds

POST /{clientToken}/signature_requests

paramètre	description	exemple
contactId	Identifiant du contact sous forme d'IRI	/{clientToken}/contacts/1
targetId	Identifiant du mandat à signer sous forme d'IRI	/{clientToken}/mandates/373969
targetIds	Tableau d'identifiants (sous forme d'IRI) des pièces à signer	/{clientToken}/mandates/373969

Exemple

POST /{clientToken}/signature_requests

Body

{
    "contactId": "/{clientToken}/contacts/1",
    // "targetId": "/{clientToken}/mandates/373969"
    "targetIds": [
        "/{clientToken}/mandates/373969",
        "/{clientToken}/sales/936973"
    ]
}

Réponse 201 Created

{  
   "@context":"\/clientToken\/contexts\/SignatureRequest",
   "@id":"\/clientToken\/signature_requests\/3451",         // <-- identifiant du processus de signature
   "@type":"SignatureRequest",
  // ...
}

Terminer le processus de signature

Une fois le SMS reçu l'application souhaitant orchestrer la signature devra récolter le code en provenance du contact ciblé par le mandat et terminer le processus de signature en validant ce code.

POST

/{clientToken}/signature_requests/{signatureRequestId}/transitions

paramètre	description	exemple
signatureRequestId	Identifiant du processus de signature créé précédemment	3451
transition	Type de transition souhaitée. Les valeurs possibles sont validate ou cancel	validate
code	Code de validation reçu par SMS	1234

Exemple

POST /{clientToken}/signature_requests/3451/transitions

Body

{
    "transition": "validate",
    "code": "94852"
}

Réponse 201 Created