Visma Fivaldi myyntilaskurajapinta

Rajapinnan käyttöönotto

Tarkista että nämä käyttöoikeudet on päällä Easoftissa (Fivaldin päässä tehtävät kirjanpitäjän toimenpiteet tulevat hieman alempana):

• InterfaceSettings/importFivaldiRestCustomerRegister
• InterfaceSettings/fetchFivaldiRestData

Valmistelut Easoftissa

• Rajapinnassa on kiinteä tunnus ja salasana, jotka löytyvät Dashlanesta.
• Alv-statukset tulee määritellä kaikille eri alv-%, joilla tuotteita myydään
  • Alv-statukselle tulee määritellä myyntitili
  • HUOM! Kun luodaan tilaus / lasku
    • Aina tulee valita Alv-käsittely
    • Kaikilla riveillä tulee olla sama myyntitili
      • Myyntitiliä ei saa vaihtaa käsin
• Rajapinta-asetuksissa tehdään mäppäykset
  • Kustannuspaikat ja yksiköt eivät ole pakollisia
• Tuoterekisterissa tuotekoodien tulee olla vähintään kahden merkin pituisia

Rajapinnan käyttöönotto Fivaldissa (kirjanpitäjän toimenpiteet)

Ensimmäisenä kannattaa Fivaldissa käydä valitsemassa/tarkistamassa Easoftin kumppanikäyttäjän käyttöoikeudet. Kumppanikäyttäjien luettelo löytyy Fivaldissa valikosta Muut --> Palvelunhallinta. Selaa listalta oikea kumppanikäyttäjä ja valitse se (esim Easoft ERP, voit varmistaa Easoftista sinuun yhteydessä olleelta henkilöltä mikä Easoftin kumppanikäyttäjä tulee valita).

Tarkista että nämä käyttöoikeudet on päällä valitulle kumppanikäyttäjälle Fivaldissa:

Muut valmistelut Fivaldissa

• Tuoterekisterissä jokaisen tuotteen tiliöinnit tulee olla samalla tavalla, kuin Easoftissa alv-statukset. Useimmiten kaikilla tuotteilla tulee olla Fivaldissa valittuna kaikki asiakkaan käytössä olevat tiliöintiryhmät, jotta samoilla tuotteilla voidaan tehdä myyntiä esim sekä kotimaan myyntinä että rakennuspalveluiden käänteisellä alvilla.
  • Tiliöintiryhmä vastaa Easoftin alv-statusta (jos Fivaldi on ollut käytössä jo ennen Easoftin käyttöönottoa, yleensä nämä ovat jo valmiina olemassa, eikä toimenpiteitä vaadita Fivaldin päässä). Easoftin päässä kytketään Fivaldin tiliöintiryhmät vastaamaan Easoftin alv-statuksia.
  • Tiliöinti vastaa Easoftin myyntitiliä (myös tässä kohtaa, jos Fivaldi on jo ollut käytössä ennen Easoftia, ovat myyntitilit jo valmiina ja riittää, että Easoftin päässä korjataan myyntitilien numerot vastaamaan Fivaldin myyntitilien numeroita. Tämän tekee Easoft.)
• Luo Fivaldin tuoterekisteriin tuote koodilla “--”. Tuotteelle vaaditaan myös nimi ja se voi myös olla “--”.
  • Tähän tuotteeseen linkittyvät sellaiset rivit, joilla ei ole Easoftissa tuotekoodia (esim maksuerät). Tuotteen nimi korvataan Fivaldiin muodostuvalle tilaukselle Easoftista tulevalla laskurivin nimellä automaattisesti.

Muuta, mitä rajapinnan toiminnasta on hyvä ymmärtää

• Easoftissa konfigurointi tehdään siis alv-statuksien kautta, Fivaldissa erikseen jokaiselle tuotteelle
  • Jos Easoftissa olevaa tuotetta ei löydy Fivaldista, se luodaan automaattisesti oikeilla tiliöintitiedoilla Fivaldiin
  • Edellyttää, että rajapinta-asetuksissa alv-statukset ja myyntitilit on mäpätty oikein (tehdään Easoftin päässä)
  • Jos Easoftissa oleva tuote löytyy Fivaldista, oletetaan, että Fivaldissa tuotteen tiliöinti on konffattu samalla tavalla, kuin Easoftin alv-statukset
    • Jos tiliöinnit on virheelliset, laskun siirto ei onnistu TAI laskurivin alv-% voi mennä väärin

