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
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/jsonByContract/osoitteisto.json?m==xxxxxxxxx…
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” : []
},
…
]
]
}
