Inscription en ligne

La documentation suivante décrit la mise en place, via API, d'une inscription en ligne, notamment celle d'un client déjà prospect dans un club.

Vérifier qu'un usager n'éxiste pas déjà

Dans Resamania, un contact est unique de par son adresse email : Il est impossible d'utiliser 2 fois la même adresse email pour un même clientToken.

Si vous venez à vouloir créer un contact alors que son adresse email est déjà utilisée sur ce clientToken vous aurez alors une erreur api.error.contact.email-already-used.

Dans un parcours utilisateur classique, il est donc recommendé de demander à l'usager son adresse email et de faire la vérification de son existence ainsi :

Example.requestExample.response

bash

----------------------------------------------------[--------v--------]
curl --location 'https://{{baseUrl}}/{{clientToken}}/contacts?email={{email}}' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer {{bearer}}' \
--header 'x-user-club-id: {{clubId}}' \
--header 'x-user-network-node-id: {{networkNodeId}}'

json

{
    "@context": "/demoapi/contexts/Contact",
    "@id": "/demoapi/contacts",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "@id": "/demoapi/contacts/2974221",
            "@type": "http://schema.org/Person",
            "number": "C2974221",
            "address": {
                "@id": "/demoapi/addresses/14284392",
                "@type": "Address",
                "addressCountry": "France",
                "addressCountryIso": "FR",
                "addressLocality": "NICE",
                "postalCode": "06000",
                "streetAddress": "1 The Street",
                "supplement": ""
            },
            "birthDate": "1990-01-01",
            "email": "[email protected]",
            "familyName": "John",
            "gender": null,
            "givenName": "Test",
            // ...
        }
    ],
    //...
}

Attention

L'email fournit en paramètre doit impérativement être url-encodé : [email protected] doit être john%2Btest%40email.tld

Cas d'une authentification http://contactclientcredentials

Pour ce mode d'authentification vous devez obligatoirement avoir un contactId au préalable Pour faire la recherche de contact, vous devrez donc utiliser un autre client oAuth avec des authorizations plus larges Nous ne mélangeons pas les grant_type ayant un scope contact avec ceux ayant un scope plus large pour des raisons de sécurité.

Cas des chaînes de club

L'exemple ci-dessus convient bien aux situation où le clientToken ne contient qu'un seul club.

Dès lors qu'un clientToken contient plusieurs clubs (cf. documentation dédiée), vous risquez de devoir faire une recherche de contact sur le réseau en utilisant l'endpoint /:clientToken/network/contact_search?email=.

Cet endpoint fonctionne de la même manière que le GET /:clientToken/contacts?email= décrit ci-dessus, aux différences

que les résultats sont sur l'ensemble des clubs du réseau.
que les résultats sont une vue limitée des données du contact

json

{
    "@context": "/demoapi/contexts/Contact",
    "@id": "/demoapi/contacts",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "@id": "/demoapi/contacts/10296819",
            "@type": "http://schema.org/Person",
            "number": "ZM14314719",
            "birthDate": "1992-04-22",
            "familyName": "Doe",
            "gender": "female",
            "givenName": "Justine",
            "pictureId": null,
            "clubId": "{{clubId}}}",
            "state": "old_client",
            "partialPhoneNumber": "******1615"
        }
    ],
    "hydra:totalItems": 1,
    // ..
}

S'il retourne une réponse, il convient donc de récupérer le clubId du contact concerné si vous souhaitez procéder à une migration du contact (cf. plus bas) dans le cas où le contact est prospect

Un contact non prospect présent dans un autre club ne peut pas être migré vers un autre club.

Créer un nouvel usager

En créant un nouvel usager, ce dernier peut prendre soit le statut (state) temp, si vous souhaitez créer un contact temporaire (voir ci-dessous) ou prospect (valeur par défaut).

Les champs requis

Par défaut, les champs obligatoirement requis sont email, familyName, givenName et birthDate. Dès lors que vous aurez à faire une vente pour ce contact, vous devrez également fournir son adresse postale (address). S'il y a un contrat ou un mandat à signer, vous devrez également fournir le numéro de téléphone portable (mobile).

D'autres champs peuvent être requis

Les champs requis dépendent parfois du clientToken, si d'autres champs vous sont demandés (ex. vous obtenez une erreur required), celà provient généralement de la configuration du client.
Contactez votre client pour savoir quels champs doivent être requis dans votre cas d'usage : Un champs que vous ne fourniriez pas, sera un champs réclamé lorsqu'un employé souhaitera modifier la fiche de l'usager depuis Resamania.
S'il faut adapter la configuration des champs requis pour les contact en provenance de votre application tout en conservant des obligations dans Resamania, contacter le service API afin de créer une configuration de champs de fiche contact dédiée.

Source du contact

Il est important pour votre client qu'il connaisse la provenance de ses contacts, et utile pour vous qu'il puisse vous attribuer sa création.

Pour se faire, les fiches contacts détiennent un champs sourceId qui fait référence à une source. Nous vous renvoyions vers l'api-reference suivante pour retrouver comment lister et créer une source.

Attention: vous devrez recréer cette source lorsque vous passerez en production.

Requête de création

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.

Example.requestExample.response

bash

