Integraatiot / ERP / Xero
Xero-integraatio-opas tuotannonsuunnitteluun SkyPlanner APS:llä
Tämä Xero-integraatio-opas kertoo Xero-neuvojille, konsulteille ja IT-tiimeille, miten Xero yhdistetään SkyPlanner APS:ään. SkyPlannerin ja Xeron välinen integraatio toimii molempiin suuntiin Xero Accounting API- ja Projects API -rajapintojen kautta:
- SkyPlanneriin tuodaan yhteystiedot, varastoseurannassa olevat nimikkeet varastosaldoineen, hyväksytyt tarjoukset sekä ostotilaukset saapumispäivineen.
- Suunniteltu valmistumispäivä viedään takaisin kunkin tarjouksen historiaan muistiinpanona.
- Valmistuneet tilaukset viedään takaisin myyntilaskuluonnoksina, joissa ovat tarjouksen rivit ja viite. Samalla tarjouksen tilaksi vaihtuu Invoiced.
- Projektitöille kirjatut tunnit viedään takaisin Xero Projects -tuntikirjauksina.
- Xeron webhookit ilmoittavat yhteystietojen ja laskujen muutoksista, ja SkyPlannerin webhookit välittävät aikataulumuutokset heti niiden tapahtuessa.
Xero on kirjanpito-ohjelmisto, joten se ei sisällä osaluetteloita, reitityksiä, koneita eikä tuotantotilauksia. Työpisteitä, työvaiheita, työvuoroja ja asetusaikoja ylläpidetään SkyPlannerissa. SkyPlannerin tiimi määrittää integraation Xero-organisaatiotasi varten käyttöönoton aikana ja tukee sitä myös tuotantokäytössä. Tämä opas on tarkoitettu neuvojille ja kehittäjille, jotka haluavat osallistua toteutukseen tai rakentaa itse ratkaisuja SkyPlannerin dokumentoitua REST API -rajapintaa hyödyntäen (rajapintadokumentaatio).
Xero Accounting API
Xero on yksi moniasiakasympäristössä toimiva pilvituote, ja kaikilla organisaatioilla on käytössään sama rajapinta. Accounting API on REST API -rajapinta osoitteessa https://api.xero.com/api.xro/2.0/, ja se tukee JSON- ja XML-muotoja. Jokaisessa kutsussa organisaatio yksilöidään Xero-tenant-id-otsakkeella. (lähde)
Tuotannonsuunnittelussa tarvittavat päätepisteet:
- Perustiedot:
/Contacts(asiakkaat ja toimittajat),/Items(Code, IsTrackedAsInventory, QuantityOnHand). - Kysyntä:
/Quotes(Status ACCEPTED, LineItems) sekä ennen tuotantoa laskuttaville yrityksille/Invoices, jossa Type on ACCREC. - Hankinnat:
/PurchaseOrders(DeliveryDate, ExpectedArrivalDate sekä LineItems, joka sisältää ItemCode-kentän). - Tietojen vienti takaisin:
/Quotes/{QuoteID}/History,/Invoices,/Quotessekä Projects API osoitteessahttps://api.xero.com/projects.xro/2.0/projects/{projectId}/time.
Kaikki listauspäätepisteet hyväksyvät If-Modified-Since-otsakkeen, joten jokaisella synkronointikerralla luetaan vain muuttuneet tiedot. Tietueet luodaan ja päivitetään erissä. Osaluetteloille, reitityksille tai tuotantotilauksille ei ole päätepistettä.
Tunnistautuminen, käyttöoikeudet ja rajoitukset
Xero käyttää OAuth 2.0 -tunnistautumista. Xeron pääkäyttäjä kirjautuu kerran, hyväksyy sovelluksen ja valitsee organisaation. Sovellus pyytää offline_access-oikeutta, jotta yhteys voidaan ylläpitää päivitystunnuksilla. (lähde)
Xero korvaa laajat käyttöoikeudet tarkemmin rajatuilla oikeuksilla, ja uudet sovellukset saavat nämä tarkennetut oikeudet. Tuotannonsuunnittelun integraatio tarvitsee seuraavat oikeudet:
accounting.invoicestarjouksia, laskuja, ostotilauksia ja nimikkeitä vartenaccounting.contactsasiakkaita ja toimittajia vartenaccounting.settings.readnimikeasetuksia vartenprojectstuntikirjauksia vartenoffline_access
Xero rajoittaa kutsuja organisaatiokohtaisesti (samanaikaiset kutsut sekä kutsut minuutissa ja vuorokaudessa) ja sovelluskohtaisesti. Kun sovellus ylittää rajan, Xero palauttaa HTTP 429 -vastauksen ja Retry-After-otsakkeen. Vuorokausikohtainen kutsukiintiö ja yhdistettyjen organisaatioiden määrä riippuvat sovelluksen kumppanitasosta. Molemmat löytyvät Xeron rajapintarajoitusten sivulta. Webhookien, If-Modified-Since-lukujen ja erissä tehtävien kirjoitusten avulla tuotannonsuunnittelun integraatio pysyy selvästi rajojen sisällä.
SkyPlannerin REST API -rajapinnassa tunnistaudutaan API-tunnuksella, joka annetaan Authorization-Token-otsakkeessa (SkyPlanner Settings > API). Rajapinta on dokumentoitu Swagger/OpenAPI-muodossa. Integraatio-ohje opastaa ensimmäisten kutsujen tekemisessä.
Webhookit
“Webhooks allow you to subscribe to certain events that happen in Xero.” (Webhookien avulla voit tilata ilmoituksia tietyistä Xeron tapahtumista.) (lähde) Tuotannonsuunnittelun kannalta olennaiset tapahtumat ovat Contact ja Invoice, joista molemmilla on CREATE- ja UPDATE-tapahtumat.
Näin webhookit toimivat:
- Yksi sovelluskohtainen webhook kattaa kaikki yhdistetyt organisaatiot.
- Jokainen toimitettu viesti sisältää events-taulukon, jossa ovat resurssin tunniste ja tapahtumatyyppi. Vastaanottaja lukee resurssin tämän jälkeen.
- Jokainen viesti allekirjoitetaan
x-xero-signature-otsakkeella, joka muodostetaan sovelluksen webhook-avaimesta. Xero lähettää “Intent to receive” -tarkistuksen ennen viestien toimittamisen aloittamista. - Xero yrittää epäonnistuneita toimituksia uudelleen ja poistaa webhookin käytöstä, jos toimitukset epäonnistuvat jatkuvasti. Siksi vastaanottaja vastaa nopeasti ja tekee varsinaisen käsittelyn vasta sen jälkeen.
Tarjouksille, nimikkeille ja ostotilauksille ei ole webhook-tapahtumia. SkyPlanner lukee ne lyhyin kyselyvälein käyttäen If-Modified-Since-otsaketta. Jos mikään ei ole muuttunut, tähän kuluu yksi kutsu tietotyyppiä kohden.
Tietojen vastaavuudet
| Xeron objekti (päätepiste) | SkyPlannerin objekti | Suunta | Siirtotiheys |
|---|---|---|---|
Contact, IsCustomer (/Contacts) | Customer (external_identifier, delivery_priority) | Xero → SkyPlanner | Alkutuonti, sen jälkeen webhookin perusteella |
Item, varastoseurannassa tai ilman varastoseurantaa, sekä QuantityOnHand (/Items) | Tuotteet ja materiaalit, varastosaldot | Xero → SkyPlanner | Alkutuonti, sen jälkeen If-Modified-Since-otsakkeella |
Quote, jonka Status on ACCEPTED, sekä LineItems (/Quotes) | Order (external_order_number, delivery_date), rivikohtaiset työt | Xero → SkyPlanner | Säännölliset kyselyt If-Modified-Since-otsakkeella |
Invoice, jonka Type on ACCREC (ennen tuotantoa laskuttavat yritykset) (/Invoices) | Order ja työt | Xero → SkyPlanner | Reaaliaikaisesti webhookin kautta |
PurchaseOrder, joka sisältää ExpectedArrivalDate- tai DeliveryDate-kentän (/PurchaseOrders) | Saapuva materiaali (estimated_delivery_date) | Xero → SkyPlanner | Säännölliset kyselyt If-Modified-Since-otsakkeella |
Muistiinpano tarjouksen historiassa (PUT /Quotes/{QuoteID}/History) | Suunniteltu valmistumispäivä | SkyPlanner → Xero | Aikataulun muuttuessa |
Invoice, Type ACCREC, Status DRAFT, Reference = tarjouksen numero (POST /Invoices) | Valmistunut tilaus | SkyPlanner → Xero | Tilauksen valmistuessa |
Quote, jonka Status on INVOICED (POST /Quotes) | Valmistunut tilaus | SkyPlanner → Xero | Laskun luonnin yhteydessä |
Projects-tuntikirjaus (POST /projects/{projectId}/time) | Mobile Confirmations, tuntikirjaukset | SkyPlanner → Xero | Työtä kirjattaessa |
| Ei Xerossa | Työpisteet, työvaiheet, työvuorot, poissaolot, asetusaikamatriisi, työkalut, työntekijämäärät, vaihtoehtoiset työpisteet | Ylläpidetään SkyPlannerissa | Määritetään käyttöönoton aikana |
Integraation toteutustavat
1. Perustietojen alkutuonti. Lue sivutettuina yhteystiedot ja nimikkeet, sitten avoimet ostotilaukset ja hyväksytyt tarjoukset. Luo SkyPlanneriin asiakkaat käyttäen Xeron ContactID-tunnistetta external_identifier-arvona sekä tuotteet ja materiaalit käyttäen nimikekoodia avaimena. Luo sitten tiedot, joita Xerossa ei ole: työpisteet, tuotekohtaiset työvaiheet, työvuorot, vapaat ja asetusajat. Työvaiheet saa nopeimmin tuotua CSV- tai Excel-tiedostosta.
2. Tilausten synkronointi. Kysele tarjouksia säännöllisesti If-Modified-Since-otsakkeella. Kun tarjouksen tilaksi vaihtuu ACCEPTED, SkyPlanner luo tilauksen, jonka external_order_number-arvoksi tulee tarjouksen numero. delivery_date haetaan kentästä, johon yrityksesi tallentaa luvatun toimituspäivän. Kenttävastaavuus määritetään käyttöönotossa. Kustakin tarjousrivistä muodostetaan työt tuotteen työvaiheiden mukaan. Ostotilausriveistä muodostetaan saapuvat materiaalit niiden odotetuille saapumispäiville, joten työt odottavat toimitusta. Avoimet tarjoukset ja ostotilaukset luetaan öisin kokonaisuudessaan, jotta mahdolliset väliin jääneet muutokset saadaan mukaan.
3. Aikataulun ja valmistumistietojen vienti takaisin. Tulokset viedään Xeroon kolmella kutsulla:
- PUT
/Quotes/{QuoteID}/Historylisää muistiinpanon, jossa on suunniteltu valmistumispäivä. Hyväksytyssä tarjouksessa voi muuttaa vain yhteystietoa ja muistiinpanoja, joten päivämäärä tallennetaan historian muistiinpanoon. (lähde) - Kun tilaus valmistuu, POST
/Invoicesluo myyntilaskun, jonka Type on ACCREC ja Status DRAFT. Laskulle tulevat tarjouksen yhteystieto ja rivit sekä tarjouksen numero Reference-kenttään. Kirjanpitäjäsi hyväksyy ja lähettää laskun Xerossa. - POST
/Quotessulkee tarjouksen, kun kutsussa annetaan QuoteID ja Status INVOICED. Tilan muuttaminen Accepted-tilasta Invoiced-tilaan on sallittu Accounting API -rajapinnassa.
4. Tuotannon kuittaukset ja projektitunnit. Työntekijät kirjaavat työnsä SkyPlanner Mobile Confirmations-, Production Timer- tai Quick Log Mode -toiminnolla. Työn eteneminen päivittää aikataulun heti, ja Autopilot suunnittelee loput uudelleen. Projektitöissä SkyPlanner vie tunnit projektitehtävän tuntikirjauksiksi. Mukana ovat Xero-käyttäjä, päivämäärä ja kesto. (lähde)
5. Tietojen omistajuus ja ristiriitojen käsittely. Kirjaa säännöt ennen tuotantokäyttöön siirtymistä:
| Tiedot | Omistaja |
|---|---|
| Yhteystiedot, nimikkeet, hinnat, tarjoukset, ostotilaukset, laskut, kirjanpito | Xero |
| Työpisteet, työvaiheet, työvuorot, poissaolot, asetusaikamatriisi, työkalut, vaihtoehtoiset resurssit | SkyPlanner |
| Töiden järjestys, alkamis- ja päättymisajat, työkohtainen työpiste | SkyPlanner |
| Tarjouksen muistiinpano suunnitellusta valmistumisesta | SkyPlanner, tallennetaan Xeroon |
| Laskuluonnos valmistuneista tilauksista, projektien työtunnit | SkyPlanner luo, Xero hallinnoi hyväksynnän jälkeen |
Projektin tyypilliset vaiheet
Toteutus valmistuu yleensä muutamassa viikossa käyttöönoton aloituksesta. Sitä ennen voit käyttää 30 päivän maksutonta kokeilua omilla tiedoillasi: yhteystiedot, tuotteet ja avoimet tarjoukset tuodaan Xerosta CSV-tiedostona.
Varsinaiseen projektiin kuuluvat seuraavat vaiheet:
- Yhteyden muodostaminen. Xeron pääkäyttäjä hyväksyy SkyPlannerin ja valitsee organisaation.
- Tuotannon käynnistävä tietue. Sovitaan, käynnistyykö tuotanto hyväksytyistä tarjouksista vai myyntilaskuista.
- Tietojen vastaavuudet. Vahvistetaan vastaavuustaulukko, nimikekoodit, laskujen kirjanpitotilit, verotuksen oletusarvot ja tietojen omistajuussäännöt.
- Ensimmäinen tiedonsiirto. Yhteystiedot, nimikkeet, avoimet ostotilaukset ja hyväksytyt tarjoukset.
- Tuotannon mallinnus. Työpisteet, tuotekohtaiset työvaiheet, työvuorot, asetusaikamatriisi, työkalut ja työntekijämäärät SkyPlannerissa.
- Synkronointi. Yhteystiedot ja laskut päivittyvät webhook-ilmoituksilla. Tarjousten, nimikkeiden ja ostotilausten muutokset haetaan säännöllisesti
If-Modified-Since-kyselyillä, ja tiedot täsmäytetään öisin. - Tietojen kirjoittaminen takaisin. Ensin tarjousten muistiinpanot, sitten laskuluonnokset ja tarjousten tilat, lopuksi projektien työtunnit, jos niitä käytetään.
- Rinnakkaistestaus ja tuotantokäyttöön siirtyminen. Vertaa SkyPlannerin päivämääriä nykyiseen suunnitelmaasi ja pyydä kirjanpitäjää tarkistamaan ensimmäiset laskuluonnokset. Ota sen jälkeen tietojen kirjoittaminen takaisin käyttöön.
Mitä Xero-integraatiossa on huomioitava
- Xerossa ei ole tuotannon tietokohteita. Ylläpidä tuotekohtaisia työvaiheita SkyPlannerissa ja yhdistä ne Xeron nimikekoodeihin. Pidä nimikekoodit muuttumattomina.
- Tarjouksille ei ole webhook-ilmoituksia. Hae niiden muutokset tihein välein
If-Modified-Since-kyselyillä. Noudata minuutti- ja vuorokausikohtaisia rajoja. - Hyväksytyt tarjoukset lukitaan. Hyväksynnän jälkeen vain yhteystietoja ja muistiinpanoja voi muuttaa. Siksi luvattu päivämäärä luetaan kerran hyväksynnän yhteydessä ja suunniteltu päivämäärä kirjataan historiatietoihin muistiinpanona.
- Varastosaldot muuttuvat myynti- ja ostolaskujen perusteella. Xero päivittää varastoseurannassa olevien nimikkeiden saldoja myyntilaskujen, ostolaskujen ja hyvityslaskujen kautta. Sovi kirjanpitäjäsi kanssa, miten valmiit tuotteet ja käytetyt materiaalit kirjataan.
- Projektien tuntikirjaukset vaativat Xero-käyttäjän. Tuntikirjaukset kuuluvat aina jollekin Xero-käyttäjälle. Päätä, keiden työntekijöiden tunnit siirretään Xero Projects -palveluun, ja säilytä muiden tuntikirjaukset SkyPlannerissa.
- Rajatut käyttöoikeudet. Pyydä tarkasti rajatut käyttöoikeudet alusta alkaen, sillä laajat käyttöoikeudet ovat poistumassa käytöstä.
- Sovelluksen kumppanitaso. Kumppanitaso määrittää, kuinka moneen organisaatioon sovellus voi muodostaa yhteyden ja kuinka monta API-kutsua se saa tehdä vuorokaudessa. Valitse taso tuotantolaitosten määrän mukaan.
Kuka määrittää Xero-integraation ja vastaa tuesta
Työssä määritetään nimikkeet, tarjoukset, ostotilaukset ja se, miten valmistuneet työt siirtyvät laskutukseen. Lisäksi määritetään tiedot, joita Xerossa ei ole: työpisteet, työvaiheet, työvuorot, asetusaikamatriisi, työkalut, työntekijämäärät ja vaihtoehtoiset resurssit.
- SkyPlanner-tiimi määrittää integraation käyttöönoton aikana ja tukee sitä tuotantokäyttöön siirtymisen jälkeen. Jokainen konepaja käsittelee nimikkeitä, tarjouksia ja varastoa Xerossa omalla tavallaan. Tämä käytännön tuntemus otetaan huomioon integraation määrityksissä.
- Xero-neuvonantajasi tai integraatiokumppanisi voi rakentaa integraation. SkyPlanner tarjoaa REST API -rajapinnan, Swagger/OpenAPI-dokumentaation ja webhook-ilmoitukset.
- Omat kehittäjäsi voivat rakentaa integraation API-tunnisteen avulla. Alkuun pääsee pelkällä API-tunnisteella, ja SkyPlanner-tiimi auttaa tarvittaessa. Tuotedokumentaatio, mukaan lukien ostotilaukset sekä tuotteiden ja materiaalien API, löytyy SkyPlannerin dokumentaatiosta.
SkyPlannerin hinta on alkaen 199 € kuukaudessa. Hintaan sisältyy 5 työpistettä, ja laskutus on kuukausittainen. Saat prosessiisi ja tarpeisiisi perustuvan tarjouksen integraatiosta sekä palvelupakettisi hinnan etukäteen, joten tiedät kokonaiskustannukset ennen aloittamista. Tutustu hinnastoon ja ominaisuuksiin sekä siihen, mihin Xero yksin riittää, artikkelissa Onko Xerossa tuotannonsuunnittelua? Yleiskuvan löydät Xero-sivulta ja muut järjestelmät kaikkien integraatioiden sivulta.
Valmistavan teollisuuden kokemuksia SkyPlannerista
2 hsäästöä joka viikko
”SkyPlanner on vienyt tuotannonsuunnittelumme Excel-taulukoista reaaliaikaiseen tuotannon optimointiin.”
Kalle Kalliomäki, toimitusketjuasiantuntija
UTU · Sähkökeskukset ja kytkinlaitteet
Tuotannonsuunnittelussa säästyy 2 tuntia työaikaa joka viikko, ja uusi työjono välittyy tuotantolinjalle sekunneissa.
+90 %tuotannon tehokkuuteen
”Tuotannon tehokkuus on kasvanut 90 %.”
Abdul Rucyinga, IT-johtaja
Laboratory & Allied · Lääkevalmistus
Tuotannon tehokkuus on kasvanut 90 %, ja kaikkien työpisteiden optimoitu suunnitelma kolmeksi kuukaudeksi syntyy alle 30 minuutissa.
Vähemmänmateriaalipuutteista johtuvia seisokkeja
”SkyPlannerin arvo meille on siinä, että se on arjessa toimiva työkalu erityisesti toimituspäivien määrittämiseen.”
Tommi Männistö, tuotannonsuunnittelupäällikkö
Eskomatic · Sopimuskoneistus
Automaattinen kuormitussuunnittelu tarkentaa toimituspäiviä, ja materiaalipuutteista johtuvat tuotantoseisokit ovat vähentyneet merkittävästi.
1 000:iatyömääräimiä suunnitellaan automaattisesti
”Tuotanto on aivan eri tavalla hallinnassa, ja ymmärryksemme kapasiteetista on täysin uudella tasolla.”
Hannu Ryynänen, toimitusjohtaja
Mamec · Teollisuussekoittimet, pumput ja korkean teknologian sopimusvalmistus
Tuhansien työmääräinten suunnittelu hoituu automaattisesti, ja koko organisaatiolla on reaaliaikainen näkymä tuotantoon.
Usein kysytyt kysymykset
Onko Xerossa API tuotantotiedoille?
Xerossa on Accounting API ja Projects API. Molemmat ovat REST-rajapintoja, jotka käyttävät OAuth 2.0 -valtuutusta. Ne kattavat yhteystiedot, nimikkeet, tarjoukset, laskut, ostotilaukset ja tuntikirjaukset. Tuotantotiedot, kuten työpisteet ja työvaiheet, ovat SkyPlannerissa.
Voiko SkyPlanner kirjoittaa tietoja takaisin Xeroon?
Kyllä. SkyPlanner lisää suunnitellun valmistumispäivän kunkin tarjouksen historiatietoihin. Kun tilaus valmistuu, se luo tarjouksen riveistä myyntilaskuluonnoksen, vaihtaa tarjouksen tilaksi Invoiced ja siirtää projektien tuntikirjaukset Xeroon.
Lähettääkö Xero muutokset reaaliaikaisesti?
Xeron webhook-ilmoitukset kattavat yhteystiedot ja laskut. SkyPlanner hakee edellisen synkronoinnin jälkeen muuttuneet tarjoukset, nimikkeet ja ostotilaukset käyttämällä If-Modified-Since-otsaketta ja täsmäyttää tiedot öisin. Näin uusi hyväksytty tarjous saadaan nopeasti mukaan tuotantosuunnitelmaan.
Mistä osaluettelot, reititykset ja koneet tulevat, jos niitä ei ole Xerossa?
SkyPlannerista. Määrität työpisteet, tuotekohtaiset työvaiheet, työvuorot ja asetusajat kerran joko käsin tai tuomalla ne CSV- tai Excel-tiedostosta. Jokainen tuote yhdistetään Xeron nimikekoodiin, joten uudet hyväksytyt tarjoukset tulevat automaattisesti mukaan tuotantosuunnitelmaan.
Voimmeko kokeilla SkyPlanneria ennen integraation rakentamista?
Kyllä. Maksuttomassa 30 päivän kokeilussa voit käyttää enintään 20 työpistettä ja tuoda tiedot Xerosta CSV-tiedostona. Luottokorttia ei tarvita. Aloita kokeilu tai ota yhteyttä myyntiin, niin määritetään integraation laajuus.
