Ghid de integrare Xero pentru programarea producției cu SkyPlanner APS

Xero este un singur produs cloud cu arhitectură multi-tenant, iar toate organizațiile folosesc același API. Accounting API este un REST API disponibil la https://api.xero.com/api.xro/2.0/, cu date în format JSON sau XML. Fiecare apel identifică organizația în antetul Xero-tenant-id. (sursă)

Endpointurile necesare pentru programarea producției:

• Nomenclatoare: /Contacts (clienți și furnizori), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Cerere: /Quotes (Status ACCEPTED, LineItems) și, pentru atelierele care facturează mai întâi, /Invoices cu Type ACCREC.
• Aprovizionare: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems cu ItemCode).
• Scriere înapoi în Xero: /Quotes/{QuoteID}/History, /Invoices, /Quotes și Projects API la https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Fiecare endpoint de listare acceptă antetul If-Modified-Since, astfel încât fiecare sincronizare citește doar datele modificate. Operațiile de creare și actualizare se trimit în loturi. Nu există endpointuri pentru liste de materiale, fluxuri tehnologice sau comenzi de producție.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (Webhookurile vă permit să vă abonați la anumite evenimente din Xero.) (sursă) Evenimentele relevante pentru programarea producției sunt Contact și Invoice, fiecare cu CREATE și UPDATE.

Cum funcționează:

• Un singur webhook per aplicație acoperă toate organizațiile conectate.
• Fiecare mesaj transmis conține un tablou de evenimente cu ID-ul resursei și tipul evenimentului. Receptorul citește apoi resursa.
• Fiecare mesaj transmis este semnat printr-un antet x-xero-signature, generat pe baza cheii webhook a aplicației. Xero trimite o verificare „Intent to receive” (intenție de primire) înainte de a începe transmiterea mesajelor.
• Xero reîncearcă transmiterile eșuate și dezactivează webhookurile care eșuează în mod repetat. De aceea, receptorul răspunde rapid și prelucrează datele ulterior.

Ofertele, articolele și comenzile de achiziție nu au evenimente webhook. SkyPlanner le citește prin interogări periodice la intervale scurte, cu If-Modified-Since. Dacă nu s-a schimbat nimic, este necesar un apel per entitate.

1. Încărcarea inițială a nomenclatoarelor. Parcurgeți paginile de contacte și articole, apoi comenzile de achiziție deschise și ofertele acceptate. Creați clienți în SkyPlanner folosind ContactID din Xero ca external_identifier, iar produsele și materialele folosind codul articolului drept cheie. Configurați apoi ceea ce Xero nu stochează: centre de lucru, etape de proces pentru fiecare produs, schimburi, concedii și timpi de pregătire. Importul din CSV sau Excel este cea mai rapidă metodă pentru etapele de proces.

2. Sincronizarea comenzilor. Interogați periodic ofertele cu If-Modified-Since. Când o ofertă trece în starea ACCEPTED, SkyPlanner creează o comandă cu numărul ofertei în external_order_number. Valoarea delivery_date provine din câmpul pe care atelierul dumneavoastră îl folosește pentru data promisă, mapat în etapa de implementare. Fiecare poziție generează operații pe baza etapelor de proces ale produsului. Pozițiile comenzilor de achiziție devin materiale în curs de aprovizionare, cu data de sosire estimată, astfel încât operațiile așteaptă livrarea. O citire integrală, în fiecare noapte, a ofertelor și comenzilor de achiziție deschise recuperează orice date omise.

3. Trimiterea înapoi în Xero a datelor despre programul de producție și finalizarea comenzilor. Trei apeluri transferă rezultatele în Xero:

• PUT /Quotes/{QuoteID}/History adaugă o notă cu data de finalizare planificată. La o ofertă acceptată se pot modifica doar contactul și notele, așa că data este păstrată în nota din istoric. (sursă)
• La finalizarea comenzii, POST /Invoices creează o factură de vânzare cu Type ACCREC, Status DRAFT, contactul și pozițiile ofertei, iar numărul ofertei este folosit ca Reference. Contabilul dumneavoastră o aprobă și o trimite din Xero.
• POST /Quotes cu QuoteID și Status INVOICED închide oferta. Trecerea din Accepted în Invoiced este o schimbare de stare validă în Accounting API.

4. Confirmări din producție și timpul lucrat pe proiecte. Operatorii înregistrează lucrul efectuat cu SkyPlanner Mobile Confirmations, Production Timer sau Quick Log Mode. Progresul actualizează imediat programul de producție, iar Autopilot reprogramează restul operațiilor. Pentru lucrările din proiecte, SkyPlanner trimite orele ca înregistrări de timp pe sarcina din proiect, cu utilizatorul Xero, data și durata. (sursă)

5. Responsabilitatea pentru date și regulile de soluționare a conflictelor. Documentați-le înainte de punerea în funcțiune:

• Xero nu are obiecte pentru producție. Păstrați în SkyPlanner operațiile fiecărui produs, asociate codului de articol din Xero. Nu modificați codurile articolelor.
• Ofertele nu au notificări webhook. Interogați-le la intervale scurte cu If-Modified-Since, respectând limitele pe minut și pe zi.
• Ofertele acceptate sunt blocate. După acceptare se mai pot modifica doar datele de contact și notele. De aceea, data promisă este citită o singură dată, la acceptare, iar data planificată este scrisă ca notă în istoric.
• Stocul se actualizează pe baza facturilor de vânzare și de achiziție. Xero modifică stocul disponibil prin facturi de vânzare, facturi de achiziție și note de credit pentru articolele cu stoc urmărit. Stabiliți împreună cu contabilul cum se înregistrează produsele finite și materialele consumate.
• Pontajele pe proiecte necesită utilizatori Xero. Fiecare înregistrare de timp aparține unui utilizator Xero. Decideți pentru ce operatori se transmite timpul lucrat în Xero Projects și păstrați restul pontajelor în SkyPlanner.
• Permisiuni granulare. Solicitați de la început permisiuni granulare, deoarece permisiunile cu acces larg sunt în curs de eliminare.
• Nivelul aplicației. Nivelul de parteneriat stabilește câte organizații poate conecta o aplicație și câte apeluri poate efectua pe zi. Alegeți nivelul în funcție de numărul de fabrici.