Allmänna instruktioner om resurser : Netvisor

INNEHÅLLSFÖRTECKNING

Allmänt
Gränssnittets arkitektur (REST)
Tvåvägs datatransfer
Datasäkerhet och förbindelse
Autentisering
Tolkningsanvisning
Meddelandesvar
Gränssnittets bilagors tillåtna filformat

Allmänt

Netvisors programgränssnitt (API) möjliggör automatisk överföring av data mellan externa system och Netvisor. Gränssnittet är utformat som ett säkert sätt att bygga integrationer. Programgränssnittet tillåter såväl hämtning av material från Netvisor som import av material till Netvisor. Resurserna som erbjuds i gränssnittet är indelade i kategorier på toppnivå.
Gemensamt för alla transaktioner är:

Datumen är i ANSI-format
Landskoder är alltid i ISO 3166-format
Bilagor är alltid Base64-kodade i ett XML-meddelande
Tomma element behöver inte skrivas i ett XML-meddelande, exempelvis tolkas ett tomt element i begäran om uppdatering som en order att uppdatera värdet till tomt
Lämna inte obligatoriska fält tomma
Elementen måste vara i ordning enligt DTD

För att inkludera de skandinaviska bokstäverna (Ä, ä, Ö, ö eller Å, å) i gränssnittet måste meddelandet vara i ISO/IEC 8859-15-kodat format, men en xml-deklaration krävs dock inte. Netvisors serversida gör nödvändig förbearbetning av innehållet, i så fall ska materialet alltid börja med <root>.

Utför stora sökningar och dataöverföringar utanför kontorstid, om det inte finns ett särskilt behov av att överföra dem under kontorstid. Lämplig frekvens för dataöverföring varierar beroende på resurs och användningsfall. I många fall räcker det med en överföring en gång per dag eller en månad. Du kan också påskynda överföringar genom att begränsa dem med hjälp av resursparametrar.

Gränssnittets arkitektur (REST)

Netvisors gränssnitt implementerar REST-modellen (Representational State Transfer). Det är en arkitekturmodell baserad på HTTP-protokollet för att implementera programmeringsgränssnitt.

Funktionsprincip: Förenklat kan alla funktioner utföras med ett meddelande genom att bara ändra HTTP-metoden (t.ex. GET för att hämta data, POST för att importera data).
Resurser: Skillnaden från en ren REST-modell är att Netvisor har en egen resurs för varje metod.
URI-struktur: Gränssnittet har en root-URI, följt av den resurs som ska anropas, exempelvis: https://isvapi.netvisor.fi/salesinvoice.nv

Tvåvägs datatransfer

Netvisors gränssnitt är tvåvägs, vilket innebär att data kan både importeras till systemet och hämtas därifrån.

Meddelandeöverföring: Vid import skickas materialet i XML-format och vid hämtning returneras svaret som ett XML-meddelande.
Svar: Gränssnittet returnerar alltid ett svar som innehåller OK/FAILED status-element.
Funktionssätt: Netvisor är alltid den passiva parten (server) i gränssnittet som svarar på de begäranden som görs till den.
Rekommendation: Begäranden rekommenderas att göras en i taget, väntande på svar mellan varje anrop.

Datasäkerhet och förbindelse

All kommunikation med gränssnittet är skyddad med moderna krypteringstekniker.

Krypterad förbindelse: Kommunikation i både produktions- och testmiljöer sker alltid över en säker HTTPS-förbindelse.
Enkelriktad kryptering av autentiseringsuppgifter: De autentiseringsuppgifter som skickas krypteras genom att skapa en kontrollsumma av dem. Från denna summa kan de ursprungliga uppgifterna inte återställas.

Autentisering

Gränssnittet identifierar varje begäran baserat på informationen i HTTP-headers.

MAC-kod: Autentisering baseras på header-information och den beräknade MAC-koden (Message Authentication Code).
Användning av headers: Korrekt header-information måste skrivas i varje HTTP-begäran.
Felaktiga situationer: Om headers saknas eller är felaktiga returnerar gränssnittet ett felmeddelande om misslyckad autentisering med förklaring (AUTHENTICATION_FAILED).

Tolkningsanvisning

Här beskrivs syftet och tolkningarna av olika markeringar i integrationsgränssnittet.
XML-strukturen för olika meddelanden beskrivs i tabellform på alla punkter i meddelandena där det är möjligt och logiskt. På grund av XML-strukturen har vi exempelvis varit tvungna att använda hänvisningar till olika punkter i anvisningarna för att bevara en tydlig helhet.

Strukturbeskrivningarnas grundstruktur är följande:
Anrop:

