Kontaktmetod
Netvisors Web Service-programgränssnitt är REST-baserat. Kommunikation mellan klientprogrammet och tjänsten sker med HTTP-anrop. Gränssnittet är tvåvägs och transaktionsbaserat.
Vid import av data skapar det sändande systemet ett XML-meddelande som beskriver materialet och skickar det ovanpå ett HTTP-anrop till Netvisor. Den valda resursen definierar typen av integrationstransaktion. I vissa transaktioner får användaren identifieringsuppgifter om det tillagda materialet för senare bruk.
Vid export av material från Netvisor behöver inget XML-meddelande skickas i anropet. Anropet riktas till önskad resurs och avgränsas vid behov med de parametrar som resursen möjliggör. I svaret presenteras den begärda transaktionen för användaren i XML-format.
Alla svar som gränssnittet skickar är i XML-format och innehåller alltid elementet ResponseStatus, utifrån vilket man kan tolka om anropet lyckades. Vid fel förmedlas också en felförklaring och feltyp. I ett lyckat svar är standardvärdet ”OK” inne i elementet Status och i ett felaktigt svar är standardvärdet ”FAILED”. För felsituationer, se separat anvisning för hantering av felsituationer.
Exempelsvar på ett lyckat anrop:
OK
01.01.2018 12:00:00
1802
Datasäkerhet och autentisering
Programgränssnittets datasäkerhet har implementerats på två olika sätt:
1. Krypterad förbindelse
Kommunikation till gränssnittets produktions- och testmiljö sker via krypterade förbindelser (HTTPS).
2. Enkelriktad kryptering av autentiseringsuppgifter
Autentiseringsuppgifterna som skickas till gränssnittet krypteras genom att skapa en kontrollsumma av dem, från vilken de ursprungliga uppgifterna inte kan återskapas.
Användning och konfiguration av proxy
När du konfigurerar en proxy för användning med Netvisors integrationstjänster, säkerställ att följande inställningar används:
Ersätt $host med adressen integration.netvisor.fi.
Direktivet proxy_ssl_server_name on; är obligatoriskt.
proxy_set_header Host integration.netvisor.fi;
proxy_ssl_server_name on;
HMACSHA256-autentisering
Netvisors gränssnitt stöder från och med maj 2025 HMACSHA256-autentisering. Nya integrationer ska implementeras enligt denna autentisering.
Datasäkerheten i Netvisors gränssnitt säkerställs både med programgränssnittskoder och med en identifierare som är unik för varje anrop.
För att data ska kunna överföras via Netvisors gränssnitt behövs:
Användarens programgränssnittskoder (användaridentifierare id och nyckel). Användarens programgränssnittskoder skapas i Netvisor: https://support.netvisor.fi/sv/articles/766837-skapa-programvarugranssnittstoken
Programvarupartnerns gränssnittskoder (partner-id och nyckel). Programvarupartnerns gränssnittskoder levereras till partnern av kundtjänsten.
När anrop skickas till Netvisors gränssnitt ska de identifieringsuppgifter som listas i bilden synas i varje anrop. HMACSHA256-värdet beräknas med alla uppgifter som listas till höger i bilden. I rubrikerna för anrop som skickas till gränssnittet ingår inte de unika nycklarna för programvarupartnern och användaren, men de behövs för HMACSHA256-beräkning. Anropets korrekthet verifieras i gränssnittet med en MAC-identifierare som skapas med HMACSHA256-beräkning. MAC-identifieraren beräknas separat för varje anrop som skickas till gränssnittet. Om ett anrop med samma transaktionsidentifierare har skickats tidigare till gränssnittet returnerar gränssnittet ett fel.
HTTP-rubriker för autentisering med förklaringar
HTTP Headers
'X-Netvisor-Authentication-Sender'
'X-Netvisor-Authentication-CustomerId'
'X-Netvisor-Authentication-PartnerId'
'X-Netvisor-Authentication-TimestampUnix'
'X-Netvisor-Authentication-Timestamp'
'X-Netvisor-Authentication-TransactionId'
'X-Netvisor-Interface-Language'
'X-Netvisor-Organisation-ID'
'X-Netvisor-Authentication-MAC'
'X-Netvisor-Authentication-MACHashCalculationAlgorithm': HMACSHA256
‘X-Netvisor-Authentication-UseHTTPResponseStatusCodes’: 1
Alla rubriker ska vara av typen string
X-Netvisor-Authentication-Sender
Fritt formulerat namn på integrationen. Om partnern har flera system kopplade till Netvisor ska varje integration namnges entydigt. Denna uppgift underlättar Netvisors support och teknik vid felsökning.
X-Netvisor-Authentication-CustomerId
Kundföretagets användares programgränssnittskoder. Detta är en användarspecifik kod.
I testmiljön skapas programgränssnittskoder av programvarupartnerns arbetstagare
I produktion skapas koden av Netvisor-användaren i det företag som tar integrationen i bruk. Hen levererar den skapade gränssnittskoden och integrationsanvändarens unika nyckel till den som implementerar integrationen eller lägger själv in koderna i integrationens inställningar.
Instruktioner för att skapa programgränssnittskoder: https://support.netvisor.fi/sv/articles/766837-skapa-programvarugranssnittstoken
X-Netvisor-Authentication-PartnerId
Partnerkod. Netvisors support skapar en kod och nyckel för partnern per integration. Koderna levereras till partnern per e-post. Om partnern har flera system kopplade till Netvisor skapas separata partnerkoder för varje integration.
X-Netvisor-Authentication-Timestamp
Tidsstämpel för integrationsanropet i ansi-format med klockslag, GMT+0. T.ex. 2023-05-04 12:00:00.000
X-Netvisor-Authentication-TimestampUnix
Tidsstämpel för anropet i UNIX-format i UTC-tid. Med andra ord antalet sekunder som förflutit efter 1. januari 1970. Till exempel 1744635366.
X-Netvisor-Interface-Language
Språkuppgift till gränssnittet. Språkstöd för svarsmeddelanden, vilket främst påverkar felmeddelanden. Uppgiften ska vara i ISO-3166-format. Språkalternativen är FI/SE/EN.
X-Netvisor-Organisation-ID
Målbolagets fo-nummer. Fo-nummer avgör vilket företag anropen registreras på eller vars uppgifter hämtas. Netvisor-användaren i företaget vars programgränssnittskoder används i integrationen måste ha rättigheter till detta företag.
X-Netvisor-Authentication-TransactionId
Unik identifierare för anropet, GUID (Globally Unique Identifier). Värdet ska vara olika i varje anrop. Om material tidigare har skickats med samma identifierare avvisas anropet och felet REQUEST_NOT_UNIQUE returneras. Identifieraren kontrolleras på partnerkodnivå, dvs. samma identifierare kan inte användas för olika kunder.
X-Netvisor-Authentication-UseHTTPResponseStatusCodes
Möjliggör användning av korrekta statuskoder i gränssnittets svar. Värdet ska vara 1.
X-Netvisor-Authentication-MACHashCalculationAlgorithm
För att gränssnittet ska ta emot en HMACSHA-256-hash måste uppgiften ges i rubrikerna. Värdet ska vara HMACSHA256.
X-Netvisor-Authentication-MAC
Med MAC-koden verifieras avsändaren av anropet. Vid beräkningen av koden används alla ovan nämnda HTTP-rubriker samt den unika nyckeln som levererats till integrationspartnern och den unika nyckeln för användarens programgränssnittskoder. Nycklarna levereras dock inte i HTTP-rubrikerna. De används enbart för beräkning och kontroll av MAC-koden. MAC-koden bildas genom att kombinera uppgifterna i tabellen nedan till en enda teckensträng som måste vara exakt i den ordning som anges i dokumentationen nedan. Från denna teckensträng beräknas HMACSHA256-kontrollsumman. När uppgifterna kombineras används tecknet & mellan uppgifterna; URI-delen måste vara densamma som den adress dit anropet skickas, inklusive stora och små bokstäver.
HTTP header | Värde |
Uri (dit anropet skickas) | https://isvapi.netvisor.fi/accounting.nv |
X-Netvisor-Authentication-Sender | ClientName |
X-Netvisor-Authentication-CustomerId | Integration user identifier |
X-Netvisor-Authentication-TimeStamp | 2023-05-04 12:00:00.000 |
X-Netvisor-Interface-Language | FI |
X-Netvisor-Organisation-ID | 1967543-8 |
X-Netvisor-Authentication-TransactionId | 123456 |
X-Netvisor-Authentication-TimestampUnix | 1683147600 |
Unik nyckel för integrationsanvändaren (userkey) | 7CD680E89E880553358BC07CD28B0EE2 |
Unik nyckel för integrationspartnern (partnerkey) | 7F94228D149A96B2F25E3EDAD55096E |
Teckensträng bildad av uppgifterna:
https://isvapi.netvisor.fi/accounting.nv&ClientName&Integration user identifier&2023-05-04 12:00:00.000&FI&1967543-8&123456&1683147600&7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E
Dessutom bildas parametern secrets av den unika nyckeln för integrationsanvändaren och den unika nyckeln för integrationspartnern:
7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E
Genom att beräkna HMACSHA256-kontrollsumman av teckensträngarna fås följande MAC-kod:
e920b92df2be6668b283fc03041c6aea09cdb2bf42a72d814131bb811a0e926e
OBS! Om den teckensträng som används för MAC-beräkningen innehåller specialtecken eller nordiska tecken ska den kodas med teckenuppsättningen ISO-8859-15.
Vanligaste felsituationerna:
PHP-exempel
PHP-exempel för att skapa MAC-kod och HTTP-rubriker:
url, $this->sender, $this->customerId, $this->timestamp, $this->language, $this->organisationId, $this->transactionId, $this->timestampUnix, $this->customerKey, $this->partnerKey ); $key = array( $this->customerKey, $this->partnerKey ); $key = array_map("strval", $key); $parameters = array_map("strval", $parameters); return hash_hmac("sha256", implode("&", $parameters), implode("&", $key)); } #HTTP headers: public function get_authentication_headers() { $headers = array( "X-Netvisor-Authentication-Sender:" . $this->sender, "X-Netvisor-Authentication-CustomerId:" . $this->customerId, "X-Netvisor-Authentication-PartnerId:" . $this->partnerId, "X-Netvisor-Authentication-Timestamp:" . $this->timestamp, "X-Netvisor-Authentication-TimestampUnix:" . $this->timestampUnix, "X-Netvisor-Authentication-TransactionId:" . $this->transactionId, "X-Netvisor-Interface-Language:" . $this->language, "X-Netvisor-Organisation-ID:" . $this->organisationId, "X-Netvisor-Authentication-UseHTTPResponseStatusCodes: 1", "X-Netvisor-Authentication-MAC:" . $this->mac, "X-Netvisor-Authentication-MACHashCalculationAlgorithm: HMACSHA256", ); return $headers; } }$mac = new MACCalculation();$mac->url = "https://isvapi.netvisor.fi/accounting.nv";$mac->sender = "ClientName";$mac->customerId = "Integration user identifier";$mac->timestamp = "2023-05-04 12:00:00.000";$mac->language = "FI";$mac->organisationId = "1967543-8";$mac->transactionId = "123456";$mac->timestampUnix = 1683147600;$mac->customerKey = "7cd680e89e880553358bc07cd28b0ee2";$mac->partnerKey = "7f94228d149a96b2f25e3edad55096e";echo $mac->get_MAC();?>
Python-exempel
Python-exempel för att skapa MAC-kod och HTTP-rubriker:
import hashlibimport randomimport timeimport requestsimport hmac# headersSender= "ClientName"PartnerId = "Partner identifier"PartnerKey = "7f94228d149a96b2f25e3edad55096e"CustomerID = "Integration user identifier"CustomerKey = "7cd680e89e880553358bc07cd28b0ee2"timestampUnix = int(time.time())timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())MacHashAlgorithm = "HMACSHA256"Organisationid = "1967543-8"URL = "https://isvapi.netvisor.fi/accounting.nv"Language = "FI"# TransactionID = "TRANSID"+"%0.12d" % random.randint(0,99999999)# compile the string for mac-hashsha256string = URL + "&" + Sender + "&" + CustomerID + "&" + timestamp + "&" + Language + "&" + Organisationid + "&" + TransactionID + "&" + str(timestampUnix) + "&" + CustomerKey + "&" + PartnerKey# encode the string to ISO-8859-15 and perform the sha256-hashkey = CustomerKey + "&" + PartnerKeyh_mac = hmac.new(bytes(key, "ISO-8859-15"), bytes(sha256string, "ISO-8859-15"), hashlib.sha256).hexdigest()print(h_mac)# # HTTP-headers being sent with the requestheaders = { "Content-Type": "text/plain", "X-Netvisor-Authentication-Sender": Sender, "X-Netvisor-Authentication-CustomerId": CustomerID, "X-Netvisor-Authentication-PartnerId": PartnerId, "X-Netvisor-Authentication-Timestamp": timestamp, "X-Netvisor-Authentication-TimestampUnix": str(timestampUnix), "X-Netvisor-Authentication-TransactionId": TransactionID, "X-Netvisor-Interface-Language": Language, "X-Netvisor-Organisation-Id": Organisationid, "X-Netvisor-Authentication-UseHTTPResponseStatusCodes: "1", "X-Netvisor-Authentication-MAC": h_mac, "X-Netvisor-Authentication-MACHashCalculationAlgorithm": MacHashAlgorithm}Denna artikel har översatts med hjälp av ett AI-baserat översättningsverktyg. Innehållet eller formuleringen i dessa instruktioner kan avvika från dem i andra instruktioner eller i programvaran.