Gestione degli Errori
Come Funziona la Validazione​
Ympact valida ogni record in modo asincrono dopo la ricezione. I record validi vengono elaborati e resi visibili nel portale Ympact. I record non validi vengono rifiutati e i dettagli dell'errore vengono restituiti attraverso lo stesso canale utilizzato per l'invio.
Coda messaggi (JSON) — gli errori di validazione vengono consegnati in una coda di errori dedicata, fornita da Ympact insieme alla coda di invio. La tua integrazione deve consumare questa coda per rilevare e gestire i record rifiutati in modo programmatico.
SFTP (CSV) — gli errori di validazione vengono scritti in un file di errori depositato sullo stesso server SFTP, in una cartella di output dedicata. Ogni file di errori corrisponde al file inviato e contiene una riga per ogni record rifiutato, con il codice di errore e una descrizione.
Errori di Validazione Comuni​
| Errore | Causa | Soluzione |
|---|---|---|
MISSING_REQUIRED_FIELD | Un campo obbligatorio è assente o vuoto | Aggiungere il campo mancante al payload o alla riga CSV |
INVALID_DATE_FORMAT | La data non è nel formato YYYY-MM-DD | Usare il formato data corretto (es. 2025-01-15) |
INVALID_ENUM_VALUE | Il valore del campo non è nella lista ammessa | Verificare la tabella dei valori ammessi nella guida dell'entità |
DUPLICATE_PRIMARY_KEY | Esiste già un record con la stessa chiave primaria ma con campi non aggiornabili diversi | Verificare i valori della chiave primaria o controllare se il record è già stato inviato |
SHIPMENT_NOT_FOUND | Un Documento fa riferimento a un shipment_reference_id che non esiste | Inviare prima la Shipment, poi il Documento |
INVALID_NUMERIC_FORMAT | Un campo numerico contiene dati non numerici | Assicurarsi che i campi numerici contengano valori validi |
UNPROCESSABLE_ENTITY | Violazione di una regola di business (es. quantità superiore al limite della riga PO) | Revisionare la logica della richiesta rispetto alle regole di business |
Come Correggere e Re-inviare​
Per correggere un record rifiutato:
- Identificare l'errore dal feedback di validazione
- Correggere il valore del campo nel payload o CSV
- Reinviare il record con la stessa chiave primaria
Ympact esegue un upsert: se la chiave primaria esiste già , il record viene aggiornato con i nuovi valori. Solo i campi aggiornabili vengono modificati. Vedi la guida di ogni entità per sapere quali campi possono essere aggiornati.
Utilizzo di traceId​
Includere sempre il traceId quando si segnalano problemi — consente al team di supporto di localizzare la richiesta nei log del server.