Netbox - Manuals ·

Netbox - NetAPI

Tämä dokumentaatio on päivitetty viimeksi 5.2.2020.

Netboxin NetAPI on ohjelmointirajapinta partnereille. NetAPI on yksityinen palvelu, johon pääsy vaatii käyttäjätunnuksen, asiakastunnuksen ja salasanan perusteella muodostetun käyttöoikeustiivisteen. Partnereilla on mahdollisuus kokeilla rajapintaa testiympäristössä pyytämällä tunnukset esimerkiksi Netboxin asiakaspalvelusta ([email protected]). Lisäksi omaan käyttöön saa myös valmiin toteutuksen PHP- ja C# -kielillä, joiden avulla partneri voi esimerkkien avulla toteuttaa helpommin integraation järjestelmäänsä.

Palvelut ovat luonteeltaan REST-tyylisiä palvelupyyntöjä. Palvelut suoritetaan salatulla HTTPS-yhteydellä. Tietorakenteiden siirtomuotona käytetään JSON-muotoa. Palvelukutsujen onnistuminen ilmaistaan standardein http- paluukoodein (katso kohta HTTP-tilakoodeja alempana).

NetAPI on taaksepäin yhteensopiva, joka tarkoittaa olemassa olevien rakenteiden säilymistä tai laajentamista ei-pakottavalla tavalla. NetAPIa käyttävien ohjelmistojen on hyvä ottaa tämä huomioon ja välttää hylkäämästä vastauksia, joissa esiintyy kenttiä, joita toteutusvaiheen aikana ei vielä ollut tiedossa. Vastaavasti taaksepäin yhteensopivuudella tarkoitetaan, ettei NetAPI hylkää pyyntöjä, vaikka myöhemmin määritellyt kentät puuttuisivatkin pyynnöstä. Uusia palveluja voidaan lisätä kokonaan uusilla rakenteilla.

Tässä dokumentissa kuvatun palvelun versio on 1.01. Versionumeroinnin tarkoitus on ilmaista taaksepäin yhteensopivuuden varmistamista: MAJOR.MINOR; Kun MAJOR versionumero vaihtuu (esimerkiksi 1.0 seuraajaksi tulee 2.0), palvelurajapinta ei välttämättä ole kaikilta osin yhteensopiva. Kun ainoastaan MINOR numero vaihtuu, palvelurajapinnan taaksepäin yhteensopivuus varmistetaan.

API - palvelupyynnöt:

Asiakkaat:
GET palveluosoite/customers?search=<pattern>
GET palveluosoite/customers/<customer_identifier>
POST palveluosoite/customers/<customer_identifier>

Sanomat:
GET palveluosoite/messages/available
GET palveluosoite/messages/headers
GET palveluosoite/messages/headers/<type>
GET palveluosoite/messages/<type>
GET palveluosoite/messages/id/<id>
GET palveluosoite/messages/statuses/<vat_identifier>
POST palveluosoite/messages
POST palveluosoite/messages (resend)

Yritystiedot:
GET palveluosoite/companies/<vat_identifier>
GET palveluosoite/companies?search=<company_name>

Täällä voit testata NetAPI Demo tunnuksia, kyselyjä ja nähdä mitä ne palauttaa:
NetAPI Demo -portaali

HTTP-tilakoodeja

Koodi	Arvo	Selite
200	OK	Kutsu onnistui
204	No Data	Ei haettavaa dataa
400	Bad Request	Kutsun parametrissa virhe
401	Unauthorized	Kirjautuminen puuttuu tai operaatioon ei ole oikeuksia
404	Not Found	URL todennäköisesti virheellinen
500	Internal Error	Järjestelmävirhe

Autentikaatio

Käyttöoikeustietue muodostetaan kahdessa vaiheessa.

Vaihe 1:

Palvelukutsuissa vaaditaan kirjautumisessa saatu käyttöoikeustietue (access token).

Tiketin muodostus

GET palveluosoite/tickets/<username>[/<customer_identifier>]

username = NetAPI -käyttäjätunnus
customer_identifier = asiakastunnus (esim. Y-tunnus tai optio -any-)

Muodostetaan käyttäjätunnuksen ja asiakastunnuksen perusteella tiketti kirjautumista varten. Pyynnössä ei välitetä salasanaa lainkaan palvelimelle.

Käyttäjätunnuksen parina voidaan antaa asiakastunnus. Asiakastunnuksen puuttuessa toimitaan kuten kättäjätunnuksen arvoa olisi käytetty asiakastunnuksena. Asiakastunnus voi olla myös arvoa ” -any- " ("viiva any viiva").

