Quickstart C

Questo tutorial costruisce tre piccole applicazioni .NET che lavorano sulla risorsa Nazione: una le elenca, una ne crea una nuova e una aggiorna una esistente gestendo il controllo di concorrenza.

Prerequisiti

• .NET SDK 6.0+ installato.
• Hai registrato un'app e ottenuto client_id e client_secret (per gli esperimenti conviene un'app privata).

• L'SDK C# di Amica (Amica.Sdk). NuGet non installa da Git: scarica il .nupkg allegato all'ultima release e installalo da una sorgente locale (vedi Installazione):

  dotnet add package Amica.Sdk --version 3.0.0 --source ./percorso/cartella-nupkg
  

using

using Amica.Sdk.Api;
using Amica.Sdk.Client;
using Amica.Sdk.Model;

Ottenere un access token

L'API è protetta da OAuth 2.0. Per un'applicazione server-to-server il flusso più diretto è Client Credentials. La risorsa Nazione fa parte delle anagrafiche, coperte dallo scope comune.

Ottenere il token con HttpClient

using System.Net.Http;

static async Task<string> GetAccessTokenAsync()
{
    using var http = new HttpClient();
    var response = await http.PostAsync(
        "https://auth.amica20.it/connect/token",
        new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["grant_type"] = "client_credentials",
            ["client_id"] = "IL_TUO_CLIENT_ID",
            ["client_secret"] = "IL_TUO_CLIENT_SECRET",
            ["scope"] = "read write comune",
        }));
    response.EnsureSuccessStatusCode();
    using var doc = System.Text.Json.JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    return doc.RootElement.GetProperty("access_token").GetString()!;
}

Custodisci il client secret

Non scrivere mai client_id/client_secret nel codice versionato: leggili da variabili d'ambiente o da un gestore di segreti.

Configurare l'SDK

Configurare l'SDK

var config = new Configuration
{
    BasePath = "https://customerws1.amica20.it",
    AccessToken = await GetAccessTokenAsync(),
};

Elenca

Recuperiamo prima l'elenco delle aziende (per conoscere il companyId), poi le prime nazioni dell'azienda 1:

Elenca

try
{
    // Elenco delle aziende disponibili per le credenziali in uso
    var aziende = new AziendaApi(config);
    foreach (var azienda in aziende.ApiVversionConfigAziendaGet("3"))
        Console.WriteLine(azienda);

    // Prime 5 nazioni dell'azienda 1
    var nazioni = new NazioneApi(config);
    var result = nazioni.ApiVversionCompanyIdNazioneGet("3", "1", take: 5);
    foreach (var nazione in result)
        Console.WriteLine($"{nazione.Id}: {nazione.Nome} ({nazione.Codice})");
}
catch (ApiException e)
{
    Console.WriteLine($"Errore nella chiamata all'API: {e.Message} (HTTP {e.ErrorCode})");
}

Cosa abbiamo imparato

1. La configurazione richiede BasePath e AccessToken.
2. Ogni risorsa ha la sua classe API (AziendaApi, NazioneApi); i metodi seguono il pattern ApiVversionCompanyIdNazioneGet(version, companyId, ...).
3. La prima chiamata utile è in genere l'elenco delle aziende, da cui ricavi il companyId.

Crea

Crea

try
{
    var nazioni = new NazioneApi(config);
    var nuova = new Nazione(nome: "Atlantide", codice: "AT");
    var creata = nazioni.ApiVversionCompanyIdNazionePost("3", "1", nazione: nuova);
    Console.WriteLine($"Creata la nazione {creata.Nome} con id {creata.Id}");
}
catch (ApiException e)
{
    Console.WriteLine($"Errore nella chiamata all'API: {e.Message} (HTTP {e.ErrorCode})");
}

Il modello Nazione espone Nome e Codice (un codice ISO 3166-1 alpha-2), oltre a Id e ConcurrencyToken valorizzati dall'API nella risposta.

Aggiorna

L'aggiornamento segue il flusso leggi → modifica → scrivi, riusando il ConcurrencyToken ricevuto in lettura (vedi Controllo della concorrenza):

Aggiorna

try
{
    var nazioni = new NazioneApi(config);

    // 1. Leggi
    var nazione = nazioni.ApiVversionCompanyIdNazioneIdGet("3", "1", 1176);

    // 2. Modifica (mantenendo il ConcurrencyToken ricevuto)
    nazione.Nome = "Atlantide (rev. 2)";

    // 3. Scrivi
    var aggiornata = nazioni.ApiVversionCompanyIdNazioneIdPut("3", "1", nazione.Id!.Value, nazione: nazione);
    Console.WriteLine($"Aggiornata: {aggiornata.Nome}, nuovo token {aggiornata.ConcurrencyToken}");
}
catch (ApiException e)
{
    Console.WriteLine($"Errore nella chiamata all'API: {e.Message} (HTTP {e.ErrorCode})");
}

Conflitto di concorrenza

Un 422 Unprocessable Entity indica che qualcun altro ha modificato la nazione dopo la tua lettura: rileggila per ottenere il ConcurrencyToken aggiornato, riapplica le modifiche e riprova.

Cosa abbiamo imparato

1. Il modello porta con sé il ConcurrencyToken: rileggi, modifica e rispedisci lo stesso oggetto.
2. In aggiornamento si usa ...IdPut(version, companyId, id, nazione: ...); in creazione ...Post(version, companyId, nazione: ...).
3. Un 422 segnala un conflitto di concorrenza, non un errore di validazione.

Codice sorgente dell'SDK

L'SDK C# è open-source su github.com/amica-dev/csharp-sdk.