Takaisin

Web service myyntilaskurajapinnan tekninen kuvaus

Muutosloki:

5.1.2023

·        Päivitetty muutokset factoring vaihtoehtoihin.

10.9.2021

·        Tiliöintiehdotus (PROPOSED_PURCHASE_ACCOUNT) -elementin lisäys rajapintaan ja kuvaukseen.

17.8.2021

·        Vakioviesti (DEFAULT_MESSAGE) -elementin poistaminen kuvauksista. Kentässä tuotava teksti ei välity Talenomin järjestelmään.

15.1.2021

·        Asiakkaan nimen (PAYER / NAME) merkkimäärärajoituksen kasvattaminen 45 merkkiin.

·        Tuotenumeron (PRODUCT_NUMBER) merkkimäärärajoituksen kasvattaminen 30 merkkiin.

·        Requestin maksimikoon kasvattaminen 4 mt -> 8 mt.

16.9.2020

·        Laskutus eri valuutoissa (ORIGINAL_CURRENCY, CUSTOM_EXCHANGE_RATE_TO_EUR)

13.6.2019

·        Sähköpostilaskun lähetystapa (EMAIL_SEND_METHOD)

·        0 = linkkinä (oletus), 1 = liitteenä

2.5.2019

·        Kasvatettu myyntitilin ja saatavatilin maksimimerkkimäärä 6:een merkkiin.

7.2.2019

·        Lisätty asiakastyypin (CUSTOMER_TYPE) välittyminen.

·        0 = yritysasiakas, 1 = yksityisasiakas.

5.12.2018

·        Alennusprosentille (DISCOUNT_PERCENTAGE) tarkistus (alennusprosentti ei saa olla miinusmerkkinen)

3.9.2018

·        Lisätty lähetystapoihin sähköpostilaskutus (SHIPMODE, USE_EMAILBILLING, EMAILBILLING_ADDRESS)

9.4.2018

·        Lisätty uudet factoring vaihtoehdot: Ropo, Lähirahoitus, Aktia ja AREX

·        Lisätty laskuriville paikka Tullin vientikoodille (CN_CODE)

·        Dokumentin kosmeettisia muutoksia

·        Lisätty paikka muutoslokille

1. YLEISTÄ

Web service tekniikan avulla integroidaan asiakkaan ja Talenomin tietojärjestelmät keskustelemaan sähköisesti. Palvelun avulla asiakas voi käyttää omaa järjestelmäänsä ja vähentää näin ollen Talenom Online -palvelussa tehtävää työtä. Talenom Tietoväylä on tuotenimi, jolla palvelua myydään asiakkaalle.

2. MYYNTILASKUTUS

• Palvelun avulla integroidaan asiakkaan ja Talenomin järjestelmät myyntilaskutuksen osalta kuvan 1 mukaisesti. Asiakas laatii myyntilaskut omassa tietojärjestelmässään, mutta laskujen lähetys ja/tai saatavien seuranta hoidetaan Talenom Online -palvelussa Myyntilaskutus -osiossa, ks. kuva 2.

• Asiakkaan ja Talenomin järjestelmien välille rakennetaan integraatio (Talenom Tietoväylä), jolla laskutiedot siirretään.

• Asiakas voi myös laatia laskuja manuaalisesti Talenom Online -palvelun Myyntilaskutus -osiossa, vaikka integraatio olisikin käytössä.

• Laskut voidaan lähettää loppuasiakkaille Talenomin Myyntilaskutuspalvelulla Myyntilaskutuksen palvelukuvauksen mukaisessa aikataulussa.

• Saatavien seuranta suoritetaan Talenomin Myyntilaskutuspalvelussa Myyntilaskutuksen palvelukuvauksen mukaisesti.

• Asiakas voi toimittaa laskuja integraation kautta milloin tahansa.

3. PALVELUN SIJAINTI JA SOAP-KUTSUT

Myyntilaskun web service löytyy osoitteesta:

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx

SOAP-kutsun rajapintakuvaukset löytyvät osoitteista (tuetaan SOAP 1.1 ja SOAP 1.2 versioita):

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx?op=NewCustomer

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx?op=NewInvoice

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx?op=NewInvoiceFile

4. METODIT

InvoiceService sisältää seuraavat web metodit:

NewInvoice

NewInvoiceFile

NewCustomer

NewInvoice

Lisätään uusi lasku. Laskun tiedot annetaan XML-tiedostossa.

