Quickstart Python

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

Prerequisiti

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

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

  pip install git+https://github.com/amica-dev/python-sdk.git@v3.0.0
  

Tip

Usa requests per la chiamata di autenticazione: pip install requests.

Ottenere un access token

L'API è protetta da OAuth 2.0. Per uno script server-to-server il flusso più diretto è Client Credentials: scambi client_id e client_secret con un access token. La risorsa Nazione fa parte delle anagrafiche, coperte dallo scope comune.

auth.py

import requests

def get_access_token() -> str:
    response = requests.post(
        "https://auth.amica20.it/connect/token",
        data={
            "grant_type": "client_credentials",
            "client_id": "IL_TUO_CLIENT_ID",
            "client_secret": "IL_TUO_CLIENT_SECRET",
            "scope": "read write comune",
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]

Custodisci il client secret

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

Configurare l'SDK

L'SDK si configura passando l'access token e l'host dell'API:

Configurare l'SDK

import amica_sdk
from amica_sdk.rest import ApiException
from auth import get_access_token

config = amica_sdk.Configuration(
    host="https://customerws1.amica20.it",
    access_token=get_access_token(),
)

Elenca

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

elenca.py

with amica_sdk.ApiClient(config) as api_client:
    try:
        # Elenco delle aziende disponibili per le credenziali in uso
        aziende = amica_sdk.AziendaApi(api_client)
        for azienda in aziende.api_vversion_config_azienda_get("3"):
            print(azienda)

        # Prime 5 nazioni dell'azienda 1
        nazioni = amica_sdk.NazioneApi(api_client)
        result = nazioni.api_vversion_company_id_nazione_get(
            version="3", company_id="1", take=5
        )
        for nazione in result:
            print(f"{nazione.id}: {nazione.nome} ({nazione.codice})")

    except ApiException as e:
        print(f"Errore nella chiamata all'API: {e}")

python elenca.py

Cosa abbiamo imparato

1. La configurazione dell'SDK richiede host e access_token.
2. Il client si usa come context manager (with), che ne gestisce la chiusura.
3. Ogni risorsa ha la sua classe API (AziendaApi, NazioneApi); i metodi seguono il pattern api_vversion_company_id_<risorsa>_get(version, company_id, ...).
4. La prima chiamata utile è in genere l'elenco delle aziende, da cui ricavi il companyId.

Crea

Per aggiungere una nazione si istanzia il modello Nazione e si chiama il metodo ...post:

crea.py

from amica_sdk.models.nazione import Nazione

with amica_sdk.ApiClient(config) as api_client:
    nazioni = amica_sdk.NazioneApi(api_client)
    try:
        nuova = Nazione(nome="Atlantide", codice="AT")
        creata = nazioni.api_vversion_company_id_nazione_post(
            version="3", company_id="1", nazione=nuova
        )
        print(f"Creata la nazione {creata.nome} con id {creata.id}")
    except ApiException as e:
        print(f"Errore nella chiamata all'API: {e}")

Il modello Nazione espone nome e codice (un codice ISO 3166-1 alpha-2), oltre a id e concurrency_token valorizzati dall'API nella risposta.

Aggiorna

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

aggiorna.py

with amica_sdk.ApiClient(config) as api_client:
    nazioni = amica_sdk.NazioneApi(api_client)
    try:
        # 1. Leggi
        nazione = nazioni.api_vversion_company_id_nazione_id_get(
            version="3", company_id="1", id=1176
        )

        # 2. Modifica (mantenendo il concurrency_token ricevuto)
        nazione.nome = "Atlantide (rev. 2)"

        # 3. Scrivi
        aggiornata = nazioni.api_vversion_company_id_nazione_id_put(
            version="3", company_id="1", id=nazione.id, nazione=nazione
        )
        print(f"Aggiornata: {aggiornata.nome}, nuovo token {aggiornata.concurrency_token}")
    except ApiException as e:
        print(f"Errore nella chiamata all'API: {e}")

Conflitto di concorrenza

Se ricevi un 422 Unprocessable Entity, qualcun altro ha modificato la nazione dopo la tua lettura: rileggila per ottenere il concurrency_token aggiornato, riapplica le modifiche e riprova.

Cosa abbiamo imparato

1. Il modello porta con sé il concurrency_token: rileggi, modifica e rispedisci lo stesso oggetto, senza ricostruirlo a mano.
2. In aggiornamento si usa ..._id_put(..., id=..., nazione=...); in creazione ..._post(..., nazione=...).
3. Un 422 segnala un conflitto di concorrenza, non un errore di validazione.

Codice sorgente dell'SDK

L'SDK Python è open-source su github.com/amica-dev/python-sdk, con la documentazione di dettaglio (una pagina per risorsa) nella sua cartella docs/.