Huomioitavaa, että muodostaessa tikettiä ”-any-” optiolla (kentässä <customer_identifier> ) antaa admin -oikeuden kaikkiin tunnuksen alla olevien yritysten aineistoihin (sanomat, data ja asiakastietojen tallennus ja muokkaus).
Vaihtoehtoisesti annettaessa esim. Y-tunnus kentässä <customer_identifier>, rajataan oikeudet vain kyseisen yrityksen aineistoihin, dataan ja asiakastietoihin.

Parametrit

url username NetAPI käyttäjätunnus

url customer identifier NetAPI käyttäjätunnukseen kytketty asiakastunnus

Palautettava tietorakenne

TicketRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
ticket	string	tiketti
expires	date-time	tiketin voimassaolo päättyy

Tiketti kirjautumista varten. Tiketti on voimassa kahden minuutin ajan.



URL: https://<palveluosoite>/tickets/NB1234DEMTEST/1234567-8
	
Palaute:

{
	"version":"1.01",
	"ticket":"a33fe7c61bd51ef7c510fdeb7d840f75a105acaf",
	"expires":"Thu, 14 Dec 2017 14:05:18 EET"
}

Vaihe 2:

Access token

GET palveluosoite/tokens/<secured_hash>

Muodostetaan varmennetun tiivisteen (secured hash) perusteella käyttöoikeustietue (access token). Pyynnössä ei välitetä käyttäjätunnusta, asiakastunnusta eikä salasanaa lainkaan palvelimelle.

Parametrit

url secured_hash Heksadesimaalinen sha1-tuottama varmennettu tiiviste peräkkäin yhteenliitetystä salasanasta ja tiketistä.

Palautettava tietorakenne

TokenRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
token	string	Käyttöoikeustietue
expires	date-time	Käyttöoikeustietueen voimassaolo päättyy

Käyttöoikeustietue ja lisätietoja. Käyttöoikeustietue on voimassa tunnin ajan.

	
URL: https://<palveluosoite>/tokens/8ea7d2e8f5dd2260d225e563f04ba7afe956c7f2

Palaute:

{
	"version":"1.01",
	"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiTkI0MTA4QVNLVEVTVCIsImN1c3Rvb...f-Lds",
	"expires":"Thu, 14 Dec 2017 16:36:26 EET"
}

Kaikki muut kutsut vaativat palautetun käyttöoikeustietueen (access token) Authorization headerinä:

Authorization header

Authorization: Bearer <käyttöoikeustietue>

Istunnon toiminnot rajautuvat autentikoinnissa ilmaistuun asiakkuuteen. Esimerkiksi, sanoman poiminta poimii vain asiakkaalle tulevia sanomia.

Asiakastunnuksen ollessa tyhjä tai käyttäjätunnus itsessään, toiminnot rajautuvat käyttäjätunnuksen tietoihin. Asiakastunnuksen ollessa ” -any- ”, toiminnot rajautuva käyttäjätunnuksen kaikkiin asiakkuuksiin.

ASIAKASTIEDOT

Haetaan asiakkaita hakutekijällä

GET palveluosoite/customers?search=<pattern>

Parametrit

url pattern Hakutekijä
Voit käyttää %-merkkiä, esim. Yritysnim%, hakee kaikki asiakkaat, joiden nimi alkaa "Yritysnim" -sanalla.

Palautettava tietorakenne (luettelo löydetyistä asiakkaista)

CustomerItemRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Asiakkaan tunniste (asiakkaan/HUBin ohjelmistossa, yleensä Y-tunnus).
name	string	Asiakkaan nimi.
vat_identifier	string	Asiakkaan y-tunnus.
edi_identifier	string	Asiakkaan OVT-tunnus.
free_text	string	Vapaata tekstiä.
open_invoice_channels	string	• Jos open_invoice_channels arvo on 0, silloin myyntilaskukanava on OFF ja ostolaskukanava on OFF (molemmat kiinni). • Jos open_invoice_channels arvo on 1, silloin myyntilaskukanava on ON ja ostolaskukanava on OFF. • Jos open_invoice_channels arvo on 2, silloin myyntilaskukanava on OFF ja ostolaskukanava on ON. • Jos open_invoice_channels arvo on 3, silloin myyntilaskukanava on ON ja ostolaskukanava on ON (molemmat auki). Jos ostolaskukanava on kiinni (OFF = arvo 0 tai 1), silloin verkkolaskun lähettäjän operaattori saa automaattisesti virheilmoituksen (negatiivinen ACK -sanoma), että vastaanottajalle ei voida toimittaa verkkolaskua.

	
URL: https://<palveluosoite>/customers?search=Yritys%20%Software%20%Oy

Palaute:

{
    "version": "1.01",
    "identifier": "1234567-8",
    "name": "Yritys Software Oy",
    "vat_identifier": "1234567-8",
    "edi_identifier": "003712345678",
    "free_text": "Vapaata lisätietoa",
    "open_invoice_channels": "3"
}