Basuppgifter
- Resurs som används
- GET - vanligen hämtning av data från Netvisor
- POST - vanligen import av data till Netvisor
Parametrar
- Konfigureras vanligen i QueryString, åtskiljs från den egentliga resursen med ett ?-tecken följt av ett &-tecken
- Alla resurser har inte
XML-struktur vid import av data (POST)
- Beskriven XML-struktur samt exempelvis elementens antal och obligatoriska egenskap

Om POST-meddelandet använder självstängande taggar, observera att dessa inte läses alls, inklusive eventuella attribut. Till exempel läses inte elementet <email/> på kundkortet alls, men <email></email> tömmer däremot värdet på Netvisors kundkort.

Svar:
Varje anrop besvaras med ett XML-svar, vars struktur till stor del motsvarar anropet. Den allmänna strukturen för meddelandet ser du i avsnittet nedan. Svaret på hämtningsmeddelanden av GET-typ inkluderar en resursspecifik datastruktur som beskrivs separat i respektive resursbeskrivning. Beroende på meddelandet inkluderar importmeddelanden av POST-typ ett Replies-element i svaret, som innehåller exempelvis ett InsertedDataIdentifier-element som innehåller det tillagda objektets ID-värde.

Meddelandesvar

Varje gränssnittsanrop besvaras med ett standardiserat meddelandesvar. I meddelanden av GET-typ innehåller svaret de begärda uppgifterna (<resursspecifikt element>) och i svar av POST-typ finns möjligen ett fallspecifikt svar (Replies).
Svarsmeddelandets allmänna struktur:
Element: Root (1 förekomst)
Element: Root/ResponseStatus (1 förekomst)

Element	Form	Beskrivning	Exempel	Ytterligare information
Status	Teckensträng	Indikerar om ett fel inträffade under bearbetningen av anropet	OK	FAILED
Status	Teckensträng	Felkonstant och felbeskrivning		Detta element endast i FAILED-läge. Se Hantera räkenskapsperioder
TimeStamp	Datum	Svarets tidstämpel	01.01.2018 12:00:00

Svarstypen är relaterad till datatrafikens riktning:
1. Vid hämtning av data från Netvisor
Hämtade data utgör ett separat element i meddelandet:
Element: Root/ResponseStatus/<resursspecifikt element>
2. Vid import av data till Netvisor
Svaret innehåller Replies-elementet och inom detta från fall till fall data:
Element: Root/ResponseStatus/Replies (0-1 förekomst)

Element	Form	Beskrivning	Exempel	Ytterligare information
InsertedDataIdentifier	Teckensträng
ELLER
Reply	Teckensträng

Följande element förekommer 0-n gånger.

Gränssnittets bilagors tillåtna filformat

ApiBatchSharedAttachments (inköpsfakturapartij.nv, försäljningsfakturapartij.nv )

- Inköpsfakturor:

- Fakturabild (invoiceimage): .pdf, .xml

- Fakturabilagor (otherattachment): .bmp, .csv, .doc, .docx, .emf, .exif, .gif, .gzip, .heic, .eml, .html, .ico, .jpg, .msg, .mp3, .odp, .ods, .odt, .pdf, .png, .pptx, .rtf, .tiff, .txt, .wmf, .xls, .xlsm, .xlsx, .xml, .xsl, .zip, .7z

- Max 20 MiB

- Försäljningsfakturor:

- (pdf) .pdf

- (finvoice) .csv, .doc, .docx, .gif, .html, .jpg, .pdf, .tiff, .txt, .xls, .xlsx, .xsl

- Max 5 MiB

ProductAttachment (product.nv)

- .bmp, .csv, .doc, .docx, .emf, .exif, .gif, .gzip, .heic, .eml, .html, .ico, .jpg, .msg, .mp3, .odp, .ods, .odt, .pdf, .png, .pptx, .rtf, .tiff, .txt, .wmf, .xls, .xlsm, .xlsx, .xml, .xsl, .zip, .7z

- Max 20 MiB

PurchaseInvoiceAttachment (inköpsfaktura.nv)

- Fakturabild (invoiceimage): .pdf, .xml

- Max 20 MiB

SalesInvoiceAttachment (försäljningsfaktura.nv)

- (pdf) .pdf

- (finvoice) .csv, .doc, .docx, .gif, .html, .jpg, .pdf, .tiff, .txt, .xls, .xlsx, .xsl

- Max 5 MiB

TripExpenseAttachment (tripexpense.nv)

- Max 20 MiB

VoucherAttachment (accounting.nv)

- Max 20 MiB

AccountingAttachment(accountingedit.nv)

- Max 20 MiB

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.

Hjälpte det här svaret? Ja Nej