Guide til Xero-integration med SkyPlanner APS til produktionsplanlægning

Xero er ét cloudprodukt med flere tenants, og alle organisationer bruger samme API. Accounting API er et REST API på https://api.xero.com/api.xro/2.0/, som bruger JSON eller XML. Hvert kald angiver organisationen i headeren Xero-tenant-id. (kilde)

De endpoints, en produktionsplanlægger har brug for:

• Stamdata: /Contacts (kunder og leverandører), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Behov: /Quotes (Status ACCEPTED, LineItems) og, for værksteder der fakturerer først, /Invoices med Type ACCREC.
• Forsyning: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems med ItemCode).
• Tilbageskrivning: /Quotes/{QuoteID}/History, /Invoices, /Quotes og Projects API på https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Alle listeendpoints accepterer headeren If-Modified-Since, så hver synkronisering kun læser det, der er ændret. Oprettelser og opdateringer sendes i batches. Der findes intet endpoint til styklister, ruter eller produktionsordrer.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (Webhooks lader dig abonnere på bestemte hændelser i Xero.) (kilde) De relevante hændelser for produktionsplanlægning er Contact og Invoice, begge med CREATE og UPDATE.

Sådan fungerer de:

• Én webhook pr. app dækker alle tilsluttede organisationer.
• Hver levering indeholder et events-array med ressource-ID og hændelsestype. Modtageren læser derefter ressourcen.
• Hver levering signeres med headeren x-xero-signature, som dannes ud fra appens webhook-nøgle. Xero sender en “Intent to receive”-kontrol, før leveringerne begynder.
• Xero forsøger igen ved mislykkede leveringer og deaktiverer en webhook, der bliver ved med at fejle. Derfor svarer modtageren hurtigt og udfører arbejdet bagefter.

Tilbud, varer og indkøbsordrer har ingen webhook-hændelser. SkyPlanner læser dem med korte pollingintervaller og If-Modified-Since. Det kræver ét kald pr. entitet, når intet er ændret.

1. Første indlæsning af stamdata. Læs kontakter og varer side for side, derefter åbne indkøbsordrer og accepterede tilbud. Opret kunder i SkyPlanner med Xero ContactID som external_identifier, og produkter og materialer med varekoden som nøgle. Opret derefter det, Xero ikke indeholder: arbejdsstationer, procestrin pr. produkt, skiftehold, fravær og omstillingstider. Import fra CSV eller Excel er den hurtigste vej til at oprette procestrin.

2. Ordresynkronisering. Poll tilbud med If-Modified-Since. Når et tilbud får status ACCEPTED, opretter SkyPlanner en ordre med tilbudsnummeret som external_order_number. Værdien i delivery_date hentes fra det felt, dit værksted bruger til den lovede dato. Mappingen fastlægges under opstarten. Hver tilbudslinje bliver til opgaver ud fra produktets procestrin. Indkøbsordrelinjer bliver til indgående materiale på den forventede ankomstdato, så opgaverne venter på leveringen. En fuld læsning af åbne tilbud og indkøbsordrer hver nat fanger det, der måtte være overset.

3. Tilbageskrivning af plan og færdigmelding. Tre kald overfører resultaterne til Xero:

• PUT /Quotes/{QuoteID}/History tilføjer en note med den planlagte slutdato. På et accepteret tilbud kan kun kontakt og noter ændres, så datoen gemmes i historiknoten. (kilde)
• Når ordren er færdig, opretter POST /Invoices en salgsfaktura med Type ACCREC, Status DRAFT, tilbuddets kontakt og linjer samt tilbudsnummeret som Reference. Din bogholder godkender og sender den i Xero.
• POST /Quotes med QuoteID og Status INVOICED lukker tilbuddet. Skiftet fra Accepted til Invoiced er en gyldig statusændring i Accounting API.

4. Registreringer fra produktionen og projekttid. Operatørerne registrerer arbejde med SkyPlanner Mobile Confirmations, Production Timer eller Quick Log Mode. Fremdriften opdaterer straks planen, og Autopilot omplanlægger resten. Ved projektarbejde overfører SkyPlanner timerne som tidsregistreringer på projektopgaven med Xero-bruger, dato og varighed. (kilde)

5. Dataejerskab og konfliktregler. Skriv dem ned før idriftsættelsen:

• Ingen produktionsobjekter i Xero. Vedligehold procestrinnene for hvert produkt i SkyPlanner med Xeros varekode som nøgle. Undgå at ændre varekoderne.
• Tilbud har ingen webhook. Hent dem med korte intervaller via polling med If-Modified-Since, og hold jer inden for grænserne pr. minut og pr. dag.
• Accepterede tilbud er låst. Efter accept kan kun kontaktoplysninger og noter ændres. Derfor læses den lovede dato én gang ved accept, mens den planlagte dato skrives som en note i historikken.
• Lageret følger salgs- og købsfakturaer. Xero ændrer lagerbeholdningen via salgsfakturaer, købsfakturaer og kreditnotaer for lagerførte varer. Aftal med bogholderen, hvordan færdigvarer og forbrugte materialer skal bogføres.
• Projekttimer kræver Xero-brugere. Tidsregistreringer er knyttet til en Xero-bruger. Beslut, hvilke operatører der skal registrere tid i Xero Projects, og behold resten i SkyPlanner.
• Granulære scopes. Anmod om granulære scopes fra starten, da brede scopes er ved at blive udfaset.
• Appens partnerniveau. Partnerniveauet bestemmer, hvor mange organisationer en app kan forbinde, og hvor mange kald den kan foretage om dagen. Vælg niveau ud fra antallet af fabrikker.