Verkkolaskuosoitteiston latauksen rajapinnasta

Verkkolaskuosoitteet ja välittäjätunnukset

Verkkolaskuosoitteistosta voi ladata listauksen verkkolaskuosoitteistossa olevien organisaatioiden osoitteista sekä erikseen listauksen verkkolaskuvälittäjien välittäjätunnuksista.

Verkkolaskuosoitteistoon sisältyviä tietoja voi ladata suoraan käytettäväksi tilaajan omissa järjestelmissä. Latauksessa ladataan kaikki osoitteiston tiedot. Tiedot voi ladata selaimen kautta tiedostoina tai rajapinnan kautta.

Tiedot voi ladata CSV, XML ja JSON -muodoissa.

Välittäjätunnusten lataaminen

  • Lisätietoja välittäjätunnuksien lataamisesta

    JSONin käyttö:

    Http requestiin lisätään header

    Accept: application/json

    Oletuskäytös on tuottaa ulos XML, eli se toimii samoin kuin:

    Accept: application/xml

    verkkolaskuosoite.fi.

    Löytyy tiedostot: owners.xsd, owners.json, owners.xml.

    Ohjeita XML

    XML scheman malli alla. Owners-listan alla on Owner, jossa on aina yhden operaattorin tiedot.

    <Owners Version=”1.0″>

        <Owner>

            <BasicInfo>

                <ServiceID>

                    <ID>556964-9287</ID>

                </ServiceID>

                <BusinessId>556964-9287</BusinessId>

                <Name>APIX Messaging AB</Name>

                <Prefix>AA</Prefix>

                <WWW>https://apixmessaging.se/</WWW>

            </BasicInfo>

            <Contact>

                <Name>APIX Kundtjänst</Name>

                <Phone>+46 (0)705 514 300</Phone>

                <Email>info@apixmessaging.se</Email>

            </Contact>

            <Address>

                <Address>APIX Messaging AB</Address>

                <Address>Bror Nilssons gata 5</Address>

                <PostalCode>417 55</PostalCode>

                <Cite>Göteborg</Cite>

                <Country>Sweden</Country>

            </Address>

        </Owner>

        … ja sitten uusi <Owner> jossa seuraavan välittäjän tiedot …

    Samaan tapaan on JSON:

    {

       ”owner” : [

          {

             ”address” : {

                ”address” : [

                   ”APIX Messaging AB”,

                   ”Bror Nilssons gata 5”

                ],

                ”city” : ”Göteborg”,

                ”country” : ”Sweden”,

                ”postalCode” : ”417 55”

             },

             ”basicInfo” : {

                ”businessId” : ”556964-9287”,

                ”name” : ”APIX Messaging AB”,

                ”prefix” : ”AA”,

                ”serviceId” : [

                   ”556964-9287”

                ],

                ”www” : ”https://apixmessaging.se/”

             },

             ”contact” : {

                ”email” : ”info@apixmessaging.se”,

                ”name” : ”APIX Kundtjänst”,

                ”phone” : ”+46 (0)705 514 300”

             }

          },

          … seuraavan välittäjän tiedot …

     

    Vastaavasti määritelty https://verkkolaskuosoite.fi/server/Integration/ownersSchema ja https://verkkolaskuosoite.fi/server/Integration/owners joiden kautta voi ladata myös nämä tiedostot samaan tapaan kuin osoitteistossakin. Jälkimmäisessä vaaditaan kirjautumista omalla käyttäjätunnuksella.

    Schema eli XSD on määritys tuolle XML sisällölle. JSON:n osalta ei ole schema-tiedostoa, mutta JSON on johdettu automaattisesti XML-muodosta.

Organisaatioiden verkkolaskuosoitteiden lataus

Alla on tarkempia tietoja kustakin latausmuodosta.

CSV-muoto.

CSV-muodossa on seuraavat kentät:

”Yrityksen nimi”;

”Y-tunnus”;

”Operaattori”;

”Lähettää”;

”Vastaanottaa”;

”Vastaanotto-osoite”;

”Vastaanotto-osoitteen nimi”;

”Muokattu”;

”Välittäjän tunnus”;

”OVT-tunnus”;

”Ensisijainen vastaanotto-osoite”;

”Liitteiden vastaanotto”

Esimerkiksi Tieken osalta lukee seuraavaa:

”TIEKE Tietoyhteiskunnan kehittämiskeskus ry, TIEKE Utvecklingscentralen för Informationssamhälle rf”;”0494484-2″;”OpusCapita Solutions Oy”;”Kyllä”;”Kyllä”;”003704944842″;”Tieke Tietoyhteiskunnan Kehittämiskeskus ry”;”2019-09-22T23:08:11.956″;”E204503″;”003704944842″;”Ei”;”Kyllä”

Puolipiste ei ole merkittävä lainausmerkkien sisällä, vaan se pitää tulkita kenttäerottimena ainoastaan lainausmerkkien ulkopuolella.

Jos nimessä itsessään on lainausmerkki, se esitetään kahdennettuna.

Esimerkiksi verkkolaskuosoitteen nimi kuten Test”;test2 joka näkyisi tiedostossa näin:

”Test””;test2”

Käytetty CSV-muoto on RFC-standardin mukainen https://en.wikipedia.org/wiki/Comma-separated_values#RFC_4180_standard mutta sillä erotuksella että kentät on erotettu puolipisteillä, ei pilkulla. Tämä on tehty siksi, että Excelissä pitää käyttää puolipistettä.

XML-formaatissa lataus 

XML-formaatti noudattaa eAddress-määrittelyä. Se löytyy osoitteesta: https://tieke.fi/wp-content/uploads/2024/01/eAddress2.0.pdf

Yksinkertaisimmillaan datan saa ladattua ohjelmallisesti palvelimen puolelta:

curl –basic –user ’tunnus:salasana’ -X GET url

Tunnus == verkkolaskuosoite.fi tunnus (email)
Salasana == verkkolaskuosoite.fi salasana

url == XML (eAddress) -linkin osoite kirjautuneen näkymästä: Lataussopimus -> Lataussopimuksen numeron linkki -> XML (eAddress)

(muotoa

https://verkkolaskuosoite.fi/server/Register/xmlByContract/osoitteisto.xml?m=avain)

JSON käyttäminen

JSON-muotoisen osoitteiston voi ladata Tiedostot-kohdasta, linkissä lukee JSON (eAddress). Integraatiorajapinnan osoitteen saa linkin osoitteesta. Se on muotoa:

https://verkkolaskuosoite.fi/server/Register/json/osoitteisto.json?s=xxxxxxxxx…ja tämän käyttäminen vaatii tilaajan käyttäjätunnuksen ja salasanan esimttämistä HTTP basic authille.

JSON-muotoista sanomarakenteesta malli alla.

Kenttien tulkinnassa auttaa APIX:n XML-schemaa varten rakennettu dokumentaatio, koska JSON on johdettu mekaanisesti ja noudattelee XML:n kanssa 1:1 samaa rakennetta. eaddress:n dokumentaatio on tässä osoitteessa: https://apix.fi/eaddress

Rakenteessa ylimpänä tasona on periaatteessa XML:n Batch-elementti, jonka jälkeen tulee organization-lista, jossa on organisaation perustiedot, ja sitten eaddress:t jotka ovat organisaation verkkolaskuosoitteita ja liitetty kunkin organisaation alle. Tässä viitataan eAddressin versioon 1.13 , se eroaa versiosta 1.12 vain siten että eaddressin alla on 2 uutta kenttää nimeltään ownerRef (omistajan osoitteelle antama sisäiseen käyttöön tarkoitettu viite) ja primaryAddress (osoitteen ensisijaisuus).

  • Malli JSON-rakenteesta

    {

       ”timestamp” : ”2019-05-13T12:23:18.491+0000”,

       ”function” : ”REPLACE”,

       ”version” : ”1.13”,

       ”organization” : [

          {

             ”street” : [],

             ”country” : null,

             ”postalCode” : null,

             ”identifier” : [

                {

                   ”value” : ”0657728-1”,

                   ”type” : ”BUSINESSID”

                }

             ],

             ”www” : null,

             ”eaddress” : [

                {

                   ”url” : null,

                   ”authorizationToken” : null,

                   ”direction” : ”SEND”,

                   ”permissionToPublish” : true,

                   ”specialRequirements” : false,

                   ”active” : true,

                   ”ownerRef” : null,

                   ”name” : ”Päijät-Hämeen Kiinteistöyhdistys Ry”,

                   ”serviceID” : {

                      ”value” : ”NDEAFIHH”,

                      ”idtype” : ”BIC”

                   },

                   ”permissionToSend” : null,

                   ”supportAttachments” : true,

                   ”context” : ”EINVOICE”,

                   ”operation” : null,

                   ”contacts” : [],

                   ”primaryAddress” : false,

                   ”id” : [

                      {

                         ”idtype” : ”IBAN”,

                         ”value” : ”FI2615873006105525”

                      }

                   ],

                   ”comment” : null,

                   ”addressOwnerServiceID” : null

                },

                {

                   ”direction” : ”RECEIVE”,

                   ”permissionToPublish” : true,

                   ”url” : null,

                   ”authorizationToken” : null,

                   ”serviceID” : {

                      ”idtype” : ”BIC”,

                      ”value” : ”NDEAFIHH”

                   },

                   ”name” : ”Päijät-Hämeen Kiinteistöyhdistys Ry”,

                   ”supportAttachments” : true,

                   ”permissionToSend” : true,

                   ”specialRequirements” : false,

                   ”ownerRef” : null,

                   ”active” : true,

                   ”operation” : null,

                   ”context” : ”EINVOICE”,

                   ”comment” : null,

                   ”addressOwnerServiceID” : null,

                   ”contacts” : [],

                   ”id” : [

                      {

                         ”value” : ”FI2615873006105525”,

                         ”idtype” : ”IBAN”

                      }

                   ],

                   ”primaryAddress” : false

                }

             ],

             ”contacts” : [],

             ”name” : ”Päijät-Hämeen Kiinteistöyhdistys Ry”,

             ”countryCode” : null,

             ”city” : null,

             ”additionalName” : []

          },

          …

        ]

      ]

    }