Inscription du client

Comment suivre ce chapitre

Entrées : Données saisies et identifiants de référence ; commencez avec le token GUEST.

Étapes et résultat attendu : Effectuez toutes les vérifications dans l’ordre. L’identité du client et la paire de tokens retournées constituent le contexte des appels suivants.

Alternatives et actions ultérieures : L’auto-inscription est le parcours principal. Utilisez l’inscription administrative uniquement si votre intégration crée des clients pour leur compte.

Code source des DTO : CivilStatusOutputModel, ClientOutputModel, CountryOutputModel, GenderOutputModel, LanguageOutputModel, LegalAcceptanceOutputModel, NationalityOutputModel, PensionSituationOutputModel, RegistrationFirstFactorOutputModel, RegistrationSecondFactorOutputModel, RegistrationThirdFactorOutputModel, TaxLiabilityOutputModel

Les variables affectées dans un bloc précédent sont réutilisées dans les suivants. Les saisies du client proviennent de votre interface. Conservez les identifiants et les valeurs de référence dans le contexte du client ; ne recréez pas ce contexte à chaque étape.

Les exemples utilisent des classes utilitaires communes. Consultez Classes utilitaires communes : code source C# et Java complet avant de copier un exemple.

Prérequis : Coordonnées du client, consentTimestamp recueilli au moment de l’accord, phoneNumberPrefix, phoneNumberNumber et mot de passe choisi par le client. Choisissez l’auto-inscription avec GUEST ou l’inscription administrative avec ADMIN.

À conserver pour la suite : userId. L’auto-inscription retourne aussi accessToken, refreshToken et validUntil. Pour l’inscription administrative, conservez le token ADMIN existant.

Remarque

L’inscription demande l’adresse e-mail du client. Elle doit être unique dans la base WMS de l’environnement cible. Toute inscription avec une adresse déjà présente échoue.

Deux possibilités d’inscription sont disponibles : auto-inscription du client ou inscription administrative du client.

Auto-inscription du client

Le client peut s’inscrire lui-même en fournissant les informations étape par étape. Cette inscription en trois étapes exige un token GUEST. Il reçoit d’abord un code par e-mail, puis un code par SMS et enfin un token CLIENT pour les appels HTTP suivants. Le champ ValidUntil retourné indique son expiration.

Première étape d’inscription

Entrées : Prénom, nom, e-mail, mot de passe, date du consentement et référence du genre.
Action : Commencez l’auto-inscription et demandez la vérification de l’e-mail.
À conserver / résultat attendu : Conservez les saisies et recueillez emailVerificationCode pour la dernière étape.

La première étape demande le genre, le prénom, le nom et l’e-mail du client. Utilisez le token GUEST dans le client HTTP. Le client reçoit un code de vérification par e-mail. Conservez-le pour la demande finale ; la demande suivante lance la vérification du numéro mobile.


httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", guestToken);
// clientEmail, clientName and clientSurname are entered by the client.
var gender = await httpClient.GetFromJsonAsync<GenderOutputModel>("/api/v1/genders/code/MALE");
var payload = JsonConvert.SerializeObject(new
{
    GenderId = gender.Id,
    Name = clientName,
    Surname = clientSurname,
    EmailAddress = clientEmail
});
var sContent = new StringContent(payload, Encoding.UTF8, "application/json");
var httpResponseMessage = await httpClient.PostAsync("api/v1/users/registration/first-factor", sContent);
httpResponseMessage.EnsureSuccessStatusCode();
var resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var firstFactorRegistrationResult = JsonConvert.DeserializeObject<RegistrationFirstFactorOutputModel>(resultAsString);

								
// clientEmail, clientName and clientSurname are entered by the client.

