Yleistä
Tulkintaohje
Sanomavastaukset
Yleistä
Ohjelmistorajapinta mahdollistaa sekä aineistojen noudon Netvisorista että aineistojen tuonnin Netvisoriin. Rajapinnan tarjoamat resurssit on jaettu ylätason kategorioihin.
Yhteistä kaikille tapahtumille on:
- Päivämäärät ovat ANSI–muodossa
- Maakoodit ovat aina ISO 3166 –muodossa
- Liitteet ovat aina Base64 -enkoodattuna XML-sanomaan
- Tyhjiä elementtejä ei tarvitse kirjoittaa XML-sanomaan, esimerkiksi päivityspyynnössä tyhjä elementti tulkitaan rajapinnassa käskyksi päivittää arvo tyhjäksi
- Pakollisia kenttiä ei tule jättää tyhjäksi
- Elementtien täytyy olla DTD:n mukaisessa järjestyksessä
Skandinaavisten kirjainten (Ä, ä, Ö, ö tai Å, å) saamiseksi käyttöliittymään on sanoman oltava ISO/IEC 8859-15-enkoodatussa muodossa, mutta xml-deklaraatiota ei kuitenkaan tarvita. Netvisorin palvelinpuoli tekee sisällölle tarvittavat esikäsittelyt, jolloin aineiston tulee aina alkaa <root>. Mikäli ääkköset eivät toimi ISO/IEC 8859-15 enkoodatussa muodossa, voidaan enkoodaus muuttaa UTF-8 muotoon.
Tee isot haut ja tietojen siirrot virka-ajan ulkopuolella, jollei niiden siirtoon virka-aikana ole erityistä tarvetta. Tietojen siirron aiheellinen tiheys eroaa resurssi- ja käyttötapauskohtaisesti. Monissa tapauksissa siirto kerran vuorokaudessa tai kuukaudessa riittää. Voit nopeuttaa siirtoja myös sopivilla rajauksilla käyttäen resurssien parametreja.
Tulkintaohje
Ohessa on kuvattu integraatiorajapinnan eri merkintöjen tarkoitus ja tulkinnat.
Eri sanomien XML-rakenne on kuvattu taulukkomuotoisesti niistä kohdista sanomia kun se on mahdollista ja loogista. XML:n rakenteellisuudesta johtuen kuvauksissa on jouduttu käyttämään esimerkiksi viittauksia ohjeistuksen eri kohtiin, jotta kokonaisuus on pysynyt selkeänä.
Rakennekuvausten perusrakenne on seuraava:
Kutsu:
- Perustiedot
- Käytettävä resurssi
- GET - yleensä datan noutoa Netvisorista
- POST - yleensä datan tuontia Netvisoriin
- Parametrit
- Yleensä QueryString:ssä määritettäviä, erotetaan varsinaisesta resurssista ?-merkillä ja tämän jälkeen &-merkillä
- Kaikilla resursseilla ei ole
- Yleensä QueryString:ssä määritettäviä, erotetaan varsinaisesta resurssista ?-merkillä ja tämän jälkeen &-merkillä
- XML-rakenne dataa tuotaessa (POST)
- Kuvattu XML:n rakenne sekä esim. elementtien määrät ja pakollisuus
Mikäli POST-sanomalla käytetään itsesulkevia tageja, niin huomaa että näitä ei lueta ollenkan, mukaanlukien mahdolliset attribuutit. Esimerkiksi asiakaskortin elementtiä <email/> ei lueta ollenkaan, mutta <email></email> taas tyhjentää kyseisen arvon Netvisorin asiakaskortilta.
Vastaus:
Jokaiseen kutsuun vastataan XML-vastauksella, jonka rakenne vastaa suurilta osin kutsua. Sanoman yleisrakenteen voi katsoa alemmasta kappaleesta. Vastaus GET-tyyppisiin noutosanomiin sisältää resurssikohtaisen datarakenteen, joka on kuvattu kussakin resurssikuvauksessa erikseen. POST-tyyppisiin tuontisanomiin tulee sanomasta riippuen vastauksessa Replies-elementti, jonka sisällä on esim. InsertedDataIdentifier-elementti sisältäen lisätyn asian ID-arvon.
Sanomavastaukset
Jokaiseen rajapintakutsuun vastataan vakioidulla sanomavastauksella. GET-tyyppisissä sanomissa vastaus sisältää pyydetyn datan (<resurssikohtainen elementti>) ja POST-tyyppisissä mahdollisesti tapauskohtaisen vastauksen (Replies).
Vastaussanoman yleinen rakenne:
Elementti: Root (1 ilmentymä)
Elementti: Root/ResponseStatus (1 ilmentymä)
| Elementti | Muoto | Kuvaus | Esimerkki | Lisätiedot |
| Status | Merkkijono | Indikoi tapahtuiko kutsun käsittelyssä virhettä | OK | FAILED |
| Status | Merkkijono | Virhevakio ja -kuvaus | Tämä elementti vain jos FAILED tilassa. Ks. Virheden hallinta | |
| TimeStamp | Päivämäärä | Vastauksen aikaleima | 01.01.2018 12:00:00 |
Vastauksen tyyppi on sidoksissa dataliikenteen suuntaan:
1. Noudettaessa dataa Netvisorista
Noudettu data on omana elementtinään sanomassa:
Elementti: Root/ResponseStatus/<resurssikohtainen elementti>
2. Tuotaessa dataa Netvisoriin
Vastaus sisältää Replies-elementin ja sen sisällä tapauskohtaisesti dataa:
Elementti: Root/ResponseStatus/Replies (0-1 ilmentymä)
| Elementti | Muoto | Kuvaus | Esimerkki | Lisätiedot |
| InsertedDataIdentifier | Merkkijono | |||
| TAI | ||||
| Reply | Merkkijono | |||
Oheiset elementit esiintyvät 0-n kertaa.
Oliko tästä vastauksesta apua? Kyllä Ei
Send feedback