Date nei fogli di calcolo e API: evita formati ambigui e cambi di giorno

Perché una data che sembra uguale può avere significati diversi

Una cella può mostrare «03/04/2025», ma questo aspetto non basta per capire se rappresenta il 3 aprile o il 4 marzo. Il foglio può interpretare il valore in base alle impostazioni, al formato della cella o al modo in cui è stato inserito. Quando il dato viene inviato a un altro sistema, anche l’API può applicare regole proprie. Microsoft spiega che le regole per interpretare le date nei programmi per fogli di calcolo possono essere complesse e consiglia di specificarle nel modo più dettagliato possibile nella sua guida sui sistemi, i formati e l’interpretazione delle date: https://support.microsoft.com/es-es/excel/change-the-date-system-format-or-two-digit-year-interpretation.

Perciò, non usare la visualizzazione come contratto di integrazione. Prima di esportare, individua le celle che contengono date, verifica quale valore rappresentano e concorda come il sistema deve riceverle. La guida ai formati di data e numero di Google Sheets API descrive i modelli di formato che possono essere inclusi nelle richieste; consulta la documentazione del servizio specifico per verificare quali sono supportati: https://developers.google.com/workspace/sheets/api/guides/formats?hl=es-419.

• Evita le date numeriche in cui giorno e mese possono essere scambiati, se il contratto non ne definisce l’ordine.
• Non dare per scontato che il formato visibile di una cella determini il modo in cui l’API interpreterà il dato.

Stabilisci se il campo è una data di calendario o un istante

Prima di scegliere un formato, definisci il significato del campo. In questa guida, una data di calendario identifica un giorno, come la scadenza di un’attività; da sola non indica un’ora né un luogo. Un istante rappresenta un punto preciso nel tempo, come l’ora in cui è stata registrata un’operazione. Anche se entrambi i valori appaiono come date in un foglio di calcolo, il contratto deve chiarire quale dei due significati è previsto.

Indica questa distinzione nel contratto dati, non solo in una nota informale. Per ogni colonna, registra il nome, il significato, il tipo previsto, l’eventuale ammissibilità di valori vuoti e un esempio valido. Se un campo rappresenta solo un giorno, non aggiungere un’ora fittizia per soddisfare un’integrazione. Se rappresenta un istante, specifica come esprimere l’ora e il contesto orario richiesto dal sistema che riceve il dato.

• Chiediti: «Il dato deve restare lo stesso giorno per tutti gli utenti?» Se sì, definisci il campo come data di calendario.
• Chiediti: «Dobbiamo sapere quando è successo qualcosa?» Se sì, definisci come gestire l’ora e il contesto orario per quell’integrazione.

Usa una rappresentazione esplicita e un contratto dati

Come scelta per il contratto di questa integrazione, puoi adottare un modello ordinato con anno, mese e giorno, come «2025-04-03», invece di «03/04/2025». Per gli istanti, specifica anche come esprimere l’ora e il contesto orario. Non dipendere dalle impostazioni locali del foglio di calcolo: chi produce e chi riceve i dati devono concordare lo stesso formato e lo stesso significato.

Documenta le eccezioni rilevanti per il servizio specifico: se sono ammessi i secondi, qual è la precisione, come si indica il contesto orario e che cosa viene considerato non valido. Non confondere il formato con il significato: una cella visualizzata come data potrebbe contenere testo o un altro valore. La guida di Google Sheets API citata sopra riguarda i modelli di formato che possono essere inclusi nelle richieste; non sostituisce la definizione del contratto e non stabilisce, da sola, che cosa significhi un campo nella tua integrazione.

• Definisci per ogni colonna il formato, il tipo, il contesto orario se applicabile, la precisione, l’obbligatorietà e un esempio.
• Rifiuta i valori che non rispettano il contratto o sottoponili a revisione; non «correggerli» in modo silenzioso.

Specifica il contesto orario quando è necessario

Se il campo esprime solo una data di calendario, definisci se il processo richiede ulteriori informazioni orarie. Per un evento con un’ora precisa, concorda il contesto orario che useranno chi produce e chi riceve i dati e registra la decisione nel contratto. Evita di mescolare un’ora locale con un’interpretazione diversa in un’altra parte del flusso.

