Verkkolaskuosoitteiston latauksen rajapinnasta

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.

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ä. Määrittely on APIX Messaging Oy:n tekemä. Se löytyy osoitteesta: https://apix.fi/eaddress

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

SFTP-puolella JSON-nouto on yksi tarjotuista optioista. JSON-muotoisen osoitteiston voi ladata Tiedostot-kohdasta, ja linkissä lukee JSON (eAddress). Integraatiorajapinnasta sen saa osoitteesta:

https://test.osoitteisto.bel.fi/server/Integration/jsonExport 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” : []

          },

          …

        ]

      ]

    }