Haetaan asiakkaan tiedot asiakastunnuksella.

GET palveluosoite/customers/<customer_identifier>

Parametrit

url customer_identifier Asiakastunnus.

Palautettava tietorakenne (asiakkaan tiedot lukuunottamatta salasanaa)

CustomerItemRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Asiakkaan tunniste.
name	string	Asiakkaan nimi.
vat_identifier	string	Asiakkaan y-tunnus.
edi_identifier	string	Asiakkaan OVT-tunnus.
eaddress_send	boolean	Laskun lähetystieto verkkolaskuosoitteistoon
eaddress_receive	boolean	Laskun vastaanottotieto verkkolaskuosoitteistoon
free_text	string	Vapaata tekstiä.
open_invoice_channels	string	• Jos open_invoice_channels arvo on 0, silloin myyntilaskukanava on OFF ja ostolaskukanava on OFF (molemmat kiinni). • Jos open_invoice_channels arvo on 1, silloin myyntilaskukanava on ON ja ostolaskukanava on OFF. • Jos open_invoice_channels arvo on 2, silloin myyntilaskukanava on OFF ja ostolaskukanava on ON. • Jos open_invoice_channels arvo on 3, silloin myyntilaskukanava on ON ja ostolaskukanava on ON (molemmat auki). Jos ostolaskukanava on kiinni (OFF = arvo 0 tai 1), silloin verkkolaskun lähettäjän operaattori saa automaattisesti virheilmoituksen (negatiivinen ACK -sanoma), että vastaanottajalle ei voida toimittaa verkkolaskua.

	
	URL: https://<palveluosoite>/customers/1234567-8

	Palaute:
	

	{
		"version": "1.01",
		"identifier": "1234567-8",
		"name": "Yritys Software Oy",
		"vat_identifier": "1234567-8",
		"edi_identifier": "003712345678",
		"eaddress_send": true,
		"eaddress_receive": true,	
		"free_text": "Vapaata lisätietoa"	
		"open_invoice_channels": "3",
		"address": {
			"street": [
				"Valtatie 66",
				null,
				null
			],
			"zipcode": "09100",
			"city": "Kalihvornia",
			"district": "Pirkanmaa",
			"country": "Finland",
			"phone": "044-7660001"
		}
	}

Luo uuden asiakkaan tai päivittää asiakkaan tiedot.

POST palveluosoite/customers/<customer_identifier>

Parametrit

url customer_identifier Asiakastunnus.Jos ei annettu, yritetään luoda asiakas, muutoin koitetaan päivittää asiakkaan tiedot.

body CustomerRecord Asiakkaan tiedot. Päivitettäessä asiakastunnuksen on täsmättävä url-parametrissa annetun tunnuksen kanssa.

Lähetettävä tietorakenne

CustomerRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Asiakkaan tunniste (asiakkaan/HUBin ohjelmistossa, yleensä Y-tunnus).
name	string	Asiakkaan nimi.
vat_identifier	string	Asiakkaan y-tunnus
edi_identifier	string	Asiakkaan OVT-tunnus
eaddress_send	boolean	Laskun lähetystieto verkkolaskuosoitteistoon
eaddress_receive	boolean	Laskun vastaanottotieto verkkolaskuosoitteistoon
open_invoice_channels	string	• Jos open_invoice_channels arvo on 0, silloin myyntilaskukanava on OFF ja ostolaskukanava on OFF (molemmat kiinni). • Jos open_invoice_channels arvo on 1, silloin myyntilaskukanava on ON ja ostolaskukanava on OFF. • Jos open_invoice_channels arvo on 2, silloin myyntilaskukanava on OFF ja ostolaskukanava on ON. • Jos open_invoice_channels arvo on 3, silloin myyntilaskukanava on ON ja ostolaskukanava on ON (molemmat auki). Jos ostolaskukanava on kiinni (OFF = arvo 0 tai 1), silloin verkkolaskun lähettäjän operaattori saa automaattisesti virheilmoituksen (negatiivinen ACK -sanoma), että vastaanottajalle ei voida toimittaa verkkolaskua.
secret	string	Asiakkaan salasana. Kenttää käytetään vain asiakastietojen päivityksissä Mekanismin avulla NetAPI käyttäjä voi tarjota asiakkuuksilleen asiakastunnukseen kytketyn salasanan halutessaan.
address	CustomerRecord.Address	Osoite (katso rakenne alla)
contact	CustomerRecord.Contact	Kontaktitiedot (katso rakenne alla)
support	CustomerRecord.Support	Tuen kontaktitiedot (katso rakenne alla)
free_text	string	Vapaata tekstiä

CustomerRecord.Address

Asiakastiedot

CustomerRecord.Address

Kenttä	Tyyppi	Kuvaus
street	[string]	Katuosoite. 1-4 riviä
zipcode	string	Postinumero
city	string	Kaupunki
district	string	Lääni
country	string	Maa
phone	string	Puhelin

