Estrarre dati dagli ordini con l’AI: campi mancanti, unità e controllo prima dell’importazione

Parliamo del tuo progetto →

Questa guida serve a una cosa precisa: trasformare il testo di un ordine in dati strutturati senza inventare campi, senza mascherare i mancanti e senza avviare l’importazione se i controlli non sono passati. La documentazione OpenAI sugli Structured Outputs indica proprio questa direzione: schema JSON dichiarato dal chiamante, uso di strict: true quando disponibile e gestione esplicita di refusal o output incompleti nell’applicazione. Structured Outputs · Structured Outputs — Responses API

Se questo flusso deve poi entrare in un gestionale, in un ERP o in un e-commerce, i riferimenti interni più utili sono AI e automazione responsabile, Sviluppo software su misura e integrazioni e Permessi delle integrazioni: una verifica pratica del minimo privilegio.

Cosa ottieni alla fine

Alla fine di questo laboratorio avrai:

  • uno schema JSON minimo per l’estrazione;
  • un prompt copiabile che vieta default inventati;
  • tre ordini simulati completi: uno semplice, uno con conversione esplicita, uno con dati mancanti;
  • un registro di controllo per decidere se importare, fermare o inviare a revisione umana;
  • una procedura ripetibile per gestire ambiguità come separatori numerici o unità non standard.

Gli esempi sono simulati: non rappresentano clienti, test reali o risultati aziendali.

A chi serve

  • Responsabili back office e operations che vogliono ridurre la ricopiatura manuale.
  • Team IT e software house che integrano AI in un flusso di importazione.
  • PMI che hanno ordini in formati misti e vogliono bloccare gli errori prima della scrittura nel sistema.

Strumenti, prerequisiti e materiale fornito

Strumenti minimi

  • un editor di testo o un ambiente di test dove incollare input e output;
  • un modello AI configurato per restituire JSON strutturato;
  • una tabella o un registro dove annotare l’esito;
  • regole interne già definite per ciò che blocca l’importazione.

Prerequisiti

  • sapere quali campi sono obbligatori nel tuo processo;
  • conoscere l’unità attesa dal gestionale, se diversa da quella sorgente;
  • decidere in anticipo chi approva i casi ambigui.

Materiale fornito in questa guida

  • schema JSON;
  • prompt completo;
  • tre testi di ordine inventati;
  • output atteso per ciascun caso;
  • registro finale riutilizzabile.

1. Preparare schema e prompt prima di toccare i dati

Lavora in un file di test, non nel gestionale reale. Il primo passo serve a fissare i vincoli: quali campi esistono, quali possono essere null, quali conversioni sono consentite e quando il flusso si blocca.

Schema JSON minimo

{
  "order_id": "string",
  "sku": "string | null",
  "quantity": "number | null",
  "unit": "string | null",
  "missing_fields": ["string"]
}

Regole operative dello schema

  • order_id è obbligatorio.
  • sku, quantity e unit possono essere null se non sono presenti o non sono affidabili.
  • missing_fields contiene solo i campi davvero mancanti.
  • Nessun valore inventato: niente 1, 0, unknown, n/a al posto di un dato assente.
  • Se esiste una conversione esplicita, il dato sorgente va conservato; il valore derivato, se serve, va annotato a parte o nel registro di controllo.

Prompt completo da copiare

Sei un estrattore di dati da ordini.

Devi restituire solo JSON valido conforme allo schema richiesto.

Regole:
1. Non inventare alcun valore mancante.
2. Se un campo non è presente, usa null e inserisci il nome del campo in missing_fields.
3. Non sostituire mai i valori assenti con 1, 0, stringhe vuote o valori impliciti.
4. Se trovi una conversione esplicita, non cambiare la quantità sorgente: annota la conversione solo se il flusso lo prevede.
5. Mantieni separati ordine, SKU, quantità e unità.
6. Se il testo è ambiguo o incompleto, segnala i campi mancanti.
7. Non aggiungere commenti, spiegazioni o testo fuori dal JSON.

Schema richiesto:
{
  "order_id": "string",
  "sku": "string | null",
  "quantity": "number | null",
  "unit": "string | null",
  "missing_fields": ["string"]
}

Risultato atteso di questo passaggio: il prompt è pronto da riusare, senza ambiguità sul default dei campi mancanti.

2. Provare il caso normale: ordine semplice e completo

Questo caso serve a verificare che il flusso non aggiunga nulla e non perda nulla quando l’ordine è pulito.