// First-factor registration
HttpRequest genderRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("genders/code/MALE"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

HttpResponse<String> response = httpClient.send(genderRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
GenderOutputModel genderObj = new Gson().fromJson(response.body(), GenderOutputModel.class);
var genderId = genderObj.Id;

JsonObject firstFactorPayload = new JsonObject();
firstFactorPayload.addProperty("GenderId", genderId);
firstFactorPayload.addProperty("Name", clientName);
firstFactorPayload.addProperty("Surname", clientSurname);
firstFactorPayload.addProperty("EmailAddress", clientEmail);

HttpRequest firstFactorRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/registration/first-factor"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(firstFactorPayload.toString()))
    .build();

response = httpClient.send(firstFactorRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
RegistrationFirstFactorOutputModel firstFactorRegistrationResult = new Gson().fromJson(response.body(), RegistrationFirstFactorOutputModel.class);

Deuxième étape d’inscription

Entrées : Le même e-mail et le numéro saisi par le client.
Action : Demandez la vérification du téléphone.
À conserver / résultat attendu : Recueillez smsVerificationCode et conservez les deux codes.

Cette demande envoie un code au numéro mobile fourni. Recueillez auprès du client les codes e-mail et SMS avant la troisième étape :


payload = JsonConvert.SerializeObject(new { PhoneNumberPrefix = phoneNumberPrefix, PhoneNumberNumber = phoneNumberNumber });
sContent = new StringContent(payload, Encoding.UTF8, "application/json");
httpResponseMessage = await httpClient.PostAsync("api/v1/users/registration/second-factor", sContent);
httpResponseMessage.EnsureSuccessStatusCode();
resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var secondFactorRegistrationResult = JsonConvert.DeserializeObject<RegistrationSecondFactorOutputModel>(resultAsString);

								
// Second-factor registration
JsonObject secondFactorPayload = new JsonObject();
secondFactorPayload.addProperty("PhoneNumberPrefix", phoneNumberPrefix);
secondFactorPayload.addProperty("PhoneNumberNumber", phoneNumberNumber);

HttpRequest secondFactorRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/registration/second-factor"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(secondFactorPayload.toString()))
    .build();

response = httpClient.send(secondFactorRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
RegistrationSecondFactorOutputModel registrationSecondFactorOutputModel = new Gson().fromJson(response.body(), RegistrationSecondFactorOutputModel.class);

Troisième étape d’inscription

Entrées : Les deux codes, la langue et les consentements.
Action : Terminez l’auto-inscription.
À conserver / résultat attendu : Conservez userId, accessToken, refreshToken et validUntil.

Recueillez emailVerificationCode et smsVerificationCode auprès du client. Les champs Token des réponses peuvent être vides si l’environnement ne retourne pas les codes de vérification. Cette étape termine l’inscription. La réponse contient un token CLIENT pour les appels HTTP suivants :


var language = await httpClient.GetFromJsonAsync<LanguageOutputModel>("/api/v1/languages/code/DE");
var legalAcceptance = await httpClient.GetFromJsonAsync<LegalAcceptanceOutputModel>("/api/v1/legal-acceptances/active");
payload = JsonConvert.SerializeObject(new
{
    ManagementPersonalDataConsent = consentTimestamp,
    SecondFactorToken = smsVerificationCode,
    FirstFactorToken = emailVerificationCode,
    GenderId = gender.Id,
    Name = clientName,
    Surname = clientSurname,
    EmailAddress = clientEmail,
    PhoneNumberPrefix = phoneNumberPrefix,
    PhoneNumberNumber = phoneNumberNumber,
    Password = clientPassword,
    LanguageId = language.Id,
    LegalAcceptanceId = legalAcceptance.Id, });
sContent = new StringContent(payload, Encoding.UTF8, "application/json");
httpResponseMessage = await httpClient.PostAsync("api/v1/users/registration/third-factor", sContent);
httpResponseMessage.EnsureSuccessStatusCode();
resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var thirdFactorRegistrationResult = JsonConvert.DeserializeObject<RegistrationThirdFactorOutputModel>(resultAsString);
var userId = thirdFactorRegistrationResult.UserId;
var accessToken = thirdFactorRegistrationResult.AccessToken;
var refreshToken = thirdFactorRegistrationResult.RefreshToken;
var validUntil = thirdFactorRegistrationResult.ValidUntil;
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

								
// Third-factor registration
HttpRequest languageRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("languages/code/DE"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(languageRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
LanguageOutputModel languageObj = new Gson().fromJson(response.body(), LanguageOutputModel.class);
var languageId = languageObj.Id;

HttpRequest legalAcceptanceRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("legal-acceptances/active"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(legalAcceptanceRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
LegalAcceptanceOutputModel legalAcceptanceObj = new Gson().fromJson(response.body(), LegalAcceptanceOutputModel.class);
var legalAcceptanceId = legalAcceptanceObj.Id;

JsonObject thirdFactorPayload = new JsonObject();
thirdFactorPayload.addProperty("ManagementPersonalDataConsent", consentTimestamp);
thirdFactorPayload.addProperty("FirstFactorToken", emailVerificationCode);
thirdFactorPayload.addProperty("SecondFactorToken", smsVerificationCode);
thirdFactorPayload.addProperty("GenderId", genderId);
thirdFactorPayload.addProperty("Name", clientName);
thirdFactorPayload.addProperty("Surname", clientSurname);
thirdFactorPayload.addProperty("EmailAddress", clientEmail);
thirdFactorPayload.addProperty("PhoneNumberPrefix", phoneNumberPrefix);
thirdFactorPayload.addProperty("PhoneNumberNumber", phoneNumberNumber);
thirdFactorPayload.addProperty("Password", clientPassword);
thirdFactorPayload.addProperty("LanguageId", languageId);
thirdFactorPayload.addProperty("LegalAcceptanceId", legalAcceptanceId);

HttpRequest thirdFactorRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users/registration/third-factor"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(thirdFactorPayload.toString()))
    .build();

response = httpClient.send(thirdFactorRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
RegistrationThirdFactorOutputModel registrationThirdFactorOutputModelObj = new Gson().fromJson(response.body(), RegistrationThirdFactorOutputModel.class);

var userId = registrationThirdFactorOutputModelObj.UserId;
var accessToken = registrationThirdFactorOutputModelObj.AccessToken;
var refreshToken = registrationThirdFactorOutputModelObj.RefreshToken;
var validUntil = registrationThirdFactorOutputModelObj.ValidUntil;

Remarque

Lisez ValidUntil dans le résultat. La durée de validité est définie par le service. Tant que la paire de tokens reste valable, obtenez un nouveau token CLIENT par la procédure de renouvellement du token .

Reconnaître le résultat

Après l’auto-inscription : conservez l’identifiant du client et les deux tokens. Les valeurs sont illustratives.

{"userId":123,"accessToken":"<access-token>","refreshToken":"<refresh-token>","validUntil":"2026-10-13T12:00:00Z"}

Le catalogue des DTO contient les autres propriétés de la réponse. Traitez une demande échouée avant de poursuivre ; consultez Gestion des erreurs.

Alternative : inscription administrative du client

Les exemples utilisent des classes utilitaires communes. Consultez Classes utilitaires communes : code source C# et Java complet avant de copier un exemple.

L’inscription administrative crée le client en un appel avec un token ADMIN existant. La réponse contient les données et l’identifiant du client, mais pas de nouveau token ADMIN. Utilisez ce parcours pour une intégration serveur à serveur autorisée qui recueille les données nécessaires. Le token doit permettre de créer des clients ; sa durée dépend de la configuration de l’intégration. Veuillez garder ce token secret.

Inscription en un appel

Entrées : Token ADMIN, données complètes et identifiants de référence.
Action : Créez le client pour son compte.
À conserver / résultat attendu : Conservez userId ; l’opération ne retourne pas de nouveau token administratif.

L’exemple crée un client avec les champs présentés. Fournissez les informations requises par le produit et respectez la validation de l’API. clientBirthDate est la date de naissance réelle du client (C# : DateTime ; Java : chaîne ISO yyyy-MM-dd). Le client HTTP doit utiliser un token ADMIN.


httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", adminToken);
var language = await httpClient.GetFromJsonAsync<LanguageOutputModel>("/api/v1/languages/code/DE");
var legalAcceptance = await httpClient.GetFromJsonAsync<LegalAcceptanceOutputModel>("/api/v1/legal-acceptances/active");
var nationality = await httpClient.GetFromJsonAsync<NationalityOutputModel>("api/v1/nationalities/code/CH");
var country = await httpClient.GetFromJsonAsync<CountryOutputModel>("api/v1/countries/code/CH");
var pensionSituation = await httpClient.GetFromJsonAsync<PensionSituationOutputModel>("api/v1/pension-situations/code/PENSION-FUND");
var taxLiability = await httpClient.GetFromJsonAsync<TaxLiabilityOutputModel>("api/v1/tax-liabilities/code/CH");
var civilStatus = await httpClient.GetFromJsonAsync<CivilStatusOutputModel>("api/v1/civil-statuses/code/SINGLE");
var gender = await httpClient.GetFromJsonAsync<GenderOutputModel>("/api/v1/genders/code/MALE");
var payload = JsonConvert.SerializeObject(new
{
    ManagementPersonalDataConsent = consentTimestamp,
    Name = clientName,
    Surname = clientSurname,
    Email = clientEmail,
    PhoneNumberPrefix = phoneNumberPrefix,
    PhoneNumberNumber = phoneNumberNumber,
    PensionSituationId = pensionSituation.Id,
    CivilStatusId = civilStatus.Id,
    LanguageId = language.Id,
    LegalAcceptanceId = legalAcceptance.Id,
    Address = new
    {
        City = "Baar",
        Zip = "6340",
        Street = "Neugasse",
        StreetNr = "28A",
        CountryId = country.Id,
        CoName = "Zoo",
        CoSurname = "Zurich"
    },
    TaxLiabilityId = taxLiability.Id,
    GenderId = gender.Id,
    Nationality1Id = nationality.Id,
    BirthDate = clientBirthDate
});
var httpResponseMessage = await httpClient.PostAsync("api/v1/users", new StringContent(payload, Encoding.UTF8, "application/json"));
httpResponseMessage.EnsureSuccessStatusCode();
var userId = JsonConvert.DeserializeObject<ClientOutputModel>(await httpResponseMessage.Content.ReadAsStringAsync()).Id;
var accessToken = adminToken;

								
// clientEmail, clientName and clientSurname are entered by the client.

HttpRequest languageRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("languages/code/DE"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

var response = httpClient.send(languageRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
LanguageOutputModel languageObj = new Gson().fromJson(response.body(), LanguageOutputModel.class);
var languageId = languageObj.Id;

HttpRequest legalAcceptanceRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("legal-acceptances/active"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(legalAcceptanceRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
LegalAcceptanceOutputModel legalAcceptanceObj = new Gson().fromJson(response.body(), LegalAcceptanceOutputModel.class);
var legalAcceptanceId = legalAcceptanceObj.Id;

HttpRequest nationalityRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("nationalities/code/CH"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(nationalityRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
NationalityOutputModel nationalityObj = new Gson().fromJson(response.body(), NationalityOutputModel.class);
var nationalityId = nationalityObj.Id;

HttpRequest countryRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("countries/code/CH"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(countryRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
CountryOutputModel countryObj = new Gson().fromJson(response.body(), CountryOutputModel.class);
var countryId = countryObj.Id;

HttpRequest pensionRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("pension-situations/code/PENSION-FUND"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(pensionRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
PensionSituationOutputModel pensionObj = new Gson().fromJson(response.body(), PensionSituationOutputModel.class);
var pensionId = pensionObj.Id;

HttpRequest taxLiabilityRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("tax-liabilities/code/CH"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(taxLiabilityRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
TaxLiabilityOutputModel taxLiabilityObj = new Gson().fromJson(response.body(), TaxLiabilityOutputModel.class);
var taxLiabilityId = taxLiabilityObj.Id;

HttpRequest civilStatusRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("civil-statuses/code/SINGLE"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(civilStatusRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
CivilStatusOutputModel civilStatusObj = new Gson().fromJson(response.body(), CivilStatusOutputModel.class);
var civilStatusId = civilStatusObj.Id;

HttpRequest genderRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("genders/code/MALE"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.GUEST_TOKEN)
    .header("Content-Type", "application/json")
    .build();

response = httpClient.send(genderRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
GenderOutputModel genderObj = new Gson().fromJson(response.body(), GenderOutputModel.class);
var genderId = genderObj.Id;

// Preparing payload
JsonObject registrationPayload = new JsonObject();
registrationPayload.addProperty("ManagementPersonalDataConsent", consentTimestamp);
registrationPayload.addProperty("CivilStatusId", civilStatusId);
registrationPayload.addProperty("Name", clientName);
registrationPayload.addProperty("Surname", clientSurname);
registrationPayload.addProperty("Email", clientEmail);
registrationPayload.addProperty("PhoneNumberPrefix", phoneNumberPrefix);
registrationPayload.addProperty("PhoneNumberNumber", phoneNumberNumber);
registrationPayload.addProperty("PensionSituationId", pensionId);
registrationPayload.addProperty("LanguageId", languageId);
registrationPayload.addProperty("LegalAcceptanceId", legalAcceptanceId);
registrationPayload.addProperty("GenderId", genderId);
registrationPayload.addProperty("BirthDate", clientBirthDate);
registrationPayload.addProperty("Nationality1Id", nationalityId);
registrationPayload.addProperty("TaxLiabilityId", taxLiabilityId);
JsonObject address = new JsonObject();
address.addProperty("City", "Baar");
address.addProperty("Zip", "6340");
address.addProperty("Street", "Neugasse");
address.addProperty("StreetNr", "1");
address.addProperty("CountryId", countryId);
registrationPayload.add("Address", address);

HttpRequest createRequest = HttpRequest.newBuilder()
    .timeout(Duration.ofMinutes(1))
    .uri(Settings.wmsUri("users"))
    .header("Accept-Language", "de-DE")
    .header("Authorization", "Bearer " + Settings.ADMIN_TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(registrationPayload.toString()))
    .build();

response = httpClient.send(createRequest, BodyHandlers.ofString());
Api.requireSuccess(response);
ClientOutputModel clientObj = new Gson().fromJson(response.body(), ClientOutputModel.class);

var userId = clientObj.Id;
// Continue using the existing administrative access token.
var accessToken = Settings.ADMIN_TOKEN;