curl --location 'https://{{baseUrl}}/{{clientToken}}/contacts' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer {{bearer}}' \
--header 'x-user-club-id: {{clubId}}' \
--header 'x-user-network-node-id: {{networkNodeId}}' \
--header 'Content-Type: application/json' \
--data '{
  "familyName":"DEV",
  "givenName":"Test",
  "gender":"male",
  "clubId": "{{clubId}}",
  "birthDate":"2000-01-01",
  "email": "{{fakeEmail}}",
  "mobile":"+336123456789",
  "sourceId": "{{sourceId}}",
  "address": {
    "addressCountry":"France",
    "addressLocality":"Toulon",
    "streetAddress":"52 chemin du test",
    "postalCode":"83390"
  }
}'

json

{
    "@context": "\/demoapi\/contexts\/Contact",
    "@id": "\/demoapi\/contacts\/2974340", -- L'id du contact à réutiliser dans vos appels suivants
    "@type": "http:\/\/schema.org\/Person",
    "number": "C2974340",
    "address": {
        "@id": "\/demoapi\/addresses\/14285613",
        "@type": "Address",
        "addressCountry": "France",
        "addressCountryIso": "FR",
        "addressLocality": "Toulon",
        "postalCode": "83390",
        "streetAddress": null,
        "supplement": ""
    },
    "birthDate": null,
    "email": "{{email}}",
    "familyName": "Doe",
    "gender": null,
    "givenName": "John",
    "pictureId": null,
    "tags": [],
    "clubId": "{{clubId}}",
    "landline": null,
    "mobile": null,
    // ...
    "parentalIdentificationValidated": false,
    "state": "prospect",
    "initialSalepersonId": null,
    //...
}

Cas d'un client déjà prospect dans un club

Il est impossible de créer un nouveau contact alors que celui-ci est déjà connu d'un club.
Cependant, certains services extérieurs ont besoin de créer un nouveau contact alors que celui-ci existe déjà.
Nous avons ajouté deux points d'API pour pallier ce problème.

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.

Glossaire des notions clés

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

Le contact prospect

Il s’agit du client existant.
Son statut doit être temp, on le nommera contact source dans ce document.

Le contact temporaire

Il s’agit du client que l'on veut inscrire.
Son statut doit être prospect, on le nommera contact target dans ce document.

Le club

Il s’agit du club où les informations du contact target seront déplacées.

La vente : sale

Une sale correspond à un panier. Elle permet de regrouper une liste d’articles qui seront ensuite vendus au contact.

Macro process et prérequis

Comme indiqué précédemment, vous devez connaître les informations suivantes :

le contact source
le contact target
le club
la vente (sale)

Le processus du transfert des informations contact se fait en deux appels :

Un premier permettant de migrer les données du contact source vers le contact target :
Migration des informations
Un deuxième permettant de modifier la vente afin de mettre les informations du contact lié à jour :
Mise à jour des informations dans la vente

Migration des informations

Ce point d'API sert pour la migration des informations du contact source vers contact target.

Rappel :

Le contact source doit avoir le statut prospect
Le contact target doit avoir le statut temp
Le club du contact source doit être différent du contact target

Important: pour cet appel, il faut être connecté en tant que contact source

PUT `/{clientToken}/contacts/{contactSourceId}/migrate`

paramètre	description	exemple
`targetContactId`	Identifiant du contact sous forme d'IRI	`/{clientToken}/clubs/1`
`targetClubId`	Identifiant du club sous forme d'IRI	`/{clientToken}/clubs/1`

Exemple

Migration du Contact 1 (prospect) vers le Contact 2 (temporaire) / Club 1

Query

PUT /{clientToken}/contacts/1/migrate

Body

json5

{
    "targetContactId": "/{clientToken}/contacts/2",
    "targetClubId": "/{clientToken}/clubs/1"
}

Réponse 204 Migration processed

Mise à jour des informations dans la vente

Ce point d'API sert à mettre à jour les informations du contact dans la vente.

Les informations mises à jour sont :

L'identifiant du contact : contactId
Le numéro du contact : contactNumber
le nom du contact : contactFamilyName
le prénom du contact : contactGivenName

PUT `/{clientToken}/sale/{saleId}/update_contact`

Exemple

Mise à jour des informations de la vente 33

Query

PUT /{clientToken}/sale/33/update_contact

Réponse 204 Process finished

Inscription en ligne ​

Vérifier qu'un usager n'éxiste pas déjà ​

Cas des chaînes de club ​

Créer un nouvel usager ​

Les champs requis ​

Source du contact ​

Requête de création ​

Retrouvez ce scénario dans notre collection Bruno

Cas d'un client déjà prospect dans un club ​

Retrouvez ce scénario dans notre collection Bruno

Glossaire des notions clés ​

Le contact prospect ​

Le contact temporaire ​

Le club ​

La vente : sale ​

Macro process et prérequis ​

Migration des informations ​

PUT /{clientToken}/contacts/{contactSourceId}/migrate ​

Exemple ​

Mise à jour des informations dans la vente ​

PUT /{clientToken}/sale/{saleId}/update_contact ​

Exemple ​

Inscription en ligne

Vérifier qu'un usager n'éxiste pas déjà

Cas des chaînes de club

Créer un nouvel usager

Les champs requis

Source du contact

Requête de création

Cas d'un client déjà prospect dans un club

Glossaire des notions clés

Le contact prospect

Le contact temporaire

Le club

La vente : sale

Macro process et prérequis

Migration des informations

PUT `/{clientToken}/contacts/{contactSourceId}/migrate`

Exemple

Mise à jour des informations dans la vente

PUT `/{clientToken}/sale/{saleId}/update_contact`

Exemple