Se il flusso deve conservare l’ora locale di un evento, documenta il criterio e verifica i casi importanti per quell’integrazione, compresi quelli vicini alla mezzanotte. Un cambio di giorno nella visualizzazione non basta, da solo, per concludere che il dato originale sia stato corrotto: confronta il risultato con il significato e le regole definiti nel contratto. Se il campo esprime solo una data, evita di aggiungere informazioni orarie non necessarie al processo.

• Per ogni istante, documenta il contesto orario concordato da chi produce e chi riceve i dati.
• Verifica i casi vicini alla mezzanotte rilevanti per il flusso; prima di decidere se si tratta di un errore, confronta il risultato con il contratto.

Verifica i casi previsti per la tua integrazione

Per verificare il comportamento di un flusso specifico, prepara casi di test coerenti con il suo contratto. Puoi includere date in cui giorno e mese possono essere confusi, valori vicini al cambio di giorno, una cella vuota, testo che non è una data e un valore con precisione o contesto orario inatteso. Decidi in anticipo se ogni caso deve essere accettato, rifiutato o sottoposto a revisione. Questo elenco è una pratica di convalida per l’integrazione, non un’affermazione sui requisiti di uno standard esterno.

La gestione dei valori vuoti merita una regola specifica. Definisci che cosa significa una cella vuota ed evita che il processo le assegni automaticamente un altro valore non concordato. Se il flusso deve distinguere tra «dato assente», «sconosciuto» e «non applicabile», documenta queste opzioni. Per i valori non validi, definisci una risposta identificabile oppure interrompi l’invio per correggere la fonte; non sostituire i dati senza segnalarlo.

• Possibile elenco di test: data ambigua, fine mese, cambio d’anno, mezzanotte, cella vuota e testo non valido.
• Verifica che cosa riceve il sistema destinatario e che cosa vede l’operatore quando una convalida non va a buon fine.

Verifica il percorso dei dati prima di utilizzarlo

Come controllo pratico del flusso specifico, prepara un piccolo insieme di record rappresentativi e conserva una copia dei valori iniziali. Inviali lungo il percorso previsto e controlla il valore ricevuto; se il processo prevede di ricaricarlo in un foglio, verifica anche il risultato. Confronta il significato, non solo l’aspetto: una data che torna con uno stile visivo diverso può essere comunque corretta, mentre un cambio di giorno o di ora può violare il contratto.

Ripeti la verifica con i casi scelti e annota il risultato previsto e quello osservato. Se rilevi una differenza, verifica in quale fase si è presentata: interpretazione del foglio, trasformazione, richiesta all’API o visualizzazione della risposta. Modifica il contratto o la conversione e poi ripeti lo stesso test per verificare l’effetto del cambiamento.

• Conserva l’input, il valore inviato, la risposta e il risultato visibile per confrontare ogni passaggio.
• Considera la verifica superata solo se il significato concordato è conservato e gli errori previsti vengono rilevati.

Organizza la revisione e l’integrazione in Apification

Come flusso di lavoro, mantieni un foglio di test separato dai dati operativi. Con Apification Cloud puoi organizzare file e progetti in uno spazio di lavoro con controllo delle versioni e creare o modificare fogli di calcolo con ONLYOFFICE senza spostarli fuori dall’archiviazione di Cloud. Controlla intestazioni, formati visibili, celle vuote ed esempi prima di preparare l’integrazione. Il foglio facilita la revisione del team, ma non sostituisce le regole di convalida del servizio che invia o riceve i dati.

Apification permette di integrare Cloud e i relativi servizi tramite REST API, OpenAPI, webhook, iframe e JavaScript. Consulta la documentazione API pertinente per definire lo scambio effettivo: non dare per scontato un endpoint o un comportamento specifico sulla base di queste funzionalità. Dopo una modifica importante, la cronologia degli elementi di Cloud consente di consultare versioni precedenti, scaricarle e ripristinare i contenuti. Questa funzione aiuta a recuperare un foglio di lavoro, ma non sostituisce la verifica del contratto né il controllo dei risultati.

• Prima di collegare dati reali, convalida una copia di lavoro con esempi rappresentativi e regole concordate.
• Verifica nella documentazione API quale operazione e quale formato supporta il servizio specifico.
• Se un foglio viene modificato, consulta la cronologia e conserva una versione nota per facilitare il ripristino.

Domande frequenti