CustomerRecord.Contact

Asiakastiedot

CustomerRecord.Address

Kenttä	Tyyppi	Kuvaus
street	[string]	Katuosoite. 1-4 riviä
zipcode	string	Postinumero
city	string	Kaupunki
district	string	Lääni
country	string	Maa
phone	string	Puhelin

CustomerRecord.Support

Asiakastiedot

CustomerRecord.Support

Kenttä	Tyyppi	Kuvaus
email	string	Sähköpostiosoite

	

URL: https://<palveluosoite>/customers/1234567-8

body:

{
	"version":"1.01",
	"identifier":"1234567-8",
	"name": "Yritys Software Oy",
	"vat_identifier": "1234567-8",
	"edi_identifier": "003712345678",
	"secret": "valinnainen",
	"eaddress_send": "true",
	"eaddress_receive": "false",
	"free_text": "Tuki klo 09-13",	
	"open_invoice_channels": "1",
	
	"address": 	[
		{
			"street": "Yrityksen nimi",
			"zipcode": "01-01-2018",
			"city": "31-12-2080",
			"district": false,
			"country": "Finland",
			"phone": "040123456789"
		}
	],
	"contact":	[
		{
			"first_name": "Matti",
			"middle_name": "Masi",
			"surname": "Meikäläinen",
			"phone": "0401234567",
			"email": "[email protected]"
			
		}
	],
	"support":	[
		{
			"email": "[email protected]"
		}
	]
	
	
}

SANOMAT

Haetaan tietoa saatavilla olevista sanomista

GET palveluosoite/messages/available

Parametrit

Ei parametreja

Saapuva tietorakenne

IncomingInfo

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
items	int	Saapuvien sanomatiedostojen lukumäärä
details	[IncomingInfo.Details]	Saapuvista sanomista erittelytietoa (katso alla)

IncomingInfo.Details

Sanomatiedot

IncomingInfo.Details

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
items	int	Saapuvien sanomatiedostojen lukumäärä
details	[IncomingInfo.Details]	Saapuvista erittelytietoa

IncomingInfo.Details.Item

Sanomatiedot

IncomingInfo.Details.Item

Kenttä	Tyyppi	Kuvaus
messages	int	Saapuvat sanomat
acks	int	Saapuvat ok-kuittaukset
errors	int	Saapuvat virhekuittaukset

	
URL: https://<palveluosoite>/messages/available

Palaute:

{
    "version": "1.01",
    "items": 12
    "details": [
        {
            "receiver": "003702823456",
            "name": "Yritys Liikenne Ky",
            "items": {
                "messages": "12",  
                "acks": "11",
                "errors": "1"
            }
        }
    ]
}

Haetaan otsikkotiedot luettelona saatavilla olevista sanomista

GET palveluosoite/messages/headers

Parametrit

Ei parametreja

Saapuva tietorakenne

IncomingInfo

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
items	int	Saapuvien sanomatiedostojen lukumäärä
details	[IncomingInfo.Details]	Saapuvista sanomista erittelytietoa (katso alla)

IncomingInfo.Sender

Sanomatiedot

IncomingInfo.Sender

Kenttä	Tyyppi	Kuvaus
address	string	Verkkolaskuosoite
intermediator	string	Välittäjän tunniste/osoite
name	string	Lähettäjän toiminimi
messageid	int	Netbox sanoma id
timestamp	datetime	Aikaleima

IncomingInfo.Receiver

Sanomatiedot

IncomingInfo.Details.Item

Kenttä	Tyyppi	Kuvaus
address	string	Verkkolaskuosoite
intermediator	string	Välittäjän tunniste/osoite
name	string	Vastaanottajan toiminimi

	
URL: https://<palveluosoite>/messages/headers

Palaute:

