Quickstart TypeScript

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

L'SDK è basato su fetch e funziona in Node.js, nel browser e con i bundler.

Prerequisiti

• Node.js 18+ (per fetch nativo).
• Hai registrato un'app e ottenuto client_id e client_secret (per gli esperimenti conviene un'app privata).

• L'SDK TypeScript di Amica installato (sostituisci v3.0.0 con l'ultima release; vedi anche Installazione):

  npm install github:amica-dev/typescript-sdk#v3.0.0
  

Client secret e browser

Il flusso Client Credentials mostrato qui usa il client_secret e va eseguito lato server, mai in un browser. Per le applicazioni frontend usa il flusso Authorization Code con PKCE.

Ottenere un access token

La risorsa Nazione fa parte delle anagrafiche, coperte dallo scope comune:

auth.ts

export async function getAccessToken(): Promise<string> {
  const response = await fetch("https://auth.amica20.it/connect/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: "IL_TUO_CLIENT_ID",
      client_secret: "IL_TUO_CLIENT_SECRET",
      scope: "read write comune",
    }),
  });
  if (!response.ok) throw new Error(`Auth fallita: ${response.status}`);
  const data = await response.json();
  return data.access_token;
}

Configurare l'SDK

Configurare l'SDK

import { Configuration, AziendaApi, NazioneApi } from "@amica/typescript-sdk";
import { getAccessToken } from "./auth";

const config = new Configuration({
  basePath: "https://customerws1.amica20.it",
  accessToken: await getAccessToken(),
});

Elenca

I metodi dell'SDK ricevono un oggetto-richiesta con i parametri. Recuperiamo prima le aziende (per il companyId), poi le prime nazioni dell'azienda 1:

elenca.ts

try {
  // Elenco delle aziende disponibili per le credenziali in uso
  const aziende = new AziendaApi(config);
  for (const azienda of await aziende.apiVversionConfigAziendaGet({ version: "3" })) {
    console.log(azienda);
  }

  // Prime 5 nazioni dell'azienda 1
  const nazioni = new NazioneApi(config);
  const result = await nazioni.apiVversionCompanyIdNazioneGet({
    version: "3",
    companyId: "1",
    take: 5,
  });
  for (const nazione of result) {
    console.log(`${nazione.id}: ${nazione.nome} (${nazione.codice})`);
  }
} catch (err) {
  console.error("Errore nella chiamata all'API:", err);
}

Cosa abbiamo imparato

1. La configurazione richiede basePath e accessToken.
2. I metodi ricevono un singolo oggetto-richiesta: { version, companyId, ... }.
3. La prima chiamata utile è in genere l'elenco delle aziende, da cui ricavi il companyId.

Crea

crea.ts

try {
  const nazioni = new NazioneApi(config);
  const creata = await nazioni.apiVversionCompanyIdNazionePost({
    version: "3",
    companyId: "1",
    nazione: { nome: "Atlantide", codice: "AT" },
  });
  console.log(`Creata la nazione ${creata.nome} con id ${creata.id}`);
} catch (err) {
  console.error("Errore nella chiamata all'API:", err);
}

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.ts

try {
  const nazioni = new NazioneApi(config);

  // 1. Leggi
  const nazione = await nazioni.apiVversionCompanyIdNazioneIdGet({
    version: "3",
    companyId: "1",
    id: 1176,
  });

  // 2. Modifica (mantenendo il concurrencyToken ricevuto)
  nazione.nome = "Atlantide (rev. 2)";

  // 3. Scrivi
  const aggiornata = await nazioni.apiVversionCompanyIdNazioneIdPut({
    version: "3",
    companyId: "1",
    id: nazione.id!,
    nazione,
  });
  console.log(`Aggiornata: ${aggiornata.nome}, nuovo token ${aggiornata.concurrencyToken}`);
} catch (err) {
  console.error("Errore nella chiamata all'API:", err);
}

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. L'oggetto restituito porta con sé il concurrencyToken: rileggi, modifica e rispediscilo come parametro nazione.
2. In aggiornamento si usa apiVversionCompanyIdNazioneIdPut({ ..., id, nazione }); in creazione apiVversionCompanyIdNazionePost({ ..., nazione }).
3. Un 422 segnala un conflitto di concorrenza, non un errore di validazione.

Codice sorgente dell'SDK

L'SDK TypeScript è open-source su github.com/amica-dev/typescript-sdk.