Created by Lassi Pesari, last modified on Apr 07, 2016

Maventa-verkkopalkan käyttöönotto ja API kuvaus

Verkkopalkkapalvelulla palkanmaksaja toimittaa palkkalaskelmat sähköisessä muodossa palkansaajien tarkasteltavaksi verkkopankin kautta. Tarkempi palvelukuvaus Tiekessä.

Sovellusohje

Palkanmaksujärjestelmän lisääminen Maventa verkkopalkkaan

Uuden palkanmaksujärjestelmän lisääminen vaatii käyttäjätunnuksen lisäämisen verkkopalkan rekisteriin. Tunnus annetaan ottamalla yhteyttä tukeen.

Tunnuksia käytetään web service rajapintapyyntöjen tunnistautumiseen.

Tunnukset annetaan pyynnön header-osuudessa avain-arvo-pareina:
käyttäjätunnus = ”Username”
salasana = ”Password”

Koodiesimerkki:

Using context = New OperationContextScope(electronicPayslipService.InnerChannel)
OperationContext.Current.OutgoingMessageHeaders.Add(MessageHeader.CreateHeader(”Username”, ””, username))
OperationContext.Current.OutgoingMessageHeaders.Add(MessageHeader.CreateHeader(”Password”, ””, password))
Dim ids As String = electronicPayslipService.GetContractCustomerExtenalIds(IDENTIFIER)
End Using

Verkkopalkan tukemat pankit

Verkkopalkassa pidetään kirjaa pankeista, joiden verkkopankkien kautta käyttäjän on mahdollisuus kirjautua verkkopalkkaan. Rajapinnasta on saatavissa listaus tuettujen pankkien BIC-koodeista

API-pyyntö:

string[] GetActiveBankBicCodes()

Palkanmaksajan aktivointi ja deaktivointi

Ennen palkkalaskelmien lähettämistä palkanmaksaja on aktivoitava Maventa verkkopalkkaan. Aktivointi voidaan suorittaa web service-pyynnöllä.

API-pyyntö:

Guid ActivateCustomerPayrollContract
(DateTime ContractBeginDate, string ExternalIdentifier, string Name, string VatId)

Parametrit:

DateTime ContractBeginDate – se ajankohta jolloin palkanmaksaja aktivoidaan verkkopalkkaan. Ko hetkestä lähtien palkanmaksajan lähettämät aineistot vastaanotetaan palveluun ja käsitellään
string ExternalIdentifier – asiakasjärjestelmän antama tunniste palkanmaksajalle
string Name – yrityksen nimi joka näkyy palkansaajalle palkkalaskelmalistauksessa
string VatId – yrityksen yksilöivä y-tunnus
Aktivoimisen jälkeen verkkopalkkapalvelu on valmis ottamaan vastaan palkkalaskelmia. Mikäli palkanmaksaja haluaa lopettaa palvelun käytön, lähetetään deaktivoimispyyntö verkkopalkkapalveluun.

API-pyyntö:

bool DeactivateCustomerPayrollContract(Guid CustomerId, string ExternalIdentifier, string VatId)

Parametrit – järjestelmästä haetaan deaktivoitavaa sopimusta ensin CustomerId:llä sitten ExternalIdentifier:llä ja lopuksi y-tunnuksella
Listauksen verkkopalkkaan aktivoitujen yritysten y-tunnuksista saa API-pyynnöllä string[] GetContractActiveCustomerVatIdentifiers()

Saatavissa on rekisteröitymisen tila myös yhden palkanmaksajan osalta

API-pyyntö:

string GetPayerRegistrationState(string VatId)

Tulos RegistrationState .xsd formaatissa

LIITE Registration State

Palkkalaskelmien lähettäminen

Palkkalaskelmat lähetetään verkkopalkkapalveluun PayslipXml-muotoisina zip-pakattuina dokumentteina web service-rajapinnan kautta. Maventa verkkopalkassa on tuettuna versio 2.0, joka tukee usean palkkalaskelman esittämisen samassa xml-dokumentissa.

PayslipXml 2.0 -sanomakuvaus:

http://www.tieke.fi/display/verkkopalkka/PayslipXML_v.2.0

API-pyyntö:

Guid SubmitDeliveryBatch(Guid BatchId, string OriginalFileName, Stream ZipFile)

Parametrit:

Guid BatchId – lähettävän järjestemän antama tunnus lähetettävälle tiedostolle. Yksilöi lähetyksen verkkopalkassa.
string OriginalFileName – lähettäjän antama tiedostonimi. Ei tarvitse olla uniikki
Stream ZipFile – lähetetty aineisto zip-pakattuna. Zip-tiedosto voi sisältää pdf-liitteitä, joihin viittaus xml-tiedostossa
Pyyntö palauttaa verkkopalkan generoiman tunnisteen lähetyserälle

PayslipXml-dokumentin käsittely

Verkkopalkkapalvelun ws-rajapintaan lähetetty zip-tiedosto puretaan ja xml-tiedosto validoidaan PayslipXML_v2.0_schema.xsd -schemaa vasten.

Virheellisestä xml-rakenteesta rajapinta palauttaa vastauksena schema-virheen. Oikeanmuotoinen xml tallentuu verkkopalkan jonoon, jonka jälkeen aineisto prosessoidaan verkkopalkassa palkkalaskelmiksi käyttäjän katsottavaksi esilläpitopalveuun. Laskelma on lähetyksen jälkeen jonotilanteesta riippuen pienellä viiveellä palvelussa katsottavissa.

Raportointi ja laskutus

Pankki veloittaa operaattoria palkansaajista, joiden palkkalaskelma on katsottavissa verkkopalkkapalvelussa.

Maventa veloittaa asiakkaitaan tai ohjelmistokumppaneitaan transaktiopohjaisesti jokaisesta verkkopalkkaan lähetetystä verkkopalkkalaskelmasta hinnaston mukaisesti

Transaktiotiedot

Verkkopalkasta on saatavissa transaktiotiedot koskien annettua raportointiväliä. Tulosjoukko on Transactiondata.xsd-muodossa.

LIITE Transaction data

API-pyyntö:

string GetContractedPayslipTransactions(DateTime EndDate, DateTime BeginDate)

Transaktiotiedot:

Verkkopalkasta on saatavissa transaktiotiedot koskien annettua raportointiväliä. Tulosjoukko on Transactiondata.xsd-muodossa.

LIITE

API-pyyntö:

string GetContractedPayslipTransactions(DateTime EndDate, DateTime BeginDate)

Toteutusesimerkki VB.Net

1. Lisää Service Reference

2. Valitse resurssi

url: ws.verkkopalkka.maventa.fi/PayslipReceiverService.svc LINKKI

Aineiston lähettäminen verkkopalkkaan:

Imports PayslipXmlExport.PayslipService
Imports System.IO
Namespace PayslipXmlExport
Public Class SampleServiceExport
Public Sub export()
Dim serviceClient As New PayslipReceiverServiceClient
Dim batchGuid As Guid = Guid.NewGuid()
Dim fileName As String = ”samplepayslipbatch.zip”
Dim stream As New FileStream(”c:\temp\samplepayslipbatch.zip”, FileMode.Open)
Dim deliveryBatchGuid As Guid = serviceClient.SubmitDeliveryBatch(batchGuid, fileName, stream)
End Sub
End Class
End Namespace

Täytä ja lähetä alla oleva lomake - olemme sinuun mahdollisimman pian yhteydessä.

Jos sinulla on tekninen kysymys, ole hyvä ja tutustu Maventa-asiakastukeen.


Etunimi

Sukunimi

Yritys

Puhelin

Sähköposti