Asiakasrekisterin tuonti (ei välttämätöntä kaikissa tapauksissa)

• Tuonnissa Fivaldin asiakasrekisterin perusteella luodaan asiakkaat Easoftiin. Jos asiakas löytyy jo Easoftista (nimi ja osoite on sama), linkitetään asiakkaat toisiinsa, jotta laskun lähetyksen yhteydessä Fivaldiin ei luoda duplikaatti asiakasta.
• Fivaldista ladataan asiakkaat

  • “Muut” → “XML-aineiston muodostus” → “Yritysrekisteri”. Tämä tiedosto toimitetaan Easoftille.

  • Easoftin rajapinta-asetuksissa klikataan “Tuo asiakasrekisteri” → valitaan Fivaldista ladattu xml-tiedosto

 

Rajapinnan toiminta:

Lasku (myyntitilaus Fivaldissa)

• Kun Easoftista siirretään lasku, siitä muodostetaan myyntitilaus Fivaldiin
  • Käyttäjän pitää käydä käsin siirtämässä tilaus laskutukseen Fivaldissa
  • Liitteitä ei voida siirtää rajapinnan kautta
  • Laskurivin nimikkeen maksimipituus on 80 merkkiä
• Fivaldin asiakkaan laskun välitykseen liittyvät kentät päivitetään aina laskun siirron yhteydessä
  • email2 => Sähköpostiosoite laskulla
  • finvoiceOtherIdentifier => Verkkolaskutusosoite laskulla
  • intermediatorCode => Välittäjän tunnus laskulla
  • transmissionTypeId => Laskun lähetystapa
• Easoftin laskun rivin alv-% ei suoraan siirry fivaldiin. Alv-% tulee laskulle valitun alv-käsittelyn ja myyntitilin perusteella.

Laskulla siirtyvät kentät ja lähtevä data. Tiedot luetaan laskulta
{
"buyer": {
"buyerOrganisationName": Invoice.customer_name, // Laskutussiakkaan nimi
"buyerOrganisationName2": Invoice.customer_name2, // Laskutusasiakkaan nim2
"countryCode": Customer.country, // Laskutusasiakkaan maa (asiakasrekisteristä)
"postCodeIdentifier": Invoice.customer_postcode, // Laskutusasiakkaan postinumero
"streetName": Invoice.customer_address, // Laskutusasiakkaan osoite
"townName": Invoice.customer_locality, // Laskutusasiakkaan postitoimipaikka
},
"recipient": { // Jos laskulla on toimitusosoite
"countryCode": Customer.country, // Asiakkaan maa (asiakasrekisteristä)
"postCodeIdentifier": Invoice.delivery_postcode, // Toimitusosoitteen postinumero
"recipientOrganisationName": Invoice.delivery_name, // Toimitusosoitteen nimi
"recipientOrganisationName2": Invoice.delivery_name2, // Toimitusosoitteen nimi2
"streetName": Invoice.delivery_address, // Toimitusosoite
"townName": Invoice.delivery_locality // Toimitusosoitteen postitoimipaikka
},
"languageCode": Customer.lang, // Asiakkaan kieli (asiakasrekisteristä)
"buyerReferenceIdentifier": Invoice.your_ref, // Viitteenne
"invoiceReference": Invoice.our_ref, // Viitteemme
"orderIdentifier": Invoice.customer_order_number, // Asiakkaan tilausnumero
"externalOrderNumber": Order.number, // Tilausnumero
"deliveryDate": Invoice.delivery_date, // Toimituspäivä
"orderDate": Order.approval_date, // Tilauksen päiväys
"paymentTermId": Invoice.payment_term_id, // Maksuehto, rajapinta-asetusten mukaan
"postingGroupId": Invoice.vat_status_id, // Alv-käsittely, rajapinta-asetusten mukaan
"salesOrderRowDTOS": [ // Laskun rivit
{ // Tuoterivi
"productCode": InvoiceRow.item, // Koodi. Jos Easoftissa ei ole koodia, tulee koodiksi "--"
"description": InvoiceRow.description, // Nimike
"quantity": InvoiceRow.qty, // Määrä
"rowFreeText": InvoiceRow.freetext, // Rivin lisätiedot
"textRow": false, // Aina false
"totalSumIncludingTax": Verollinen loppusumma, // Lasketaan rivin loppusumma
"unitId": InvoiceRow.unit // Yksikkö, rajapinta-asetusten mukaan
"accountDimension1": Invoice.service_code_id // Laskun kustannuspaikka, rajapinta-asetusten mukaan
},
{ // Tekstirivi
"textRow": true, // Aina true
"rowFreeText": InvoiceRow.description // Nimike
}
],
"customerId": ExternalId.external_id, // Fivaldin asiakkaan id. Tallennettu external_ids tauluun
"readyToInvoice": true, // Aina true
"currency": "EUR", // Aina EUR
"currencyRate": 1, // Aina 1
}

