Registrazione del cliente

Come seguire questo capitolo

Dati richiesti: Dati inseriti dal cliente e ID di riferimento; inizia con il token GUEST.

Passaggi e risultato atteso: Completa tutte le verifiche nell’ordine indicato. L’identità del cliente e la coppia di token restituiti costituiscono il contesto delle chiamate successive.

Alternative e operazioni successive: L’autoregistrazione è il percorso principale. Usa la registrazione amministrativa soltanto se l’integrazione crea clienti per loro conto.

Codice sorgente dei DTO: CivilStatusOutputModel, ClientOutputModel, CountryOutputModel, GenderOutputModel, LanguageOutputModel, LegalAcceptanceOutputModel, NationalityOutputModel, PensionSituationOutputModel, RegistrationFirstFactorOutputModel, RegistrationSecondFactorOutputModel, RegistrationThirdFactorOutputModel, TaxLiabilityOutputModel

Le variabili assegnate in un blocco precedente vengono riutilizzate nei successivi. I dati inseriti dal cliente provengono dalla tua interfaccia. Conserva identificativi e valori di riferimento nel contesto del cliente; non ricreare il contesto a ogni passaggio.

Gli esempi utilizzano classi helper condivise. Consulta Classi helper condivise: codice C# e Java completo prima di copiare un esempio.

Prima di iniziare: Recapiti del cliente, consentTimestamp raccolto al momento del consenso, phoneNumberPrefix, phoneNumberNumber e password scelta dal cliente. Scegli autoregistrazione con GUEST o registrazione amministrativa con ADMIN.

Da conservare per il passaggio successivo: userId. L’autoregistrazione restituisce anche accessToken, refreshToken e validUntil. Per la registrazione amministrativa, conserva il token ADMIN esistente.

Nota

La registrazione richiede l’indirizzo e-mail del cliente. Deve essere univoco nel database WMS dell’ambiente di destinazione. La registrazione con un indirizzo già presente non riesce.

Sono disponibili due modalità di registrazione: autoregistrazione del cliente oppure registrazione amministrativa del cliente.

Autoregistrazione del cliente

Il cliente può registrarsi autonomamente fornendo le informazioni passo dopo passo. Questa registrazione in tre passaggi richiede un token GUEST. Riceve prima un codice via e-mail, poi un codice via SMS e infine un token CLIENT per le chiamate HTTP successive. Il valore ValidUntil restituito ne indica la scadenza.

Primo passaggio della registrazione

Dati richiesti: Nome, cognome, e-mail, password, data del consenso e riferimento del genere.
Operazione: Avvia l’autoregistrazione e richiedi la verifica dell’e-mail.
Da conservare / risultato atteso: Conserva i dati di registrazione e raccogli emailVerificationCode per l’ultimo passaggio.

Il primo passaggio richiede genere, nome, cognome ed e-mail del cliente. Usa il token GUEST nel client HTTP. Il cliente riceve un codice di verifica via e-mail. Conservalo per la richiesta finale; la richiesta successiva avvia la verifica del numero 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);

Secondo passaggio della registrazione

Dati richiesti: La stessa e-mail e il numero di telefono inserito dal cliente.
Operazione: Richiedi la verifica del telefono.
Da conservare / risultato atteso: Raccogli smsVerificationCode e conserva entrambi i codici.

Questa richiesta invia un codice al numero mobile indicato. Raccogli dal cliente sia il codice e-mail sia quello SMS prima del terzo passaggio:


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);

Terzo passaggio della registrazione

Dati richiesti: Entrambi i codici, la lingua e i consensi.
Operazione: Completa l’autoregistrazione.
Da conservare / risultato atteso: Conserva userId, accessToken, refreshToken e validUntil.

Raccogli emailVerificationCode e smsVerificationCode dal cliente. I campi Token delle risposte possono essere vuoti se l’ambiente non restituisce i codici di verifica. Questo passaggio completa la registrazione. La risposta contiene un token CLIENT per le chiamate HTTP successive:


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;

Nota

Leggi ValidUntil nel risultato. La durata di validità è definita dal servizio. Finché la coppia di token è valida, ottieni un nuovo token CLIENT tramite la procedura di rinnovo del token .

Riconoscere il risultato

Dopo l’autoregistrazione: conserva l’ID del cliente ed entrambi i token. I valori sono illustrativi.

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

Il catalogo DTO contiene le altre proprietà della risposta. Gestisci una richiesta non riuscita prima di proseguire; consulta Gestione degli errori.

Alternativa: registrazione amministrativa del cliente

Gli esempi utilizzano classi helper condivise. Consulta Classi helper condivise: codice C# e Java completo prima di copiare un esempio.

La registrazione amministrativa crea il cliente con una chiamata e un token ADMIN esistente. La risposta contiene dati e identificativo del cliente, ma non un nuovo token ADMIN. Usa questo percorso per un’integrazione server-to-server autorizzata che raccoglie i dati necessari. Il token deve consentire la creazione dei clienti; la durata dipende dalla configurazione dell’integrazione. Ricorda di mantenere segreto il token.

Registrazione con una chiamata

Dati richiesti: Token ADMIN, dati completi e ID di riferimento.
Operazione: Crea il cliente per suo conto.
Da conservare / risultato atteso: Conserva userId; l’operazione non restituisce un nuovo token amministrativo.

L’esempio crea un cliente con i campi mostrati. Fornisci i dati richiesti dal prodotto e rispetta la validazione dell’API. clientBirthDate è la data di nascita effettiva del cliente (C#: DateTime; Java: stringa ISO yyyy-MM-dd). Il client HTTP deve usare 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;