Leitfaden zur Xero Schnittstelle für die Feinplanung mit SkyPlanner APS

Xero ist ein mandantenfähiges Cloudprodukt. Jede Organisation nutzt dieselbe API. Die Accounting API ist eine REST API unter https://api.xero.com/api.xro/2.0/ und unterstützt JSON oder XML. Jeder Aufruf gibt die Organisation im Header Xero-tenant-id an. (Quelle)

Diese Endpunkte werden für die Feinplanung benötigt:

• Stammdaten: /Contacts (Kunden und Lieferanten), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Bedarf: /Quotes (Status ACCEPTED, LineItems) und für Betriebe, die zuerst die Rechnung stellen, /Invoices mit Type ACCREC.
• Materialzugänge: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems mit ItemCode).
• Rückschreiben: /Quotes/{QuoteID}/History, /Invoices, /Quotes und die Projects API unter https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Jeder Listenendpunkt akzeptiert den Header If-Modified-Since. So werden bei jeder Synchronisierung nur Änderungen gelesen. Datensätze werden stapelweise angelegt und aktualisiert. Für Stücklisten, Arbeitspläne oder Fertigungsaufträge gibt es keinen Endpunkt.

„Webhooks allow you to subscribe to certain events that happen in Xero.“ (Mit Webhooks können Sie bestimmte Ereignisse in Xero abonnieren.) (Quelle) Für die Feinplanung sind die Ereignisse Contact und Invoice relevant, jeweils mit CREATE und UPDATE.

So funktionieren sie:

• Ein Webhook pro App deckt alle verbundenen Organisationen ab.
• Jede Zustellung enthält ein events-Array mit Ressourcen-ID und Ereignistyp. Der Empfänger liest die Ressource anschließend aus.
• Jede Zustellung ist über den Header x-xero-signature signiert. Die Signatur wird aus dem Webhook-Schlüssel der App erzeugt. Vor der ersten Zustellung führt Xero eine Prüfung namens „Intent to receive“ durch.
• Xero wiederholt fehlgeschlagene Zustellungen und deaktiviert einen Webhook bei anhaltenden Fehlern. Deshalb antwortet der Empfänger zügig und erledigt die Verarbeitung anschließend.

Für Angebote, Artikel und Bestellungen gibt es keine Webhook-Ereignisse. SkyPlanner fragt sie in kurzen Intervallen mit If-Modified-Since ab. Wenn sich nichts geändert hat, ist dafür ein Aufruf pro Entität nötig.

1. Erstimport der Stammdaten. Lesen Sie Kontakte und Artikel seitenweise aus, danach offene Bestellungen und angenommene Angebote. Legen Sie in SkyPlanner Kunden mit der Xero ContactID als external_identifier an. Für Produkte und Materialien verwenden Sie den Artikelcode als Schlüssel. Richten Sie anschließend ein, was Xero nicht enthält: Arbeitsstationen, Prozessschritte je Produkt, Schichten, Urlaub und Rüstzeiten. Prozessschritte lassen sich am schnellsten per CSV- oder Excel-Import übernehmen.

2. Auftragssynchronisierung. Fragen Sie Angebote mit If-Modified-Since ab. Sobald ein Angebot den Status ACCEPTED erhält, erstellt SkyPlanner einen Auftrag mit der Angebotsnummer als external_order_number. Das Feld delivery_date wird aus dem Feld übernommen, das Ihr Betrieb für den zugesagten Termin verwendet. Diese Zuordnung wird beim Onboarding festgelegt. Aus jeder Angebotsposition entstehen Arbeitsgänge anhand der Prozessschritte des Produkts. Bestellpositionen werden zu Materialzugängen mit dem voraussichtlichen Ankunftstermin. Die Arbeitsgänge warten somit auf die Lieferung. Ein nächtlicher vollständiger Abruf aller offenen Angebote und Bestellungen erfasst alles, was zuvor übersehen wurde.

3. Planung und Fertigmeldungen zurückschreiben. Drei Aufrufe übertragen die Ergebnisse nach Xero:

• PUT /Quotes/{QuoteID}/History fügt eine Notiz mit dem geplanten Fertigstellungstermin hinzu. Bei einem angenommenen Angebot lassen sich nur Kontakt und Notizen ändern. Daher wird der Termin in der Verlaufsnotiz hinterlegt. (Quelle)
• Wenn der Auftrag abgeschlossen ist, erstellt POST /Invoices eine Ausgangsrechnung mit Type ACCREC, Status DRAFT, dem Kontakt und den Positionen des Angebots sowie der Angebotsnummer als Reference. Ihre Buchhaltung gibt die Rechnung in Xero frei und versendet sie dort.
• POST /Quotes mit der QuoteID und Status INVOICED schließt das Angebot ab. Der Wechsel von Accepted zu Invoiced ist in der Accounting API zulässig.

4. Rückmeldungen aus der Fertigung und Projektzeiten. Bediener erfassen ihre Arbeit mit SkyPlanner Mobile Confirmations, Production Timer oder Quick Log Mode. Der Fortschritt aktualisiert den Plan sofort, und Autopilot plant die verbleibenden Arbeiten neu. Bei Projektarbeiten überträgt SkyPlanner die Stunden als Zeiteinträge zur Projektaufgabe, einschließlich Xero-Benutzer, Datum und Dauer. (Quelle)

5. Datenhoheit und Konfliktregeln. Halten Sie diese vor dem Produktivstart schriftlich fest:

• Keine Produktionsobjekte in Xero. Pflegen Sie die Prozessschritte je Produkt in SkyPlanner und verknüpfen Sie diese über den Xero-Artikelcode. Ändern Sie die Artikelcodes nicht.
• Keine Webhooks für Angebote. Fragen Sie Angebote mit If-Modified-Since in kurzen Abständen ab und halten Sie dabei die Limits pro Minute und pro Tag ein.
• Angenommene Angebote sind gesperrt. Nach der Annahme lassen sich nur noch Kontaktdaten und Notizen ändern. Deshalb wird der zugesagte Termin bei der Annahme einmalig ausgelesen und der geplante Termin als Notiz im Verlauf hinterlegt.
• Rechnungen bestimmen den Lagerbestand. Xero verändert den vorhandenen Bestand bestandsgeführter Artikel über Ausgangsrechnungen, Eingangsrechnungen und Gutschriften. Stimmen Sie mit Ihrer Buchhaltung ab, wie Fertigwaren und verbrauchte Materialien verbucht werden.
• Für Projektzeiten sind Xero-Benutzer erforderlich. Zeiteinträge sind einem Xero-Benutzer zugeordnet. Legen Sie fest, welche Bediener Zeiten in Xero Projects buchen. Die übrigen Zeiten bleiben in SkyPlanner.
• Granulare Scopes. Fordern Sie von Anfang an granulare Scopes an, da weitreichende Scopes abgeschafft werden.
• App-Tarif. Die Partner-Tarifstufe legt fest, wie viele Organisationen eine App anbinden kann und wie viele Aufrufe ihr pro Tag zur Verfügung stehen. Berücksichtigen Sie bei der Tarifwahl die Anzahl der Werke.