Przewodnik po integracji Xero ze SkyPlanner APS do planowania produkcji

Xero to jeden produkt chmurowy w architekturze wielodostępnej, a wszystkie organizacje korzystają z tego samego API. Accounting API to REST API dostępne pod adresem https://api.xero.com/api.xro/2.0/, obsługujące JSON lub XML. Każde wywołanie wskazuje organizację w nagłówku Xero-tenant-id. (źródło)

Endpointy potrzebne do harmonogramowania:

• Dane podstawowe: /Contacts (klienci i dostawcy), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Zapotrzebowanie: /Quotes (Status ACCEPTED, LineItems), a dla zakładów, które najpierw wystawiają fakturę — /Invoices z wartością ACCREC w polu Type.
• Zaopatrzenie: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems z ItemCode).
• Zapis zwrotny: /Quotes/{QuoteID}/History, /Invoices, /Quotes oraz Projects API pod adresem https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Każdy endpoint zwracający listę obsługuje nagłówek If-Modified-Since, więc każda synchronizacja odczytuje tylko zmienione dane. Tworzenie i aktualizowanie rekordów odbywa się zbiorczo. Nie ma endpointów dla zestawień materiałowych, marszrut technologicznych ani zleceń produkcyjnych.

„Webhooks allow you to subscribe to certain events that happen in Xero.” (Webhooki umożliwiają subskrybowanie określonych zdarzeń w Xero.) (źródło) Dla harmonogramowania istotne są zdarzenia Contact i Invoice, w obu przypadkach z typami CREATE i UPDATE.

Jak działają:

• Jeden webhook na aplikację obsługuje wszystkie połączone organizacje.
• Każda dostarczona wiadomość zawiera tablicę zdarzeń z identyfikatorem zasobu i typem zdarzenia. Odbiorca następnie odczytuje zasób.
• Każda wiadomość jest podpisana za pomocą nagłówka x-xero-signature, utworzonego na podstawie klucza webhooka aplikacji. Przed rozpoczęciem dostarczania Xero wysyła żądanie weryfikacyjne „Intent to receive”.
• Xero ponawia nieudane próby dostarczenia i wyłącza webhook, jeśli błędy się powtarzają. Dlatego odbiorca odpowiada szybko, a przetwarzanie wykonuje później.

Oferty, pozycje i zamówienia zakupu nie mają zdarzeń webhook. SkyPlanner odpytuje je w krótkich odstępach z użyciem If-Modified-Since. Jeśli nic się nie zmieniło, wymaga to jednego wywołania na typ obiektu.

1. Początkowy import danych podstawowych. Pobierz kolejne strony kontaktów i pozycji, a następnie otwarte zamówienia zakupu i zaakceptowane oferty. Utwórz klientów w SkyPlanner, używając ContactID z Xero jako external_identifier, a produkty i materiały — używając kodu pozycji jako klucza. Następnie zdefiniuj to, czego nie przechowuje Xero: stanowiska robocze, etapy procesu dla każdego produktu, zmiany robocze, urlopy i czasy przezbrojeń. Etapy procesu najszybciej zaimportujesz z pliku CSV lub Excel.

2. Synchronizacja zleceń. Odpytuj oferty z użyciem If-Modified-Since. Gdy oferta otrzyma status ACCEPTED, SkyPlanner tworzy zlecenie z numerem oferty w polu external_order_number. Wartość delivery_date pochodzi z pola, w którym zakład zapisuje obiecany termin; mapowanie ustala się podczas wdrożenia. Każda pozycja oferty jest przekształcana w operacje zgodnie z etapami procesu danego produktu. Pozycje zamówień zakupu stają się oczekiwanymi dostawami materiałów z przewidywanym terminem przybycia, więc operacje czekają na dostawę. Pełny odczyt otwartych ofert i zamówień zakupu każdej nocy wychwytuje pominięte zmiany.

3. Zapis zwrotny informacji o harmonogramie i zakończeniu zleceń. Trzy wywołania zapisują wyniki w Xero:

• PUT /Quotes/{QuoteID}/History dodaje notatkę z planowanym terminem zakończenia. W zaakceptowanej ofercie można zmieniać tylko kontakt i notatki, dlatego termin zapisuje się w notatce w historii. (źródło)
• Po zakończeniu zlecenia POST /Invoices tworzy fakturę sprzedaży z wartością ACCREC w polu Type i DRAFT w polu Status, kontaktem i pozycjami z oferty oraz numerem oferty w polu Reference. Osoba odpowiedzialna za księgowość zatwierdza ją i wysyła w Xero.
• POST /Quotes z identyfikatorem QuoteID i wartością INVOICED w polu Status zamyka ofertę. Przejście ze statusu Accepted do Invoiced jest dozwolone w Accounting API.

4. Potwierdzenia z hali produkcyjnej i czas pracy przy projektach. Operatorzy rejestrują pracę za pomocą SkyPlanner Mobile Confirmations, Production Timer lub Quick Log Mode. Postęp prac natychmiast aktualizuje harmonogram, a Autopilot przeplanowuje pozostałą pracę. W przypadku prac projektowych SkyPlanner zapisuje godziny jako wpisy czasu pracy przy zadaniu projektowym, wskazując użytkownika Xero, datę i czas trwania. (źródło)

5. Odpowiedzialność za dane i zasady rozstrzygania konfliktów. Spisz je przed uruchomieniem:

• Brak obiektów produkcyjnych w Xero. Przechowuj operacje dla poszczególnych produktów w SkyPlanner i powiąż je z kodem pozycji w Xero. Nie zmieniaj kodów pozycji.
• Oferty nie obsługują webhooków. Odpytuj je w krótkich odstępach za pomocą If-Modified-Since, przestrzegając limitów minutowych i dziennych.
• Zaakceptowane oferty są zablokowane. Po akceptacji można zmieniać tylko dane kontaktowe i notatki. Dlatego zadeklarowany termin jest odczytywany jednorazowo w chwili akceptacji, a planowany termin jest zapisywany jako notatka w historii.
• Stany magazynowe wynikają z faktur sprzedaży i zakupu. Xero aktualizuje ilość na stanie na podstawie faktur sprzedaży, faktur zakupu i korekt dla pozycji objętych ewidencją magazynową. Ustal z księgowością, jak rozliczać wyroby gotowe i zużyte materiały.
• Ewidencja czasu projektów wymaga użytkowników Xero. Wpisy czasu pracy są przypisane do użytkownika Xero. Zdecyduj, którzy operatorzy mają rejestrować czas w Xero Projects, a ewidencję pozostałych pozostaw w SkyPlanner.
• Szczegółowe zakresy uprawnień. Wnioskuj o szczegółowe zakresy uprawnień od samego początku, ponieważ szerokie zakresy są wycofywane.
• Poziom partnerski aplikacji. Poziom partnerski określa, z iloma organizacjami aplikacja może się połączyć i ile wywołań dziennie może wykonać. Dobierz go do liczby zakładów.