<userName>string</userName> 
<userPw>string</userPw> 
<xmlInvoice>xml</xmlInvoice>

userName: Talenom-järjestelmän käyttäjätunnus

userPW: Talenom-järjestelmän salasana kryptattuna MD5-algoritmilla

xmlInvoice: Laskun tiedot XML-tiedostona

NewInvoice request -sanoman maksimikoko on 8 megatavua.

NewInvoiceFile

Lisätään uusi lasku sekä laskun liitetiedosto (PDF).

<userName>string</userName> 
<userPw>string</userPw> 
<byteData>base64Binary</byteData>

Laskun tiedot annetaan XML-tiedostossa, jonka nimi on NewInvoice.xml. XML-tiedosto ja PDF liitetiedosto pakataan zip-tiedostoksi siten että PDF-tiedosto on alikansiossa Attachments. PDF-tiedoston nimi voi olla mikä tahansa, ja nimi kerrotaan XML-tiedostossa elementissä PDF_FILE_NAME.

Zip-tiedoston rakenne:

NewInvoice.xml

Attachments

Attachment.pdf

Pakattu zip-tiedosto lähetetään NewInvoiceFile-metodille byte-taulukkona.

PDF-tiedoston vaatimukset:

- Sivumäärää ei ole rajoitettu, mutta yhden sivun keskimääräinen koko ei saisi olla yli 2000 kilotavua. PDF liitetiedoston koko ei saa olla yli 5 megatavua. Huomiona: NewInvoiceFile -requestin maksimikoko on 8 megatavua.

NewCustomer

Lisätään uusi loppuasiakas / asiakkaat. Asiakkaan tiedot annetaan XML-tiedostossa.

<userName>string</userName> 
<userPw>string</userPw> 
<xmlCustomer>xml</xmlCustomer>

userName: Talenom-järjestelmän käyttäjätunnus

userPW: Talenom-järjestelmän salasana kryptattuna MD5-algoritmilla

xmlCustomer: Loppuasiakkaiden tiedot XML-tiedostona

5. XML TIEDOSTORAKENTEET

NewInvoice XML-tiedoston rakenne

Alla olevassa taulukossa on kirjoitettu auki XML-skeeman kuvaus (UusiLasku.xsd) .Sama XML-kuvaus on käytössä sekä NewInvoice- että NewInvoiceFile –metodeissa.

HUOM: elementtien pitää olla alla mainitussa järjestyksessä.

NewInvoice- ja NewInvoiceFile -metodin paluuarvo

Paluuarvona metodi palauttaa XML-muodossa valmiin laskun tiedot sekä lisää INVOICE-elementtiin status-attribuutin, joka kertoo onnistuiko laskun tallennus. Jos tallennus onnistui, XML sisältää kohdassa ’XML-tiedoston rakenne’ mainittujen elementtien lisäksi alla mainitut elementit.

HUOM: paluuarvon tyyppi on string, mutta sisältö on XML-muotoinen, eli sen voi konvertoida XML-tiedostoksi.

Vastauksessa INVOICE-elementillä on attribuutit Status ja ReturnMessage, jotka antavat tietoa tallennuksen onnistumisesta. Status –attribuutti voi saada seuraavat arvot:

ReturnMessage-attribuutissa on tarkempi kuvaus mahdollisesta virheestä. Virheilmoitukset ovat alla luetellun tyyppisiä. Kaikki virheilmoitukset, jotka alkavat sanoilla ”XML validation error” ovat XML-validaattorin tuottamia ja johtuvat siitä että lähetetty XML ei vastaa XML skeeman kuvausta, (jokin pakollinen elementti puuttuu / jonkin elementin arvo on väärän tyyppinen / elementit ovat väärässä järjestyksessä). XML skeeman kuvaus löytyy kohdasta ’XML-tiedoston rakenne’.

NewCustomer XML-tiedoston rakenne

Alla olevassa taulukossa on kirjoitettu auki XML-skeeman kuvaus (UusiAsiakas.xsd) .

HUOM: elementtien pitää olla alla mainitussa järjestyksessä.

NewCustomer -metodin paluuarvo

Paluuarvona metodi palauttaa XML-muodossa valmiin laskun tiedot sekä lisää CUSTOMER-elementtiin status-attribuutin, joka kertoo onnistuiko laskun tallennus. Jos tallennus onnistui, XML sisältää kohdassa ’XML-tiedoston rakenne’ mainittujen elementtien lisäksi alla mainitut elementit.

