Guida all’integrazione di monday.com con SkyPlanner APS per la schedulazione della produzione

monday.com espone un’unica GraphQL API all’indirizzo POST https://api.monday.com/v2. Viene rilasciata una versione ogni trimestre; l’header API-Version permette di fissare la versione da usare. Le deprecazioni vengono annunciate con almeno sei mesi di anticipo. (Gestione delle versioni dell’API)

Gli oggetti utilizzati da un’integrazione per la schedulazione:

• Boards e groups, spesso usati per organizzare fasi o settimane.
• Items e subitems. Un item rappresenta di solito un ordine o un’operazione, mentre i subitems contengono le operazioni.
• Valori delle colonne: Status, Date, Timeline, Numbers, People, Dependency, Time Tracking, Connect Boards e Mirror.
• Webhook per gli eventi di modifica.

Per le letture si usa items_page, annidato in una scheda o in un gruppo. La pagina predefinita contiene 25 elementi e “the maximum is 500.” (limite massimo). Si prosegue con next_items_page e “each cursor will expire 60 minutes after the first request.” (scadenza di ogni cursore calcolata dalla prima richiesta). Usa query_params per filtrare e leggere solo gli ordini aperti. (items_page)

Per le scritture si usano create_item, create_subitem, change_column_value e change_multiple_column_values. Quest’ultimo aggiorna più colonne di un elemento con una sola chiamata: è ciò che serve per riportare la schedulazione su monday.com.

Per i caricamenti di grandi dimensioni, dalla versione API 2026-07 sono disponibili ingest_items e backfill_items. Si carica un CSV su un URL prefirmato e si interroga periodicamente lo stato dell’elaborazione. (Importazione in blocco)

Crea una sottoscrizione con create_webhook(board_id, url, event, config). Gli eventi necessari per un’integrazione di schedulazione sono:

• create_item e create_subitem per nuovi ordini e operazioni.
• change_column_value o change_specific_column_value per le modifiche a data di consegna, quantità o priorità.
• change_status_column_value per le modifiche di stato effettuate dagli utenti.
• item_archived, item_deleted e item_moved_to_specific_group per gli ordini annullati o completati.

Alla creazione del webhook, l’URL di ricezione deve rispondere a un token di verifica. Per le consegne non riuscite, la documentazione indica: “retry once a minute for 30 minutes,” (un tentativo al minuto per il periodo indicato). Poi i tentativi si interrompono. Per questo l’integrazione esegue anche una lettura periodica di riconciliazione con items_page, filtrando gli elementi aggiornati di recente. (Webhook)

Nella direzione opposta, SkyPlanner invia webhook quando cambia lo stato o la schedulazione. Il servizio di integrazione li riceve e scrive le nuove date su monday.com: l’aggiornamento di ritorno è quindi guidato dagli eventi.

1. Caricamento iniziale delle anagrafiche. Leggi prodotti, materiali e ordini aperti con items_page. Crea centri di lavoro, turni e vincoli in SkyPlanner, oppure importali da Excel. Decidi fin dall’inizio se gestire le operazioni come sottoelementi o su una scheda collegata.

2. Sincronizzazione degli ordini. I webhook della scheda di produzione inviano a SkyPlanner gli elementi nuovi e modificati sotto forma di ordini. Se gestisci gli ordini di acquisto su una scheda, SkyPlanner considera il materiale ordinato disponibile alla data di consegna e aggiorna le giacenze quando l’ordine di acquisto viene contrassegnato come Delivered.

3. Scrittura della schedulazione su monday.com. Per ogni ordine inserito o spostato dal motore di schedulazione, l’integrazione chiama change_multiple_column_values. Imposta l’inizio e la fine pianificati nella colonna Timeline e compila la colonna del centro di lavoro. Una sola chiamata per elemento mantiene basso il numero di richieste.

4. Avanzamento nel reparto produttivo. Gli operatori registrano il lavoro con Mobile Confirmations, Production Timer o Quick Log Mode. Le registrazioni dei tempi mantengono aggiornata la schedulazione e l’etichetta Status corrispondente viene riportata sulla scheda: così il commerciale vede l’avanzamento senza dover chiedere.

5. Responsabilità sui dati e gestione dei conflitti. Documenta le regole prima della messa in esercizio:

La principale causa di conflitto sono le modifiche manuali alla colonna Timeline. Stabilisci che solo SkyPlanner possa scrivere in quella colonna, oppure tratta ogni modifica manuale come una richiesta e lascia che SkyPlanner ricalcoli la schedulazione. Autopilot la ricalcola automaticamente quando la produzione cambia.

• Ogni account struttura gli ordini in modo diverso. Una bacheca per cliente, operazioni come elementi o sottoelementi, macchine come colonne People o Status. Mappa gli ID delle colonne per ciascun account, mai in base al titolo della colonna.
• Limiti dei piani. Free, Basic e Standard consentono 1.000 chiamate API al giorno, Pro 10.000 ed Enterprise 25.000. Usa i webhook per le modifiche e raggruppa le scritture di ritorno con change_multiple_column_values. (limiti di frequenza)
• Il numero di bacheche collegate è limitato. Basic consente il collegamento a una bacheca e Standard a cinque, limitando così le bacheche di operazioni o prodotti che si possono collegare. (limiti di Connect Boards)
• Fissa la versione dell’API. Le versioni cambiano ogni trimestre. Prima della versione 2026-04, le bacheche multilivello erano escluse dalla query boards predefinita.
• Scadenza del cursore. Un cursore items_page ha una validità di 60 minuti. Le riconciliazioni lunghe devono poter ripartire correttamente da zero.
• Limiti dei webhook. L’URL può contenere al massimo 255 caratteri e i tentativi di reinvio si interrompono dopo 30 minuti. Il ricevitore deve essere idempotente.
• Unità e durate. Le colonne Numbers non specificano alcuna unità di misura. Prima della prima importazione, concorda se le durate sono espresse in minuti o in ore.