[
    {
        "messageid": "1036",
        "type": invoice,
        "original_filename": "kollektor-Koll_20180410055506_0001",
        "handled": "2018-05-04 12:11:17",
        "sender": {
            "address": "14756079",
            "intermediator": "KOLLEKTORSCAN",
            "name": "Laskuttaja Lex Oy",
            "messageid": "75856097",
            "timestamp": "2018-04-08T13:40:00+0000"
        },
        "receiver": {
            "address": "003724563330",
            "intermediator": "003726044706",
            "name": "CRM House Oy"
        }
    }

Haetaan otsikkotiedot luettelona saatavilla olevista sanomista sanomatyypin mukaan

GET palveluosoite/messages/headers/<type>

Parametrit

url type Valinnainen rajaus haluttuun sanomatyyppin. Sanomatyypit löytyvät MessageData –rakenteen kuvauksen yhteydessä.

Saapuva tietorakenne

IncomingInfo

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
items	int	Saapuvien sanomatiedostojen lukumäärä
details	[IncomingInfo.Details]	Saapuvista sanomista erittelytietoa (katso alla)

IncomingInfo.Sender

Sanomatiedot

IncomingInfo.Sender

Kenttä	Tyyppi	Kuvaus
address	string	Verkkolaskuosoite
intermediator	string	Välittäjän tunniste/osoite
name	string	Lähettäjän toiminimi
messageid	int	Netbox sanoma id
timestamp	datetime	Aikaleima

IncomingInfo.Receiver

Sanomatiedot

IncomingInfo.Details.Item

Kenttä	Tyyppi	Kuvaus
address	string	Verkkolaskuosoite
intermediator	string	Välittäjän tunniste/osoite
name	string	Vastaanottajan toiminimi

	
URL: https://<palveluosoite>/messages/headers/invoice

Palaute:

[
    {
        "messageid": "1036",
        "type": invoice,
        "original_filename": "kollektor-Koll_20180410055506_0001",
        "handled": "2018-05-04 12:11:17",
        "sender": {
            "address": "14756079",
            "intermediator": "KOLLEKTORSCAN",
            "name": "Laskuttaja Lex Oy",
            "messageid": "75856097",
            "timestamp": "2018-04-08T13:40:00+0000"
        },
        "receiver": {
            "address": "003724563330",
            "intermediator": "003726044706",
            "name": "CRM House Oy"
        }
    }

Haetaan seuraava saatavilla olevan sanoma tai sen osa (jonohaku)

GET palveluosoite/messages/<type>

Sanomat tulevat fifo:n mukaan, eli vanhin sanoma ensin.

Parametrit

url type Valinnainen rajaus haluttuun sanomatyyppin. Sanomatyypit löytyvät MessageData –rakenteen kuvauksen yhteydessä.

Palautettava tietorakenne (Sanoman tiedot)

MessageData

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Sanoman tunniste
type	enum	Sanoman tyyppi
datafiles	[MessageData.DataFile]	Sanoman tiedostot (katso alla)

MessageData.DataFile

Sanomatiedot

MessageData.DataFile

Kenttä	Tyyppi	Kuvaus
filename	string	Tiedoston nimi
compressed	int	true, jos data on gzip-pakattu ennen base64 enkoodausta.
data	base64data	Tiedoston data base64-koodattuna binäärimassana.
filesize	int	Tiedoston alkuperäinen koko.
filetime	date-time	Tiedoston viimeisin muutosaika.

Sanoman tyypit ovat:

Tyyppi	Kuvaus
invoice	Verkkolasku
ack	Verkkolasku ok tai virhekuittaus
bankstmt	CAMT053-muotoinen pankkitiliote
bankrefp	CAMT054-muotoinen viitemaksu

	
URL: https://<palveluosoite>/messages

Palaute:

	{
		"version": "1.01",
		"identifier": "xml",
		"type": "ack",
		"datafiles":	
		[
			{
				"data":"PFNPQVAtRU5WOkVudmV...2b2ljZWFjaz4K",
				"filename":"ERR-171219150010860-52.xml",
				"filesize":3684,
				"filetime":"2017-12-19T15:03:55+0200",
				"sha1":"d0357bd3543d322eb26cf04c8bc4094956390881"
			}
		]
	}

Haetaan tietty sanoma tunnisteella

GET palveluosoite/messages/id/<id>

Haku ei poista sanomaa sanoma jonosta, vaan on edelleen noudettavsissa jonohaulla.

Parametrit

url id Tietyn sanoman sanomatunniste. Sanomatunnisteen voit noutaa /headers/ - kutsulla.

Palautettava tietorakenne (Sanoman tiedot)

MessageData

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Sanoman tunniste
type	enum	Sanoman tyyppi
datafiles	[MessageData.DataFile]	Sanoman tiedostot (katso alla)

MessageData.DataFile

Sanomatiedot

MessageData.DataFile

Kenttä	Tyyppi	Kuvaus
filename	string	Tiedoston nimi
compressed	int	true, jos data on gzip-pakattu ennen base64 enkoodausta.
data	base64data	Tiedoston data base64-koodattuna binäärimassana.
filesize	int	Tiedoston alkuperäinen koko.
filetime	date-time	Tiedoston viimeisin muutosaika.

Sanoman tyypit ovat:

Tyyppi	Kuvaus
invoice	Verkkolasku
ack	Verkkolasku ok tai virhekuittaus
bankstmt	CAMT053-muotoinen pankkitiliote
bankrefp	CAMT054-muotoinen viitemaksu

	
URL: https://<palveluosoite>/id/123456

Palaute:

	{
		"version": "1.01",
		"identifier": "1043",
		"type": "ack",
		"datafiles":	
		[
			{
				"data":"PFNPQVAtRU5WOkVudmV...2b2ljZWFjaz4K",
				"filename":"ERR-171219150010860-52.xml",
				"filesize":3684,
				"filetime":"2017-12-19T15:03:55+0200",
				"sha1":"d0357bd3543d322eb26cf04c8bc4094956390881"
			}
		]
	}

LÄHETETÄÄN SANOMA TAI SEN OSA

POST palveluosoite/messages

Sanoma suositellaan lähetettävän kokonaisuudessaan ZIP-tiedostona. Tiedostot voidaan lähettää myös erikseen, joka yhtenä palvelukutsuna tai erillisinä palvelukutsuina. Sanomatunniste on viitteellinen tieto. Erillisiä tiedostoja ei kytketä sanomaan sanomatunnisteen avulla, vaan ainoastaan sisältöjen perusteella. Sanomatunnisteen tulee olla pysyvästi yksikäsitteinen. Tiedostojen nimien tulee olla yksikäsitteisiä 6kk ajan.

Parametrit

url type Valinnainen rajaus haluttuun sanomatyyppin.

Lähetettävä tietorakenne (Sanoman tiedot)

MessageData

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Sanoman tunniste
type	enum	Sanoman tyyppi
datafiles	[MessageData.DataFile]	Sanoman tiedostot (katso yllä)

Lähetetään sanoma uudelleen (resend)

POST palveluosoite/messages

Jo lähetetyn sanoman esim. laskun "resend".

Parametrit

url type Valinnainen rajaus haluttuun sanomatyyppin.

Lähetettävä tietorakenne (Sanoman tiedot)

MessageData

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
identifier	string	Sanoman tunniste
type	enum	Sanoman tyyppi
datafiles	[MessageData.DataFile]	Sanoman tiedostot (katso yllä)

MessageData.DataFile

Sanomatiedot

MessageData.DataFile

Kenttä	Tyyppi	Kuvaus
filename	string	Tiedoston nimi
compressed	int	true, jos data on gzip-pakattu ennen base64 enkoodausta.
data	base64data	Tiedoston data base64-koodattuna binäärimassana.
filesize	int	Tiedoston alkuperäinen koko.
filetime	date-time	Tiedoston viimeisin muutosaika.

Sanoman tyypit ovat:

Tyyppi	Kuvaus
invoice	Verkkolasku
ack	Verkkolasku ok tai virhekuittaus
bankstmt	CAMT053-muotoinen pankkitiliote
bankrefp	CAMT054-muotoinen viitemaksu

MessageData.Resend

Sanomatiedot

Resend.Receiver

Kenttä	Tyyppi	Kuvaus
address	string	Vastaanottojan verkkolaskuosoite
intermediator	string	Vastaanottajan operaattorin välittäjätunnus

Resend.Sender

Kenttä	Tyyppi	Kuvaus
address	string	Lähettäjän verkkolaskuosoite
intermediator	string	Lähettäjän operaattorin välittäjätunnus (Netbox: 003726044706)
messageid	string	Lähettäjän sanomatunniste/id (Finvoice sanomassa <MessageId>)

MessageData.Type

Kenttä	Tyyppi	Kuvaus
type	string	Sanomatyyppi (tyypit lueteltu MessageData.DataFile osiossa)

	
URL: https://<palveluosoite>/messages

Body:

{
    "datafiles": [
        {
            "data": "...base64_encode...",
            "filename": "invoice_543_1234567890.xml",
            "filesize": 1122
        },
        {
            "data": "...base64_encode...",
            "filename": "invoice_543_1234567890.pdf",
            "filesize": 10022
        }
    ],
    "resend": {
        "receiver": {
            "address": "receiver_eaddress",
            "intermediator": "receiver_intermediator_address"
        },
        "sender": {
            "address": "sender_eaddress",
            "intermediator": "sender_intermediator_address",
            "messageid": "sender_message_id"
        }
    },
    "type": "invoice"
}

YRITYSTIEDOT

Haetaan yrityksen julkisia tietoja y-tunnuksella

GET palveluosoite/companies/<vat_identifier>

Parametrit

url vat_identifier Yrityksen y-tunnus

Palautettava tietorakenne (Yrityksen tiedot)

CompanyRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"
vat_identifier	string	Yrityksen y-tunnus
names	[CompanyRecord.Name]	Yrityksen nimitiedot (katso alla)
addresses	[CompanyRecord.Address]	Yrityksen osoitetiedot (katso alla)
eaddresses	[CompanyRecord.Eaddress]	Yrityksen sähköiset osoitetiedot (katso alla)

CompanyRecord.Name

Yritystiedot

CompanyRecord.Name

Kenttä	Tyyppi	Kuvaus
name	string	Yrityksen nimi
start_date	date	Nimen voimaantulopäivä
end_date	date	Nimen viimeinen voimassaolopäivä
aux	boolean	true, jos kyseessä on aputoiminimi

CompanyRecord.Address

Osoitetiedot

CompanyRecord.Address

Kenttä	Tyyppi	Kuvaus
street	[string]	Katuosoite. 1-4 riviä
zipcode	string	Postinumero
city	string	Kaupunki
country	string	Maa
start_date	date	Osoitteen voimaantulopäivä
end_date	date	Osoitteen viimeinen voimassaolopäivä
eaddress_id_type	string
eaddress_id_value	string
eaddress_service
type	string	Osoitteen tyyppi. Postal tai visiting

CompanyRecord.Eaddress

Verkkolaskutuksen osoitetiedot

CompanyRecord.Eaddress

Kenttä	Tyyppi	Kuvaus
type	string	Osoitteen tyyppi. Tyypit ilmaistaan soveltaen Eaddress v1.12 määrittelyn mukaisia: ovt vatid businessid gln duns peppol mutual other iban bic ibusinessid
context	string	Osoitteen konteksti. Kontekstit ilmaistaan soveltaen Eaddress v1.12 määrittelyn mukaisesti: einvoice orders ordrsp pricat desadv other
direction	string	Suunta. Suunnat ilmaistaan soveltaen Eaddress v1.12 määrittelyn mukaisesti: send receive
address	string	Osoite
service_type	string	Palvelun tyyppi
service_identifier	string	Palvelun tunnus

	
URL: https://<palveluosoite>/companies/1234567-8

Palaute:

{
    "version": "1.01",
    "vat_identifier": "2604470-6",
    "names": [
        {
            "name": "Netbox Finland Oy",
            "start_date": "2014-03-04",
            "end_date": "",
            "aux": "false"
        }
    ],
    "addresses": [
        {
            "street": "Rautatienkatu 21",
            "zipcode": "33100",
            "city": "TAMPERE",
            "country": "",
            "type": "postal",
            "start_date": "2018-02-17",
            "end_date": ""
        },
        {
            "street": "Rautatienkatu 21",
            "zipcode": "33100",
            "city": "TAMPERE",
            "country": "",
            "type": "visiting",
            "start_date": "2018-02-17",
            "end_date": ""
        }
    ],
    "eaddresses": [
        {
            "type": "ovt",
            "context": "einvoice",
            "direction": "send",
            "address": "003726044706",
            "service_type": "ovt",
            "service_identifier": "003726044706"
        },
        {
            "type": "ovt",
            "context": "einvoice",
            "direction": "receive",
            "address": "003726044706",
            "service_type": "ovt",
            "service_identifier": "003726044706"
        }
    ]
}

Haetaan yrityksen julkisia tietoja toiminimellä

GET palveluosoite/companies?search=<company_name>

Hakusana(t) tulee olla enkoodattu esim. PHP:ssä urlencode($hakusana);

Parametrit

url ?search= Yrityksen nimi tai osa nimestä. Haku on "case insensitive".

Palautettava tietorakenne (Yrityksen tiedot)

CompanyRecord

Kenttä	Tyyppi	Kuvaus
version	string	rakenteen versio:"1.01"

CompanyRecord.Results

Yritystiedot

CompanyRecord.Results

Kenttä	Tyyppi	Kuvaus
vat_identifier	string	Y-tunnus
name	string	Yrityksen nimi
street	string	Katuosoite
zipcode	int	Postinumero
city	string	Kaupunki
domicile	string	Lääni

	
URL: https://<palveluosoite>/companies?search=netbox%20%finland

Palaute:

{
    "version": "1.01",
    "results": [
        {
            "vat_identifier": "2604470-6",
            "name": "Netbox Finland Oy",
            "street": "Rautatienkatu 21  ",
            "zipcode": "33100",
            "city": "TAMPERE",
            "domicile": "TAMPERE"
        },
        {
            "vat_identifier": "1306336-9",
            "name": "Tmi Netbox",
            "street": "   ",
            "zipcode": null,
            "city": null,
            "domicile": "PAIMIO"
        },
        {
            "vat_identifier": "2938504-7",
            "name": "NETBOX PL SP. Z O.O.",
            "street": "   ",
            "zipcode": null,
            "city": null,
            "domicile": "ULKOMAAT"
        }
    ]
}

	url	username	NetAPI käyttäjätunnus
	url	customer identifier	NetAPI käyttäjätunnukseen kytketty asiakastunnus

	url	customer_identifier	Asiakastunnus.Jos ei annettu, yritetään luoda asiakas, muutoin koitetaan päivittää asiakkaan tiedot.
	body	CustomerRecord	Asiakkaan tiedot. Päivitettäessä asiakastunnuksen on täsmättävä url-parametrissa annetun tunnuksen kanssa.

Dashboards

Netbox palveluiden ohjeita

GET palveluosoite/tickets/<username>[/<customer_identifier>]

urlusernameNetAPI käyttäjätunnus urlcustomer identifierNetAPI käyttäjätunnukseen kytketty asiakastunnus

TicketRecord

GET palveluosoite/tokens/<secured_hash>

urlsecured_hashHeksadesimaalinen sha1-tuottama varmennettu tiiviste peräkkäin yhteenliitetystä salasanasta ja tiketistä.

TokenRecord

Authorization: Bearer <käyttöoikeustietue>

GET palveluosoite/customers?search=<pattern>

urlpatternHakutekijäVoit käyttää %-merkkiä, esim. Yritysnim%, hakee kaikki asiakkaat, joiden nimi alkaa "Yritysnim" -sanalla.

CustomerItemRecord

GET palveluosoite/customers/<customer_identifier>

urlcustomer_identifierAsiakastunnus.

CustomerItemRecord

POST palveluosoite/customers/<customer_identifier>

urlcustomer_identifierAsiakastunnus.Jos ei annettu, yritetään luoda asiakas, muutoin koitetaan päivittää asiakkaan tiedot. bodyCustomerRecordAsiakkaan tiedot. Päivitettäessä asiakastunnuksen on täsmättävä url-parametrissa annetun tunnuksen kanssa.

CustomerRecord

CustomerRecord.Address

CustomerRecord.Address

CustomerRecord.Support

GET palveluosoite/messages/available

Ei parametreja

IncomingInfo

IncomingInfo.Details

IncomingInfo.Details.Item

GET palveluosoite/messages/headers

Ei parametreja

IncomingInfo

IncomingInfo.Sender

IncomingInfo.Details.Item

GET palveluosoite/messages/headers/<type>

urltypeValinnainen rajaus haluttuun sanomatyyppin. Sanomatyypit löytyvät MessageData –rakenteen kuvauksen yhteydessä.

IncomingInfo

IncomingInfo.Sender

IncomingInfo.Details.Item

GET palveluosoite/messages/<type>

urltypeValinnainen rajaus haluttuun sanomatyyppin. Sanomatyypit löytyvät MessageData –rakenteen kuvauksen yhteydessä.

MessageData

MessageData.DataFile

Sanoman tyypit ovat:

GET palveluosoite/messages/id/<id>

urlidTietyn sanoman sanomatunniste. Sanomatunnisteen voit noutaa /headers/ - kutsulla.

MessageData

MessageData.DataFile

Sanoman tyypit ovat:

POST palveluosoite/messages

urltypeValinnainen rajaus haluttuun sanomatyyppin.

MessageData

POST palveluosoite/messages

urltypeValinnainen rajaus haluttuun sanomatyyppin.

MessageData

MessageData.DataFile

Sanoman tyypit ovat:

Resend.Receiver

Resend.Sender

MessageData.Type

GET palveluosoite/companies/<vat_identifier>

urlvat_identifierYrityksen y-tunnus

CompanyRecord

CompanyRecord.Name

CompanyRecord.Address

CompanyRecord.Eaddress

GET palveluosoite/companies?search=<company_name>

url?search=Yrityksen nimi tai osa nimestä. Haku on "case insensitive".

CompanyRecord

CompanyRecord.Results

url username NetAPI käyttäjätunnus

url customer identifier NetAPI käyttäjätunnukseen kytketty asiakastunnus

url secured_hash Heksadesimaalinen sha1-tuottama varmennettu tiiviste peräkkäin yhteenliitetystä salasanasta ja tiketistä.

url pattern Hakutekijä
Voit käyttää %-merkkiä, esim. Yritysnim%, hakee kaikki asiakkaat, joiden nimi alkaa "Yritysnim" -sanalla.

url customer_identifier Asiakastunnus.

url customer_identifier Asiakastunnus.Jos ei annettu, yritetään luoda asiakas, muutoin koitetaan päivittää asiakkaan tiedot.

body CustomerRecord Asiakkaan tiedot. Päivitettäessä asiakastunnuksen on täsmättävä url-parametrissa annetun tunnuksen kanssa.

url type Valinnainen rajaus haluttuun sanomatyyppin. Sanomatyypit löytyvät MessageData –rakenteen kuvauksen yhteydessä.

url type Valinnainen rajaus haluttuun sanomatyyppin. Sanomatyypit löytyvät MessageData –rakenteen kuvauksen yhteydessä.

url id Tietyn sanoman sanomatunniste. Sanomatunnisteen voit noutaa /headers/ - kutsulla.

url type Valinnainen rajaus haluttuun sanomatyyppin.

url type Valinnainen rajaus haluttuun sanomatyyppin.

url vat_identifier Yrityksen y-tunnus

url ?search= Yrityksen nimi tai osa nimestä. Haku on "case insensitive".