Integrare ERP e sistemi aziendali: progettare un contratto API affidabile

Stabilire chi possiede ciascuna informazione

Prima di scrivere un connettore conviene costruire una matrice delle responsabilità. Il catalogo può essere mantenuto nel gestionale, i contenuti commerciali nel sito e il consenso alle comunicazioni in un sistema dedicato. Per ogni campo si stabilisce chi può modificarlo, chi lo riceve e quale regola risolve un conflitto. Dire che due sistemi sono sincronizzati senza chiarire queste responsabilità significa rinviare una decisione che riemergerà sotto forma di anomalia.

Gli identificativi richiedono la stessa attenzione. Il codice visibile a un operatore può cambiare, mentre il collegamento tecnico deve continuare a riconoscere l'entità. È utile conservare una corrispondenza esplicita tra identificativi interni ed esterni, con il sistema di origine. I casi di fusione di anagrafiche, cessazione di un articolo e variazione di unità di misura vanno discussi subito: sono eventi normali nella vita aziendale, non eccezioni improbabili.

Il contratto descrive regole, non soltanto campi

Un contratto API deve specificare formati, obbligatorietà, limiti e significato operativo. Una data può rappresentare l'istante di acquisizione o il giorno commerciale; una quantità può riferirsi a pezzi, confezioni o unità base. Precisione decimale, arrotondamenti, valuta e fuso orario producono differenze reali nei risultati. Anche la distinzione tra valore assente, nullo e vuoto deve essere intenzionale, soprattutto quando una richiesta modifica soltanto una parte dell'oggetto.

Una descrizione leggibile dalle macchine, come quella prevista da OpenAPI, aiuta a condividere la struttura dell'interfaccia e a costruire strumenti di verifica. Va accompagnata però da esempi di processo e regole di transizione. Un payload formalmente valido può richiedere un'operazione non consentita nello stato corrente. I messaggi di errore devono permettere al chiamante di distinguere un dato correggibile, un conflitto e un'indisponibilità temporanea, senza rivelare dettagli interni inutili.

Gestire la ripetizione senza duplicare gli effetti

Supponiamo che un sistema invii un ordine e non riceva risposta prima del timeout. Non può sapere se l'ordine sia stato salvato oppure se la richiesta si sia interrotta prima. Ripetere l'invio senza una strategia può creare un duplicato. L'idempotenza affronta proprio questo problema: una stessa operazione logica, riconosciuta attraverso una chiave concordata, non deve generare effetti aggiuntivi quando viene presentata di nuovo entro le condizioni definite dal contratto.

La chiave richiede una politica precisa: ambito, durata, comportamento con un contenuto diverso e modalità di recupero della risposta precedente. Servono inoltre vincoli che resistano a richieste concorrenti. Non è sufficiente controllare in anticipo se il documento esiste e poi inserirlo, perché due richieste possono superare insieme il controllo. La prova significativa invia richieste parallele e simula una caduta della connessione nel momento in cui l'esito è incerto.

Eventi, webhook e ordine delle operazioni

Un webhook segnala che qualcosa è accaduto, ma il destinatario può essere irraggiungibile. Occorre concordare autenticazione del mittente, gestione dei tentativi, duplicati e recupero degli eventi mancanti. La ricezione dovrebbe registrare il messaggio prima di affidarlo a un'elaborazione più lunga, così da non perdere il lavoro dopo la conferma. I messaggi che continuano a fallire devono diventare visibili in una coda di anomalie con strumenti di diagnosi.

L'ordine di arrivo non sempre coincide con l'ordine degli eventi. Un aggiornamento di spedizione può precedere la registrazione del documento a cui si riferisce. Si può gestire il problema con numeri di versione, stati intermedi o una consultazione della fonte autorevole. La soluzione dipende dal processo. Una promessa generica di sincronizzazione in tempo reale non sostituisce la definizione del ritardo ammissibile e del comportamento previsto mentre le informazioni convergono.

Riconciliare per scoprire ciò che non è arrivato

I registri dei singoli invii dicono che cosa si è tentato, ma non sempre rivelano che cosa manca. Una riconciliazione periodica confronta gli insiemi rilevanti: documenti attesi e ricevuti, stati, quantità e importi secondo regole concordate. Può partire da un intervallo temporale con una sovrapposizione controllata, così da intercettare aggiornamenti tardivi. Anche la cancellazione o l'archiviazione di un'entità deve avere una rappresentazione riconoscibile.

Il cruscotto operativo dovrebbe distinguere elementi da ritentare automaticamente, errori da correggere e conflitti che richiedono una decisione. Ogni anomalia deve avere un proprietario, un riferimento al documento e una cronologia comprensibile. Consentire un nuovo tentativo senza modificare i dati manualmente nel database rende il recupero più controllabile. Questa capacità va progettata insieme al connettore, perché l'assistenza ne avrà bisogno dopo il primo rilascio.

Definire un budget di attesa e di recupero

Un'integrazione deve rispettare i limiti di capacità dei sistemi coinvolti. Il contratto operativo dovrebbe chiarire quante richieste si possono inviare, con quale concorrenza e che cosa accade quando il destinatario chiede di rallentare. Un ritentativo immediato e ripetuto da molti client può aggravare un disservizio. È preferibile prevedere attese progressive con una componente di variazione, rispettare le indicazioni disponibili e interrompere i tentativi dopo condizioni concordate, trasferendo il caso a una gestione visibile.

Il dimensionamento va provato anche dopo un'interruzione. Durante il fermo gli eventi possono accumularsi; alla ripartenza non basta che il connettore torni a funzionare. Deve poter smaltire l'arretrato mentre arrivano nuove operazioni, senza saturare i servizi operativi. La prova considera volume iniziale, velocità di recupero e priorità. Se gli ordini recenti e quelli arretrati richiedono trattamenti diversi, la politica deve essere esplicita e compatibile con le dipendenze tra i documenti.

La direzione del progetto dovrebbe conoscere il massimo ritardo tollerato e il momento in cui il sistema richiede un intervento. Questa informazione permette di predisporre una procedura temporanea per i reparti e di evitare che ciascuno avvii correzioni manuali incoerenti. Il recupero tecnico e la ripresa organizzativa devono convergere sullo stesso stato dei dati: altrimenti il collegamento risulta attivo, mentre il processo resta disallineato.

Versioni e responsabilità nel tempo

Un'integrazione entra nel patrimonio informativo dell'impresa e può vivere più a lungo dei gruppi che l'hanno realizzata. Servono inventario, referente, ambienti di prova e una politica per le modifiche incompatibili. Aggiungere un campo opzionale e cambiare il significato di un campo esistente non sono interventi equivalenti. I test di contratto devono coprire i consumatori reali e le combinazioni di versione che resteranno attive durante una transizione.

Per il contesto del prodotto, la pagina dedicata alle API e ai Web Services di Gestionale sul Web è il punto di approfondimento pertinente. Disponibilità degli endpoint, autenticazione, limiti e operazioni supportate vanno verificati nella documentazione applicabile al progetto. I modelli descritti qui sono criteri generali di integrazione: non sostituiscono il contratto tecnico effettivo di una piattaforma.