Guide till Xero-integration för produktionsplanering med SkyPlanner APS

Xero är en gemensam molnprodukt för flera organisationer, och alla organisationer använder samma API. Accounting API är ett REST API på https://api.xero.com/api.xro/2.0/ med stöd för JSON och XML. I varje anrop anges organisationen i headern Xero-tenant-id. (källa)

Endpoints som behövs för produktionsplanering:

• Grunddata: /Contacts (kunder och leverantörer), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Efterfrågan: /Quotes (Status ACCEPTED, LineItems) och, för verkstäder som fakturerar först, /Invoices med Type ACCREC.
• Materialförsörjning: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems med ItemCode).
• Återföring: /Quotes/{QuoteID}/History, /Invoices, /Quotes och Projects API på https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Alla endpoints för listor accepterar headern If-Modified-Since, så att bara ändrade uppgifter läses vid varje synkronisering. Poster skapas och uppdateras i batcher. Det finns inga endpoints för stycklistor, operationsföljder eller tillverkningsorder.

”Webhooks allow you to subscribe to certain events that happen in Xero.” (Med webhooks kan du prenumerera på vissa händelser i Xero.) (källa) De händelser som är relevanta för produktionsplaneringen är Contact och Invoice, båda med CREATE och UPDATE.

Så fungerar de:

• En webhook per app täcker alla anslutna organisationer.
• Varje leverans innehåller en array med händelser som anger resurs-ID och händelsetyp. Mottagaren läser sedan in resursen.
• Varje leverans signeras med headern x-xero-signature, som skapas med appens webhook-nyckel. Xero skickar en kontroll av typen ”Intent to receive” innan leveranserna börjar.
• Xero försöker på nytt om en leverans misslyckas och inaktiverar en webhook som fortsätter att misslyckas. Därför svarar mottagaren snabbt och utför arbetet efteråt.

Offerter, artiklar och inköpsorder har inga webhook-händelser. SkyPlanner läser dem med korta pollingintervall och If-Modified-Since. När inget har ändrats krävs ett anrop per entitet.

1. Första inläsning av grunddata. Läs in kontakter och artiklar sida för sida, därefter öppna inköpsorder och accepterade offerter. Skapa kunder i SkyPlanner med Xeros ContactID som external_identifier och produkter och material med artikelkoden som nyckel. Lägg sedan upp det som saknas i Xero: produktionsgrupper, processteg per produkt, skift, ledighet och ställtider. Import från CSV eller Excel är det snabbaste sättet att lägga upp processteg.

2. Ordersynkronisering. Hämta offerter genom polling med If-Modified-Since. När en offert får status ACCEPTED skapar SkyPlanner en order med offertnumret som external_order_number. Värdet för delivery_date hämtas från det fält som verkstaden använder för utlovat leveransdatum. Mappningen görs under införandet. Varje offertrad blir operationer utifrån produktens processteg. Inköpsorderrader blir inkommande material på förväntat ankomstdatum, så att operationerna väntar på leveransen. En fullständig nattlig inläsning av öppna offerter och inköpsorder fångar upp sådant som kan ha missats.

3. Återföring av planering och färdiga order. Tre anrop för över resultaten till Xero:

• PUT /Quotes/{QuoteID}/History lägger till en anteckning med planerat slutdatum. I en accepterad offert får endast kontaktuppgifter och anteckningar ändras, så datumet sparas i historikanteckningen. (källa)
• När ordern är färdig skapar POST /Invoices en kundfaktura med Type ACCREC, Status DRAFT, offertens kontakt och rader samt offertnumret som Reference. Din redovisningsansvariga godkänner och skickar fakturan i Xero.
• POST /Quotes med QuoteID och Status INVOICED avslutar offerten. Ändringen från Accepted till Invoiced är en giltig statusändring i Accounting API.

4. Återrapportering från produktionen och projekttid. Operatörerna registrerar arbete med SkyPlanner Mobile Confirmations, Production Timer eller Quick Log Mode. Produktionsplanen uppdateras direkt när arbetet går framåt, och Autopilot planerar om resten. För projektarbete skickar SkyPlanner timmarna som tidposter på projektuppgiften med Xero-användare, datum och tidsåtgång. (källa)

5. Dataägarskap och regler vid konflikter. Dokumentera dem före driftsättning:

• Xero saknar produktionsobjekt. Lagra processtegen för varje produkt i SkyPlanner, kopplade till artikelkoden i Xero. Håll artikelkoderna oförändrade.
• Offerter saknar webhook. Hämta dem med korta intervall med If-Modified-Since, utan att överskrida gränserna per minut och dygn.
• Accepterade offerter är låsta. Efter accept kan bara kontaktuppgifter och anteckningar ändras. Därför läses det utlovade datumet in en gång vid accept, medan det planerade datumet skrivs som en anteckning i historiken.
• Lagersaldot följer kund- och leverantörsfakturorna. Xero ändrar lagersaldot för lagerförda artiklar genom kundfakturor, leverantörsfakturor och kreditnotor. Kom överens med din redovisningsansvariga om hur färdiga varor och förbrukat material ska bokföras.
• Projekttid kräver Xero-användare. Tidposter tillhör en användare i Xero. Bestäm vilka operatörer som ska rapportera tid till Xero Projects och behåll övrig tid i SkyPlanner.
• Detaljerade behörighetsomfång. Begär detaljerade behörighetsomfång från början, eftersom de breda omfången håller på att avvecklas.
• Appnivå. Partnernivån avgör hur många organisationer en app kan ansluta och hur många anrop den får göra per dag. Välj nivå utifrån antalet fabriker.