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

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

Tarkempi palvelukuvaus Tiekessä.

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 servicerajapintapyyntö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

WS API -rajapinta

Rajapintakuvaus:
Tuotanto: https://verkkopalkka.maventa.fi/Service/PayslipReceiverService.svc

Demo: https://verkkopalkkademo.maventa.fi/Service/PayslipReceiverService.svc

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.

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.

Toteutusesimerkki

VB.Net

1. Lisää Service Reference

2. Valitse resurssi

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