Testo ordine simulato

Ordine ORD-1001
SKU: BIC-24
Quantità: 15
Unità: pezzi
Note: consegna standard.

Output atteso

{
  "order_id": "ORD-1001",
  "sku": "BIC-24",
  "quantity": 15,
  "unit": "pezzi",
  "missing_fields": []
}

Controllo da fare subito dopo

  • order_id esiste ed è identico al testo sorgente.
  • sku è presente.
  • quantity è numerica, non una stringa.
  • unit è presente e coerente.
  • missing_fields è vuoto.

Se il risultato diverge: non andare avanti con i casi successivi. Prima correggi il prompt o il mapping del modello, perché un caso semplice che non torna indica quasi sempre un errore di configurazione.

3. Provare il caso con conversione esplicita: 2 scatole da 12 pezzi

Questo è il passaggio più importante della guida. Qui il rischio è confondere la quantità sorgente con il dato derivato. L’ordine dice “2 scatole da 12 pezzi”: il sistema può calcolare 24 pezzi, ma non deve sostituire il valore iniziale se lo schema base non lo prevede.

Testo ordine simulato

Ordine ORD-1002
SKU: PEN-BOX12
Quantità: 2 scatole da 12 pezzi
Unità: scatole
Nota: ogni scatola contiene 12 pezzi.

Output atteso conforme allo schema minimo

{
  "order_id": "ORD-1002",
  "sku": "PEN-BOX12",
  "quantity": 2,
  "unit": "scatole",
  "missing_fields": []
}

Come gestire la conversione

Nel registro di controllo puoi aggiungere una nota separata:

Conversione dichiarata: 2 scatole = 24 pezzi
Dato sorgente mantenuto: 2 scatole
Dato derivato: 24 pezzi
Decisione: non importare finché il flusso non prevede esplicitamente il campo derivato

Il punto non è vietare le conversioni. Il punto è evitare che il numero derivato prenda il posto del numero sorgente senza una regola chiara.

Controllo da fare subito dopo

  • la quantità sorgente resta 2;
  • l’unità resta scatole;
  • nessun campo nuovo entra di nascosto nel JSON;
  • la conversione è annotata fuori dallo schema o in un campo separato, se previsto dal processo.

Se il risultato diverge: blocca l’importazione diretta. Il caso può essere valido solo dopo una regola esplicita di conversione o un passaggio umano di conferma.

4. Provare il caso con dati mancanti: SKU o unità assenti

Ora verifica il comportamento corretto quando mancano campi essenziali. L’obiettivo non è “far funzionare comunque” il flusso, ma verificare che il sistema sappia fermarsi.

Testo ordine simulato

Ordine ORD-1003
Quantità: 8
Note: ritiro in negozio.

Output atteso

{
  "order_id": "ORD-1003",
  "sku": null,
  "quantity": 8,
  "unit": null,
  "missing_fields": ["sku", "unit"]
}

Criterio decisionale

  • se manca sku, il record non è pronto per l’importazione;
  • se manca unit, il record non è pronto per l’importazione;
  • quantity da sola non basta a rendere il dato utilizzabile.

Variante utile: separatori numerici e unità non standard

Se il testo contiene valori come 1,500 o 1.500, non decidere a occhio se si tratti di millecinquecento o di uno virgola cinque. In quel caso il flusso deve fermarsi e chiedere una regola locale esplicita.

Se compare un’unità non standard, per esempio ctn o un’abbreviazione interna, non inventare una corrispondenza. O la mappatura esiste già, oppure il caso va bloccato per revisione.

Se il risultato diverge: il problema non è il record singolo, ma la regola di validazione. Prima di importare, devi decidere se i campi mancanti sono bloccanti o se esistono fonti esterne affidabili per completarli.

5. Applicare la validazione prima dell’importazione

Lavora sul passaggio di controllo, non sull’estrazione. L’importazione deve dipendere da regole chiare e ripetibili.

Checklist decisionale

Controllo Chi lo verifica Esito richiesto
order_id presente sistema obbligatorio
sku presente e coerente sistema o operatore obbligatorio
quantity numerica sistema obbligatorio
unit riconosciuta sistema o operatore obbligatorio o mappato
conversione dichiarata operatore annotata, non nascosta
separatore numerico ambiguo operatore fermo e chiarimento
campi mancanti sistema null + missing_fields

Regola pratica di blocco

