Valtuustarkistuskyselyn rajapintakuvaus yrityksen asioidessa toisen yrityksen puolesta – OrganizationalMandates-kysely

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

Rajapinnan kutsuminen

Valtuudet-palvelun tarjoaman OrganizationalMandates-rajapinnan kautta tarkistetaan, onko yrityksellä oikeus asioida toisen yrityksen 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 OrganizationalMandates-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

OrganizationalMandates-rajapinnan kutsu- ja vastaussanomat

Kutsusanoma

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

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

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

Vastaussanoma

Vastauksena (response) kutsusanomaan OrganizationalMandates-rajapinta palauttaa listan (principalList) toisen yrityksen puolesta asioivalle yritykselle myönnetyistä valtuuksista. Valtuudet on ryhmitelty sen mukaan, mitä valtuuksia mikäkin yritys on myöntänyt toisen puolesta asioivalle yritykselle. Jos kutsun käsittelyssä tapahtuu virhe, virheen syy palautetaan exceptionMessage-kentässä.

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

Taulukossa on kuvattu principalList-elementin tiedot. PrincipalList sisältää yhden tai useamman principal-elementin, joka ilmaisee valtuuttaneen yrityksen yritystunnuksen ja asiat, joita valtuus koskee.

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

• PrincipalId ilmaisee valtuuttaneen yrityksen yritystunnuksen.
• Issue kertoo, minkä asian tai asioiden hoitamiseen yritys on valtuuttanut toisen yrityksen.
• Incomplete sisältää tiedon siitä, onko kaikki säännöt voitu tarkistaa valtuuttaneen yrityksen 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 toisen yrityksen puolesta.

OrgMandates – Haetaan asioijan yritysvaltuudet

<!-- 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>kaparova3</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>rovaOrgMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns2:rovaOrgMandatesService xmlns:ns2="http://xml.vrk.fi/ws/Rova/OrgMandates/Entities" xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegate>aaaaaaa-a</delegate>
                <principal>bbbbbbb-b</principal>
                <principal>ccccccc-c</principal>
                <principal>ddddddd-d</principal>
            </request>
        </ns2:rovaOrgMandatesService>
    </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>kaparova3</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>rovaOrgMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns4:rovaOrgMandatesServiceResponse 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>bbbbbbb-b</principal>
                <principal>ccccccc-c</principal>
                <principal>ddddddd-d</principal>
            </request>
            <response>
                <principalList>
                    <principal>
                        <principalId>bbbbbbb-b</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>ccccccc-c</principalId>
                        <incomplete>false</incomplete>
                    </principal>
                    <principal>
                        <principalId>ddddddd-d</principalId>
                        <incomplete>true</incomplete>
                    </principal>
                </principalList>
            </response>
        </ns4:rovaOrgMandatesServiceResponse>
    </S:Body>
</S:Envelope>