Guida all’integrazione di Xero per la schedulazione della produzione con SkyPlanner APS

Xero è un unico prodotto cloud multi-tenant: tutte le organizzazioni utilizzano la stessa API. Accounting API è una REST API disponibile all’indirizzo https://api.xero.com/api.xro/2.0/, con dati in JSON o XML. Ogni chiamata identifica l’organizzazione nell’header Xero-tenant-id. (fonte)

Gli endpoint necessari per la schedulazione:

• Anagrafiche: /Contacts (clienti e fornitori), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Domanda: /Quotes (Status ACCEPTED, LineItems) e, per le officine che fatturano prima della produzione, /Invoices con Type ACCREC.
• Approvvigionamenti: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems con ItemCode).
• Scrittura dei dati in Xero: /Quotes/{QuoteID}/History, /Invoices, /Quotes e Projects API all’indirizzo https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Ogni endpoint che restituisce un elenco accetta l’header If-Modified-Since: a ogni sincronizzazione vengono quindi letti solo i dati modificati. Creazioni e aggiornamenti vengono inviati in batch. Non esistono endpoint per distinte base, cicli di lavorazione o ordini di produzione.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (I webhook permettono di ricevere notifiche su determinati eventi che si verificano in Xero.) (fonte) Gli eventi rilevanti per la schedulazione sono Contact e Invoice, entrambi con CREATE e UPDATE.

Come funzionano:

• Un solo webhook per app copre tutte le organizzazioni collegate.
• Ogni notifica contiene un array di eventi con l’ID della risorsa e il tipo di evento. Il destinatario legge poi la risorsa.
• Ogni notifica è firmata tramite l’header x-xero-signature, generato a partire dalla chiave webhook dell’app. Prima di iniziare l’invio delle notifiche, Xero esegue una verifica “Intent to receive”.
• Xero ritenta l’invio delle notifiche non recapitate e disabilita i webhook che continuano a fallire. Il destinatario risponde quindi subito ed esegue l’elaborazione in un secondo momento.

Preventivi, articoli e ordini di acquisto non dispongono di eventi webhook. SkyPlanner li legge tramite polling a intervalli brevi con If-Modified-Since: quando non ci sono modifiche, è sufficiente una chiamata per entità.

1. Caricamento iniziale delle anagrafiche. Leggi contatti e articoli pagina per pagina, quindi gli ordini di acquisto aperti e i preventivi accettati. Crea i clienti in SkyPlanner usando il ContactID di Xero come external_identifier, e i prodotti e materiali usando il codice articolo come chiave. Configura poi ciò che Xero non contiene: centri di lavoro, fasi di lavorazione per ciascun prodotto, turni, ferie e permessi e tempi di attrezzaggio. Per le fasi di lavorazione, l’importazione da CSV o Excel è la via più rapida.

2. Sincronizzazione degli ordini. Interroga periodicamente i preventivi con If-Modified-Since. Quando un preventivo passa ad ACCEPTED, SkyPlanner crea un ordine usando il numero del preventivo come external_order_number. La delivery_date viene ricavata dal campo che la tua officina usa per la data di consegna promessa, mappato durante l’avviamento. Da ogni riga vengono generate le operazioni previste dalle fasi di lavorazione del prodotto. Le righe degli ordini di acquisto diventano materiale in arrivo alla data prevista, così le operazioni attendono la consegna. Una lettura completa ogni notte dei preventivi e degli ordini di acquisto aperti recupera eventuali dati sfuggiti alla sincronizzazione.

3. Invio a Xero del programma di produzione e dei dati di completamento. Tre chiamate trasferiscono i risultati in Xero:

• PUT /Quotes/{QuoteID}/History aggiunge una nota con la data di fine pianificata. Un preventivo accettato consente di modificare solo il contatto e le note: la data viene quindi inserita nella nota della cronologia. (fonte)
• Al completamento dell’ordine, POST /Invoices crea una fattura di vendita con Type ACCREC, Status DRAFT, il contatto e le righe del preventivo e il numero del preventivo come Reference. Il tuo addetto alla contabilità la approva e la invia in Xero.
• POST /Quotes con QuoteID e Status INVOICED chiude il preventivo. Il passaggio da Accepted a Invoiced è un cambio di stato valido in Accounting API.

4. Conferme dal reparto e ore di progetto. Gli operatori registrano il lavoro con SkyPlanner Mobile Confirmations, Production Timer o Quick Log Mode. L’avanzamento aggiorna immediatamente il programma di produzione e Autopilot ripianifica il lavoro restante. Per le attività di progetto, SkyPlanner invia le ore come registrazioni sull’attività del progetto, indicando utente Xero, data e durata. (fonte)

5. Responsabilità sui dati e regole per i conflitti. Mettile per iscritto prima della messa in produzione:

• Xero non prevede oggetti per la produzione. Gestisci le fasi di lavorazione di ogni prodotto in SkyPlanner, collegandole al codice articolo Xero. Mantieni stabili i codici articolo.
• I preventivi non hanno webhook. Interrogali con If-Modified-Since a intervalli brevi, rispettando i limiti al minuto e giornalieri.
• I preventivi accettati sono bloccati. Dopo l’accettazione si possono modificare solo i dati di contatto e le note. La data promessa viene quindi letta una sola volta, al momento dell’accettazione, mentre la data pianificata viene scritta come nota nella cronologia.
• Le giacenze seguono le fatture di vendita e di acquisto. Xero aggiorna le quantità a magazzino tramite fatture di vendita, fatture di acquisto e note di credito relative agli articoli con gestione delle giacenze. Concorda con chi segue la contabilità come contabilizzare i prodotti finiti e i materiali utilizzati.
• Le ore di progetto richiedono utenti Xero. Ogni registrazione delle ore è associata a un utente Xero. Decidi quali operatori registrano le ore in Xero Projects e mantieni le altre registrazioni in SkyPlanner.
• Ambiti di autorizzazione granulari. Richiedi ambiti granulari fin dall’inizio, perché quelli più ampi sono in fase di dismissione.
• Livello dell’app. Il livello partner determina quante organizzazioni può collegare un’app e quante chiamate può effettuare al giorno. Scegli il livello in base al numero di stabilimenti.