Valtuustarkistuskyselyn rajapintakuvaus yrityksen asioidessa henkilön puolesta – OrganizationalPersonMandates-kysely

Tässä artikkelissa esitellään Suomi.fi-valtuuksien valtuustarkistuskyselyn rajapintakuvaus, kun yritys asioi henkilön puolesta. Artikkelissa kerrotaan kyselyssä käytettävän OrganizationalPersonMandates-rajapinnan kutsumisesta sekä kuvataan kutsu- ja vastaussanomien sisältöä.

Rajapinnan kutsuminen

Valtuudet-palvelun tarjoaman OrganizationalPersonMandates-rajapinnan kautta tarkistetaan, onko yrityksellä oikeus asioida henkilön puolesta ja millaisissa asioissa. Rajapinta tarjotaan Palveluväylän (X-Road 6) kautta. X-Roadin SOAP-otsakkeita käytetään Palveluväylä-yhteyden lisäksi asiointipalvelun (client header) ja loppukäyttäjän (userId) tunnistamiseen Valtuudet-palvelussa.

Taulukossa on kuvattu OrganizationalPersonMandates-rajapinnan keskeiset tiedot.

Huom! Sallitut rajapinnat määritellään käyttöönoton yhteydessä, joten kaikki tarjotut rajapinnat eivät välttämättä ole asiakasorganisaation käytettävissä.

Rajapintakuvauksissa viitataan lisäksi seuraaviin X-Roadin skeematiedostoihin:

• X-Roadin skeematiedosto xroad6.xsdAvautuu uuteen ikkunaan.
• X-Roadin skeematiedosto xroad6identifiers.xsdAvautuu uuteen ikkunaan..

X-Road 6 -attribuutit

Taulukossa on esitetty X-Road 6 -attribuutit, jotka on asetettava Valtuudet-palvelua kutsuttaessa.

Huom! Taulukon kenttien pakollisuus saattaa erota X-Roadin tiedonsiirtoprotokollasta.

• X-Road-tiedonsiirtoprotokollan kuvaus

OrganizationalPersonMandates-rajapinnan kutsu- ja vastaussanomat

Kutsusanoma

OrganizationalPersonMandates-rajapintaan lähetettävä kutsu (request) sisältää kaksi elementtiä:

• Delegate-elementti yksilöi sen yrityksen, jonka valtuus asioida henkilön puolesta tarkistetaan.
• Principal-elementti yksilöi sen henkilön, jonka puolesta yritys haluaa asioida. Principal-elementtejä voi olla kutsusanomassa useita, eli yhdellä kutsusanomalla voidaan tarkistaa usean henkilön myöntämät valtuudet.

Taulukossa on kuvattu OrganizationalPersonMandates-rajapintaan lähetettävän kutsusanoman tiedot.

Vastaussanoma

Vastauksena (response) kutsusanomaan OrganizationalPersonMandates-rajapinta palauttaa listan (principalList) henkilön puolesta asioivalle yritykselle myönnetyistä valtuuksista. Valtuudet on ryhmitelty sen mukaan, mitä valtuuksia kukin henkilö on myöntänyt puolestaan asioivalle yritykselle. Jos kutsun käsittelyssä tapahtuu virhe, virheen syy palautetaan exceptionMessage-kentässä.

Taulukossa on kuvattu OrganizationalPersonMandates-rajapinnan lähettämän vastaussanoman tiedot.

Taulukossa on kuvattu principalList-elementin tiedot. PrincipalList sisältää yhden tai useamman principal-elementin, joka ilmaisee valtuuttaneen henkilön henkilötunnuksen tai UID:n ja asiat, joita valtuus koskee.

Taulukossa on kuvattu principal-pääelementin tiedot. Principal-pääelementti sisältää kolme elementtiä:

• PrincipalId ilmaisee valtuuttaneen henkilön henkilötunnuksen tai UID:n.
• Issue kertoo, minkä asian tai asioiden hoitamiseen henkilö on valtuuttanut yrityksen.
• Incomplete sisältää tiedon siitä, onko kaikki säännöt voitu tarkistaa valtuuttaneen henkilön osalta.

Sanomaesimerkki

Seuraavassa on tämän artikkelin asioista koostettu esimerkki. Siitä käyvät ilmi rajapinnan kutsuminen sekä kutsu- ja vastaussanomat tarkistettaessa yrityksen valtuuksia asioida henkilön puolesta.

OrgPersonMandates - Haetaan asioivan organisaation henkilövaltuudet

<!-- request -->
<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <id xmlns="http://x-road.eu/xsd/xroad.xsd">6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd">kela-rova-user</userId>
        <client xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SUBSYSTEM">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova</ns3:subsystemCode>
        </client>
        <service xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SERVICE">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova</ns3:subsystemCode>
            <ns3:serviceCode>rovaOrgPersonMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns2:rovaOrgPersonMandatesService xmlns:ns2="http://xml.vrk.fi/ws/Rova/OrgPersonMandates/Entities" xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegate>aaaaaaa-a</delegate>
                <principal>ppkkvv-aaaa<</principal>
                <principal>ppkkvv-bbbb<</principal>
                <principal>ppkkvv-cccc<</principal>
            </request>
        </ns2:rovaOrgPersonMandatesService>
    </S:Body>
</S:Envelope>

<!-- response -->
<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <id xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id>
        <requestHash xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">Ryi6rQMaG6BDbXoLCSZbriP5IRMw0EOABKnslSvGMNoBK89k5b0b8Qj3GK/2+BSJZ3jF7O2LkX5DGaobzdPIIg==</requestHash>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">kela-rova-user</userId>
        <client xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SUBSYSTEM">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova</ns3:subsystemCode>
        </client>
        <service xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SERVICE">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova</ns3:subsystemCode>
            <ns3:serviceCode>rovaOrgPersonMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns4:rovaOrgPersonMandatesServiceResponse xmlns:ns2="http://x-road.eu/xsd/identifiers" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://xml.vrk.fi/ws/Rova/OrgMandates/Entities">
            <request>
                <delegate>aaaaaaa-a</delegate>
                <principal>ppkkvv-aaaa</principal>
                <principal>ppkkvv-bbbb</principal>
                <principal>ppkkvv-cccc</principal>
            </request>
            <response>
                <principalList>
                    <principal>
                        <principalId>ppkkvv-aaaa</principalId>
                        <issue>http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu</issue>
                        <issue>http://valtuusrekisteri.suomi.fi/palkkatietojen_ilmoittaminen?principalId=8888888-3</issue>
                        <incomplete>false</incomplete>
                    </principal>
                    <principal>
                        <principalId>ppkkvv-bbbb</principalId>
                        <incomplete>false</incomplete>
                    </principal>
                    <principal>
                        <principalId>ppkkvv-cccc</principalId>
                        <incomplete>true</incomplete>
                    </principal>
                </principalList>
            </response>
        </ns4:rovaOrgPersonMandatesServiceResponse>
    </S:Body>
</S:Envelope>