Importa solo se:

  1. tutti i campi obbligatori sono presenti;
  2. le conversioni sono esplicite e ammesse dal processo;
  3. non ci sono ambiguità numeriche;
  4. l’unità è riconosciuta.

Se uno di questi punti fallisce, il record non entra nel gestionale. Va in revisione, non in produzione.

Caso valido e caso respinto

Caso valido: ORD-1001

Stato: valido
Motivo: tutti i campi presenti, nessuna ambiguità.
Azione: importazione consentita.

Caso respinto: ORD-1003

Stato: respinto
Motivo: SKU e unità mancanti.
Azione: non importare; inviare a revisione umana.

Se il risultato diverge: non correggere a mano il JSON per farlo sembrare completo. Correggi la regola di ingresso o la qualità del testo sorgente.

6. Chiudere con registro, troubleshooting e prova finale ripetibile

L’ultimo passaggio serve a lasciare una traccia riusabile. Il laboratorio è davvero utile solo se il registro consente a un secondo operatore di rifare il controllo nello stesso modo.

Registro finale riutilizzabile

DATA: 2026-10-14
LABORATORIO: estrazione ordini con AI

CASO 1 — ORD-1001
Esito: ok
Campi mancanti: nessuno
Decisione: importazione consentita
Note: JSON completo e coerente

CASO 2 — ORD-1002
Esito: da rivedere
Campi mancanti: nessuno
Decisione: anteprima solo
Note: conversione esplicita 2 scatole = 24 pezzi; il dato sorgente resta 2 scatole

CASO 3 — ORD-1003
Esito: respinto
Campi mancanti: sku, unit
Decisione: blocco importazione
Note: il sistema non deve inventare valori

Troubleshooting concreto

Problema: il modello riempie i mancanti con valori finti

  • Rimedio: vieta default impliciti nel prompt e valida che i mancanti siano solo null più missing_fields.

Problema: la conversione sostituisce il dato sorgente

  • Rimedio: separa sempre quantità sorgente e quantità derivata; non sovrascrivere il valore iniziale.

Problema: l’unità non è riconosciuta

  • Rimedio: ferma il flusso e aggiungi una tabella di mappatura approvata prima del go-live.

Problema: numero ambiguo con virgola o punto

  • Rimedio: non interpretare automaticamente; chiedi conferma o imposta una regola locale univoca.

Problema: output incompleto o refusal

  • Rimedio: trattalo come non importabile. La documentazione OpenAI segnala che refusal e output incompleti possono verificarsi e devono essere gestiti dall’applicazione. Structured Outputs — Responses API

Prova finale ripetibile

Ripeti lo stesso ciclo su tre ordini, nello stesso ordine:

  1. ordine completo;
  2. ordine con conversione esplicita;
  3. ordine con campo mancante.

Criteri di accettazione

  • il primo record passa;
  • il secondo record non viene importato senza regola di conversione formalizzata;
  • il terzo record viene respinto;
  • nessun valore assente viene inventato;
  • il registro finale spiega perché ogni record è stato accettato o fermato.

Quando portare il flusso in produzione

La domanda giusta non è “quale modello usare?”, ma “quale regola rende importabile un ordine e chi decide quando fermarsi?”. Se il processo deve collegarsi a ERP, CRM o gestionali già in uso, conviene progettare prima governance, permessi e integrazioni, poi l’automazione. In questo passaggio sono utili AI e automazione responsabile e Sviluppo software su misura e integrazioni.

Per il controllo degli accessi e delle eccezioni nei collegamenti applicativi, può essere utile anche la logica di verifica descritta in Permessi delle integrazioni: una verifica pratica del minimo privilegio.

Limiti da tenere presenti

  • Lo schema e il prompt possono garantire che l’output sia ben formato, ma non possono garantire da soli che l’ordine sia semanticamente corretto.
  • Un JSON valido non basta se i campi obbligatori del processo mancano o se l’unità è ambigua.
  • Le conversioni vanno governate da regole di processo, non improvvisate dal modello.
  • Il laboratorio è didattico: gli ordini sono inventati e non provengono da casi aziendali reali.

Passo successivo

Se vuoi portare questa procedura in un progetto reale, il prossimo passo non è aggiungere altri default, ma definire:

  • quali campi sono davvero obbligatori;
  • quali conversioni sono ammesse;
  • chi approva i casi ambigui;
  • quale log deve accompagnare ogni importazione.

Solo dopo questa decisione il flusso AI può diventare affidabile abbastanza da scrivere nel gestionale.

Fonti