HUOM: paluuarvon tyyppi on string, mutta sisältö on XML-muotoinen, eli sen voi konvertoida XML-tiedostoksi.

Vastauksessa CUSTOMER-elementillä on attribuutit Status ja ReturnMessage, jotka antavat tietoa tallennuksen onnistumisesta. Status –attribuutti voi saada seuraavat arvot:

ReturnMessage-attribuutissa on tarkempi kuvaus mahdollisesta virheestä. Virheilmoitukset ovat alla luetellun tyyppisiä. Kaikki virheilmoitukset, jotka alkavat sanoilla ”XML validation error” ovat XML-validaattorin tuottamia ja johtuvat siitä että lähetetty XML ei vastaa XML skeeman kuvausta, (jokin pakollinen elementti puuttuu / jonkin elementin arvo on väärän tyyppinen / elementit ovat väärässä järjestyksessä). XML skeeman kuvaus löytyy kohdasta ’XML-tiedoston rakenne’.

Alla esimerkki NewInvoice metodin vastauksesta, kun laskun tallennus on onnistunut.

<?xml version="1.0" encoding="utf-8" ?>
- <INVOICE xmlns="" Status="OK" ReturnMessage="Success: Invoice added">
<INVOICE_NR>1009</INVOICE_NR>
<REFERENCE_NR>12310092</REFERENCE_NR>
<AMOUNT_TOTAL_VAT_INCLUDED>166.8836</AMOUNT_TOTAL_VAT_INCLUDED>
<AMOUNT_TOTAL_VAT_EXCLUDED>135.6777</AMOUNT_TOTAL_VAT_EXCLUDED>
<AMOUNT_VAT>31.2059</AMOUNT_VAT>
<INVOICE_ACCEPTED>12/10/2010 10:47:00 AM</INVOICE_ACCEPTED>
<CLIENT_ID>22</CLIENT_ID>
<INVOICE_DATE>2018-12-09</INVOICE_DATE>
<DUE_DATE>2018-12-23</DUE_DATE>
<DELIVERY_DATE>2018-12-30</DELIVERY_DATE>
<OUR_REFERENCE>viitteemme</OUR_REFERENCE>
<YOUR_REFERENCE>viitteenne</YOUR_REFERENCE>
<DNET>14</DNET>
<CASHDISDDATE>2018-12-16</CASHDISDDATE>
<CASHDISDATEPERC>2.50</CASHDISDATEPERC>
<OVERDUEINTEREST>8.50</OVERDUEINTEREST>
<REMARKTIME>8</REMARKTIME>
<INVOICE_MESSAGE>Laskukohtainen viesti</INVOICE_MESSAGE>
<CLIENT_MESSAGE>Asiakaskohtainen viesti</CLIENT_MESSAGE>
<SHIPMODE>1</SHIPMODE>
<COMMENT />
- <PAYER>
<NUMBER>123</NUMBER>
<NAME>Ripan Ruuvi Oy</NAME>
<NAME_EXT />
- <DELIVERY_ADDRESS>
<STREET_ADDRESS>Saturnuksentie 45</STREET_ADDRESS>
<POSTAL_CODE>01480</POSTAL_CODE>
<POST_OFFICE>Helsinki</POST_OFFICE>
<COUNTRY>FI</COUNTRY>
<DELIVERY_LOCATION>Toimituspaikka</DELIVERY_LOCATION>
</DELIVERY_ADDRESS>
- <INVOICE_ADDRESS>
<STREET_ADDRESS>PL 125</STREET_ADDRESS>
<POSTAL_CODE>01481</POSTAL_CODE>
<POST_OFFICE>Espoo</POST_OFFICE>
<COUNTRY>FI</COUNTRY>
<USE_EMAILBILLING></USE_EMAILBILLING>
<EMAILBILLING_ADDRESS></EMAILBILLING_ADDRESS>
</INVOICE_ADDRESS>
<VAT_ID>FI1122336</VAT_ID>
<BUSINESS_ID>112233-6</BUSINESS_ID>
<PHONE>09-123666</PHONE>
<MOBILE />
<TELEFAX />
<EMAIL />
<EINVOICEID />
<INTERMEDIATOR />
<INVOICE_LANGUAGE>fi-FI</INVOICE_LANGUAGE>
<CUSTOMER_MESSAGE>Asiakasviesti</CUSTOMER_MESSAGE>
<DNET>14</DNET>
<CASH_DIS_DAYS>7</CASH_DIS_DAYS>
<CASH_DIS_DATE_PERC>2.50</CASH_DIS_DATE_PERC>
</PAYER>
- <ROWS>
- <ROW>
<PRODUCT_NUMBER>10</PRODUCT_NUMBER>
<PRODUCT_NAME>Ruuvi</PRODUCT_NAME>
<PRODUCT_INFO>Selite</PRODUCT_INFO>
<QUANTITY>1</QUANTITY>
<PRICEPERUNIT>100.1255</PRICEPERUNIT>
<DISCOUNT_PERCENTAGE>10.00</DISCOUNT_PERCENTAGE>
<VAT_RATE>24.00</VAT_RATE>
<ROW_TYPE>0</ROW_TYPE>
<SALES_ACCOUNT_NUMBER>123456</SALES_ACCOUNT_NUMBER>
<PROPOSED_PURCHASE_ACCOUNT>4000</PROPOSED_PURCHASE_ACCOUNT>
<COST_CENTER_CODE>1234</COST_CENTER_CODE>
<COST_CENTER_INFO>Kustannuspaikka1</COST_CENTER_INFO>
<COST_TYPE_CODE>345</COST_TYPE_CODE>
<COST_TYPE_INFO>Kustannustyyppi 1</COST_TYPE_INFO>
<PROJECT_CODE />
<PROJECT_INFO />
<PROJECT_TYPE_CODE />
<PROJECT_TYPE_INFO />
<TOTAL_SUM_TAX_INCLUDED>110.8389</TOTAL_SUM_TAX_INCLUDED>
<TOTAL_SUM_TAX_EXCLUDED>90.113</TOTAL_SUM_TAX_EXCLUDED>
<TOTAL_TAX>20.726</TOTAL_TAX>
</ROW>
- <ROW>
<PRODUCT_NUMBER>20</PRODUCT_NUMBER>
<PRODUCT_NAME>Mutteri</PRODUCT_NAME>
<PRODUCT_INFO>Selite</PRODUCT_INFO>
<QUANTITY>5</QUANTITY>
<PRICEPERUNIT>10.1255</PRICEPERUNIT>
<DISCOUNT_PERCENTAGE>10.00</DISCOUNT_PERCENTAGE>
<VAT_RATE>24.00</VAT_RATE>
<ROW_TYPE>0</ROW_TYPE>
<SALES_ACCOUNT_NUMBER>1237777</SALES_ACCOUNT_NUMBER>
<PROPOSED_PURCHASE_ACCOUNT />
<COST_CENTER_CODE />
<COST_CENTER_INFO />
<COST_TYPE_CODE />
<COST_TYPE_INFO />
<PROJECT_CODE />
<PROJECT_INFO />
<PROJECT_TYPE_CODE />
<PROJECT_TYPE_INFO />
<TOTAL_SUM_TAX_INCLUDED>56.0446</TOTAL_SUM_TAX_INCLUDED>
<TOTAL_SUM_TAX_EXCLUDED>45.5648</TOTAL_SUM_TAX_EXCLUDED>
<TOTAL_TAX>10.4799</TOTAL_TAX>
</ROW>
- <ROW>
<PRODUCT_NUMBER />
<PRODUCT_NAME />
<PRODUCT_INFO>Seliterivin selite</PRODUCT_INFO>
<QUANTITY>0</QUANTITY>
<PRICEPERUNIT>0</PRICEPERUNIT>
<DISCOUNT_PERCENTAGE>0</DISCOUNT_PERCENTAGE>
<VAT_RATE>0</VAT_RATE>
<ROW_TYPE>1</ROW_TYPE>
<SALES_ACCOUNT_NUMBER>0</SALES_ACCOUNT_NUMBER>
<PROPOSED_PURCHASE_ACCOUNT />
<COST_CENTER_CODE />
<COST_CENTER_INFO />
<COST_TYPE_CODE />
<COST_TYPE_INFO />
<PROJECT_CODE />
<PROJECT_INFO />
<PROJECT_TYPE_CODE />
<PROJECT_TYPE_INFO />
<TOTAL_SUM_TAX_INCLUDED>0</TOTAL_SUM_TAX_INCLUDED>
<TOTAL_SUM_TAX_EXCLUDED>0</TOTAL_SUM_TAX_EXCLUDED>
<TOTAL_TAX>0</TOTAL_TAX>
</ROW>
</ROWS>
</INVOICE>

Takaisin