Handleiding voor de Xero koppeling voor productieplanning met SkyPlanner APS

Xero is één multi-tenant cloudproduct: elke organisatie gebruikt dezelfde API. De Accounting API is een REST API op https://api.xero.com/api.xro/2.0/, met JSON of XML. Elke aanroep vermeldt de organisatie in de Xero-tenant-id-header. (bron)

De endpoints die een productieplanner nodig heeft:

• Stamgegevens: /Contacts (klanten en leveranciers), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Vraag: /Quotes (Status ACCEPTED, LineItems) en, voor productiebedrijven die vooraf factureren, /Invoices met Type ACCREC.
• Aanvoer: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems met ItemCode).
• Terugschrijven: /Quotes/{QuoteID}/History, /Invoices, /Quotes en de Projects API op https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Elk lijstendpoint accepteert een If-Modified-Since-header, zodat bij elke synchronisatie alleen gewijzigde gegevens worden ingelezen. Aanmaken en bijwerken gebeurt in batches. Er zijn geen endpoints voor stuklijsten, bewerkingsvolgordes of productieorders.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (Met webhooks kunt u zich abonneren op bepaalde gebeurtenissen in Xero.) (bron) Voor de productieplanning zijn de events Contact en Invoice van belang, beide met CREATE en UPDATE.

Zo werken ze:

• Eén webhook per app dekt alle gekoppelde organisaties.
• Elk bericht bevat een events-array met de resource-ID en het eventtype. De ontvanger haalt de resource daarna op.
• Elk bericht wordt ondertekend met een x-xero-signature-header, opgebouwd met de webhooksleutel van de app. Voordat Xero berichten gaat versturen, voert het een “Intent to receive”-controle uit.
• Xero probeert mislukte afleveringen opnieuw en schakelt een webhook uit als die blijft mislukken. Daarom antwoordt de ontvanger snel en verwerkt hij het bericht pas daarna.

Voor offertes, artikelen en inkooporders zijn er geen webhookevents. SkyPlanner leest ze met korte tussenpozen uit via polling met If-Modified-Since. Als er niets is gewijzigd, kost dat één aanroep per entiteit.

1. Eerste import van stamgegevens. Lees contacten en artikelen pagina voor pagina uit, gevolgd door openstaande inkooporders en geaccepteerde offertes. Maak in SkyPlanner klanten aan met de Xero ContactID als external_identifier, en producten en materialen met de artikelcode als sleutel. Richt vervolgens in wat Xero niet bevat: werkcentra, processtappen per product, ploegendiensten, verlof en insteltijden. Voor processtappen is import via CSV of Excel de snelste route.

2. Ordersynchronisatie. Haal offertes periodiek op met If-Modified-Since. Zodra een offerte de status ACCEPTED krijgt, maakt SkyPlanner een order aan met het offertenummer als external_order_number. De delivery_date komt uit het veld dat uw productiebedrijf gebruikt voor de toegezegde leverdatum. Deze mapping wordt tijdens de implementatie ingesteld. Elke offerteregel wordt omgezet in taken op basis van de processtappen van het product. Inkooporderregels worden inkomend materiaal met de verwachte aankomstdatum, zodat taken op de levering wachten. Elke nacht worden alle openstaande offertes en inkooporders volledig uitgelezen om eventuele gemiste wijzigingen op te vangen.

3. Planning en afronding terugschrijven. Drie aanroepen zetten de resultaten in Xero:

• PUT /Quotes/{QuoteID}/History voegt een notitie met de geplande einddatum toe. Bij een geaccepteerde offerte kunnen alleen het contact en de notities worden gewijzigd. Daarom wordt de datum in de historienotitie vastgelegd. (bron)
• Zodra de order is afgerond, maakt POST /Invoices een verkoopfactuur aan met Type ACCREC, Status DRAFT, het contact en de regels van de offerte, en het offertenummer als Reference. Uw boekhouder keurt de factuur in Xero goed en verstuurt deze.
• POST /Quotes met de QuoteID en Status INVOICED sluit de offerte af. Van Accepted naar Invoiced is een geldige statuswijziging in de Accounting API.

4. Terugmeldingen vanaf de werkvloer en projecturen. Operators registreren hun werk met SkyPlanner Mobile Confirmations, Production Timer of Quick Log Mode. De voortgang wordt direct in de planning verwerkt en Autopilot plant de rest opnieuw. Bij projectwerk schrijft SkyPlanner de uren als tijdregistraties naar de projecttaak, met de Xero-gebruiker, datum en duur. (bron)

5. Gegevenseigenaarschap en conflictregels. Leg deze vast vóór ingebruikname:

• Geen productieobjecten in Xero. Beheer de bewerkingsstappen per product in SkyPlanner en koppel ze aan de artikelcode in Xero. Houd artikelcodes ongewijzigd.
• Geen webhook voor offertes. Vraag ze met korte tussenpozen op via If-Modified-Since, binnen de limieten per minuut en per dag.
• Geaccepteerde offertes zijn vergrendeld. Na acceptatie kunnen alleen de contactgegevens en notities nog worden gewijzigd. Daarom wordt de toegezegde datum eenmalig bij acceptatie uitgelezen en wordt de geplande datum als notitie in de historie vastgelegd.
• Voorraadmutaties volgen uit verkoop- en inkoopfacturen. Xero wijzigt de aanwezige voorraad via verkoopfacturen, inkoopfacturen en creditnota’s voor artikelen met voorraadregistratie. Spreek met uw boekhouder af hoe gereed product en verbruikte materialen worden geboekt.
• Projecturen vereisen Xero-gebruikers. Elke urenboeking hoort bij een Xero-gebruiker. Bepaal welke operators uren naar Xero Projects boeken en houd de overige uren in SkyPlanner.
• Fijnmazige scopes. Vraag vanaf het begin fijnmazige scopes aan, want de brede scopes worden uitgefaseerd.
• Appniveau. Het partnerniveau bepaalt hoeveel organisaties een app kan koppelen en hoeveel API-aanroepen per dag beschikbaar zijn. Stem dit niveau af op het aantal productielocaties.