Tuoterekisteri

• Laskun siirron yhteydessä Fivaldiin luodaan sellaiset tuotteet, joita sieltä ei ennestään löydy
  • Tuotteita etsitään tuotekoodin perusteella
    {
    "productCode": InvoiceRow.item TAI Product.item // Riippuu, onko rivillä tuoterekisterin tuote
    "description": InvoiceRow.description TAI Product.description // Riippuu, onko rivillä tuoterekisterin tuote
    "salesPrice": Laskuruviltä tai tuoterekisteristä laskettu hinta // Riippuu, onko rivillä tuoterekisterin tuote
    "productEntityPostingDTOList": [ // Easoftiin määriteltyjen alv-statuksien mukaisesti
    "postingGroupId": Rajapinta-asetusten Alv-statukset mäppäyksen mukaan
    "postingCodeId": Rajapinta-asetusten Myyntitilit mäppäyksen mukaan
    ]
    }

Asiakasrekisteri

Asiakkaalle siirtyvät kentät ja lähtevä data
{
"businessId": Customer.businessid // Asiakkaan taakse tallennettu y-tunnus
"customerName": Invoice.customer_name // Asiakkaan nimi laskulla
"customerName2": Invoice.customer_name2 // Asiakkaan nimi2 laskulla
"email": Customer.email // Asiakkaan taakse tallennettu email
"email2": Invoice.customer_email // Asiakkaan sähköposti laskulla
"phoneNumber": Invoice.customer_phone // Asiakkaan puhelinnumero laskulla
"phoneNumber2": Customer.phone2 // Asiakkaan taakse tallennettu phone2
"currency": "EUR" // Aina EUR
"finvoiceOtherIdentifier": Invoice.einvoiceid // Verkkolaskuosoite laskulla
"intermediatorCode": Invoice.evoiceint // Välittäjän tunnus laskulla
"isCustomer": true // Aina true
"additionalInformation": Customer.notes // Asiakkaan taakse tallennettu muistiinpanot
"isConsumer": Customer.customer_type // Kuluttaja-asiakas. Jos valittuna "Yksityishenkilö"
"debtCollectionDisabled": Customer.sensible // Perintäkielto fivaldissa. Asetetaan päälle, jos Easoftissa maksumuistutus pois päältä
"transmissionTypeId": Invoice.sendtype // Laskun lähetystapa. Laskun lähetystavan ja rajapinta-asetusten mukaan
"customerEntityAddressDTOS": [
{
"addressType": '01' // Tyyppi "postiosoite"
"streetAddress": Customer.address // Asiakkaan osoite
"postalCode": Customer.postcode // Asiakkaan postinumero
"postalAddress": Customer.locality // Asiakkaan postitoimipaikka
"countryCode": Customer.country // Asiakkaan maa
"isMainAddress": true // Aina true
},
{ // Jos asiakaskortille on tallennettu laskutusosoite
"addressType": '03' // Tyyppi "laskutusosoite"
"streetAddress": Customer.invoicingAddress // Asiakkaan laskutusosoite
"postalCode": Customer.invoicingPostcode // Asiakkaan laskutuspostikoodi
"postalAddress": Customer.invoicingLocality // Asiakkaan laskutuspostitoimipaikka
}
]
}

Mahdolliset virheviestit:

"Tilauksen luonti Fivaldiin: Bad request, request parameter or body in invalid format"

Jokin laskulla oleva tieto voi olla väärin muotoiltu tai liian pitkä. Usein ongelma on esimerkiksi liian pitkä teksti laskurivin nimikkeessä