Programmeringsgränssnitt (API)
Öppenhetsregistret kan anslutas till det egna affärssystemet eller till ett annat motsvarande verktyg med hjälp av ett programmeringsgränssnitt (API). Genom integrationen kan uppgifterna i verksamhetsanmälan överföras maskinellt till öppenhetsregistret, vilket minskar det manuella arbetet som rapporteringen orsakar.
API (Application Programming Interface) är ett programmeringsgränssnitt som kan användas för att överföra information mellan olika program. Med gränssnittet kan de anmälningsskyldiga skicka sin verksamhetsanmälan till öppenhetsregistret. Detta underlättar och påskyndar anmälan och minskar det administrativa arbete som uppstår.
Integrationen minskar det manuella arbetet under anmälningsfasen
Integrationen effektiviserar anmälningsprocessen genom att eliminera ett onödigt manuellt steg. När en anmälningsskyldig samlar uppgifter om sin påverkanskommunikation i sitt eget system kan uppgifterna, när anmälningsperioden har inletts, överföras elektroniskt från systemet till öppenhetsregistret. Därmed bortfaller det arbetsmoment där uppgifterna samlas in från det egna systemet och matas in enskilt i öppenhetsregistret.
Integrationen är särskilt till nytta för sådana anmälningsskyldiga som ska rapportera flera ämnen inom påverkanskommunikation eller rådgivning inom påverkanskommunikation. Till öppenhetsregistret anmäls inte varje enskilt möte, utan påverkanskommunikationen rapporteras ämnesvis. Därför kan en anmälningsskyldig som endast har några få ämnen inom påverkanskommunikation eller rådgivning inom påverkanskommunikation även fortsättningsvis lämna sin anmälan smidigt direkt i öppenhetsregistrets e-tjänst.
Den som genomför integrationen ansvarar för integrationen och kostnaderna för den
Integrationen kräver teknisk kompetens och möjlighet att anpassa det system som används så att det motsvarar kraven i öppenhetsregistret. Den anmälningsskyldiga kan bygga eller låta bygga integrationen för sig själv eller utnyttja olika tjänsteleverantörers färdiga tjänster som integrerats i öppenhetsregistret.
Användningen av gränssnittet är kostnadsfri, men den som genomför integrationen ansvarar själv för kostnaderna för utvecklingsarbetet och implementeringen i anslutning till integrationen.
Beställ kundmeddelanden om gränssnittet till din e-post
Statens revisionsverk informerar om tekniska ändringar som påverkar integrationen och om andra frågor som gäller gränssnittet. Beställ kundmeddelanden om öppenhetsregistrets programmeringsgränssnitt, så får du alltid nödvändig information till din e-post. Tidigare kundmeddelanden kan du läsa i arkivet.
Anvisningar för anmälningsskyldiga
Egen integration till öppenhetsregistret
Om du är anmälningsskyldig och vill bygga integrationen mellan det datasystem du använder och öppenhetsregistret, följ dessa anvisningar. Se dessutom närmare anvisningar om det tekniska genomförandet nedan.
Fyll i gränssnittsavtalet och skicka det till adressen avoimuusrekisteri@vtv.fi.
När avtalet har undertecknats och den IP-adress du angett har lagts till i den begränsade testmiljön får du som svar anvisningar om åtkomst till testmiljön.
Gör integrationen i testmiljön och testa att de tekniska lösningarna fungerar.
När testningen har utförts på det sätt som beskrivs i avtalet ska du meddela Statens revisionsverk (avoimuusrekisteri@vtv.fi) om övergången till produktion och begära aktivering av sidan "Hantering av API-nycklar" i öppenhetsregistrets tjänsteportal så att ni kan skapa en API-nyckel för produktionen.
När sidan "Hantering av API-nycklar" visas i tjänsteportalen, skapa nyckeln. Välj "Vi integrerar vårt eget system i öppenhetsregistret" som genomförandesätt för integrationen. Ta genast tillvara den skapade nyckeln. Uppgifterna visas inte längre senare, utan när uppgifterna har förstörts måste en ny nyckel skapas.
Innan den första verksamhetsanmälan som görs i produktionen ska du meddela revisionsverket (avoimuusrekisteri@vtv.fi) tidpunkten då ni kommer att ta i bruk produktionsgränssnittet.
Kom ihåg att skapa och ta i bruk en ny API-nyckel när den föregående går ut.
Tjänst som integrerats av tjänsteleverantören
Om du är anmälningsskyldig och vill använda en tjänst som tillhandahålls av en tredje part för att göra verksamhetsanmälningar, följ dessa anvisningar.
Kom överens om praxis med tjänsteleverantören. Gör en skriftlig fullmakt där du befullmäktigar tjänsteleverantören att agera för din räkning i överenskomna ärenden som gäller öppenhetsregistret.
Din tjänsteleverantör behöver en API-nyckel för att rikta er verksamhetsanmälan till er organisation. Kontakta avoimuusrekisteri@vtv.fi och be om aktivering av sidan "Hantering av API-nycklar" i öppenhetsregistrets tjänsteportal så att ni kan skapa nyckeln.
När sidan "Hantering av API-nycklar" visas i tjänsteportalen, skapa nyckeln. Välj den tjänsteleverantör du använder i den färdiga listan. Om din tjänsteleverantör inte finns på listan, be tjänsteleverantören kontakta avoimuusrekisteri@vtv.fi. Du kan skapa API-nyckeln när tjänsteleverantören har lagts till i listan. Ta genast tillvara den skapade nyckeln. Uppgifterna visas inte längre senare, utan när uppgifterna har förstörts måste en ny API-nyckel skapas.
Skicka API-nyckeln till din tjänsteleverantör på ett datasäkert sätt som rekommenderats av tjänsteleverantören så att nyckeln inte hamnar i fel händer. Skicka nyckeln endast till en betrodd aktör.
Följ din tjänsteleverantörs anvisningar.
Kom ihåg att skapa och leverera en ny API-nyckel till din tjänsteleverantör när den föregående går ut.
Anvisning till tjänsteleverantören
Om du är en tjänsteleverantör som bygger integrationen mellan sin egen tjänst och öppenhetsregistret så att era kunder (anmälningsskyldiga) kan göra anmälningar via den, följ dessa anvisningar. Se dessutom närmare anvisningar om det tekniska genomförandet nedan.
Fyll i gränssnittsavtalet och skicka det till adressen avoimuusrekisteri@vtv.fi.
När avtalet har undertecknats och den IP-adress du angett har lagts till i den begränsade testmiljön får du som svar anvisningar om åtkomst till testmiljön.
Gör integrationen i testmiljön och testa att de tekniska lösningarna fungerar minst på det sätt som beskrivs i avtalet.
Be varje kundorganisation om en skriftlig fullmakt av vilken det framgår i vilka öppenhetsregisterärenden tjänsteleverantören har behörighet att agera.
Gör integrationen i produktionsmiljön.
De anmälningsskyldiga kan skapa en organisationsspecifik API-nyckel i öppenhetsregistrets tjänsteportal på sidan "Hantering av API-nycklar". Sidan syns inte automatiskt i tjänsteportalen, utan kunderna måste be att sidan aktiveras på adressen avoimuusrekisteri@vtv.fi för att kunna skapa en nyckel. Tjänsteleverantören kan också centraliserat begära aktivering för sina kunders räkning.
När sidan "Hantering av API-nycklar" har aktiverats ska du be kunden skapa en organisationsspecifik API-nyckel i tjänsteportalen. När nyckeln skapas ska kunden fastställa en giltighetstid för nyckeln och uppge tjänsteleverantören. Som tjänsteleverantör kan endast anges en aktör som har lämnat in ett ifyllt gränssnittsavtal till Statens revisionsverk. Kom ihåg att instruera kunden att lämna in API-nyckeln till den person som ansvarar för det tekniska genomförandet på ett datasäkert sätt så att nyckeln inte hamnar i fel händer.
Före den första anmälningen i produktion ska du meddela revisionsverket (avoimuusrekisteri@vtv.fi) tidpunkten då ni kommer att ta i bruk produktionsgränssnittet.
Kom ihåg att byta API-nyckeln till en ny när den gått ut. Den anmälningsskyldiga kan skapa en ny nyckel i tjänsteportalen.
Testning och implementering av API-gränssnittet
Nedan lyfter vi fram det viktigaste som ska beaktas i genomförandet av integrationen. Närmare definitioner av gränssnittet, dvs. schemat, hittar du i Swagger-tjänsten. Anvisningen länkar till Swaggers punkter i anslutning till öppenhetsregistrets produktionsmiljö, där man kan kontrollera vilka värden som tas emot eller returneras av anropen i fråga. Motsvarande punkter finns i testmiljöns Swagger.
Tillgång till testmiljön
Testa API-gränssnittet i öppenhetsregistrets testmiljö innan det tas i bruk. Tillgång till testmiljön är begränsad så skicka det ifyllda gränssnittsavtalet till adressen avoimuusrekisteri@vtv.fi.
Efter att avtalet undertecknats läggs den IP-adress du uppgett till i listan över tillåtna adresser. Du får också testmiljöns adress och testpersonbeteckningar för inloggning. Observera att testmiljön är öppen endast vardagar kl. 8–20.
Användning av testmiljön
Logga in i öppenhetsregistrets testmiljö i tjänsteportalen med knappen ”Logga in” uppe till höger. Välj testidentifierare som inloggningssätt och använd testpersonbeteckningen enligt anvisningarna du fått från Statens revisionsverk. Välj i nästa steg den organisation du representerar. Observera att den testpersonbeteckning du valt redan kan ha använts. Välj då en annan oanvänd personbeteckning. Du identifierar en oanvänd personbeteckning genom att du efter att ha loggat in ombeds ge ditt samtycke till behandling av personuppgifter och elektronisk delgivning och att organisationen ännu inte har en registreringsanmälan.
Gör en registreringsanmälan.
I testmiljön är anmälningsperioden inte alltid öppen och då kan verksamhetsanmälningar inte göras. Gå då till sidan "Verktyg för testare" i tjänsteportalen, där du kan aktivera inaktiva verksamhetsanmälningar för ifyllning. Aktivera verksamhetsanmälningarna genom att klicka på blixtikonen i slutet av raden.
I verksamhetsanmälan till öppenhetsregistret anges en gång om året sommartid även ekonomiska uppgifter om påverkanskommunikationen. För att testa dem ska följande testupplägg ställas in:
Ändra på datumet då registreringsanmälan skapades på sidan ”Verktyg för testare” till ett par år tidigare, så att testorganisationen har funnits i registret tillräckligt länge för att ge uppgifter (minst ett helt kalenderår).
Aktivera och fyll i två verksamhetsanmälningar så att de täcker ett helt kalenderår. Rapportera påverkanskommunikation i anmälningarna (välj inte "Inga kontakter alls" eller "Högst 5 kontakter" som omfattning). Aktivera ännu en tredje verksamhetsanmälan i följd. I den tredje verksamhetsanmälan efterfrågas ekonomiska uppgifter.
Genom att gå till tjänsteportalens startsida och klicka på "Gör en verksamhetsanmälan" kan du testa hur genomförandet av en verksamhetsanmälan ser ut i användargränssnittet eller så kan du börja testa genomförandet av verksamhetsanmälningar via användargränssnittet.
Skapa API-nyckel
I integrationen används API-autentisering. Den anmälningsskyldige kan skapa den API-nyckel som behövs för detta i öppenhetsregistrets tjänsteportal.
API-nycklarna skapas på sidan "Hantering av API-nycklar", som inte syns automatiskt i tjänsteportalen. Aktivera sidan i testmiljön på sidan "Testarens verktyg" genom att klicka på aktivera hantering av API-nycklar. I produktionsmiljön ska aktivering av sidan begäras av Statens revisionsverk (avoimuusrekisteri@vtv.fi).
Gå till sidan "Hantering av API-nycklar". Skapa API-nyckel. Kom ihåg att spara nyckelns uppgifter genast när du har skapat den. Uppgifterna visas inte längre senare, utan när uppgifterna har förstörts måste en ny API-nyckel skapas.
Verksamhetsanmälan via gränssnittet
Logga in med den API-nyckel du skapat. Inloggningen returnerar en åtkomsttoken (access token) som används i andra anrop i Authorization header. Åtkomsttoken gäller i fyra timmar. Observera att de endpoints som används vid anmälan har samlats i Swagger-tjänsten under rubriken "Customer API" (exkl. sökning av anmälningsperioder).
I verksamhetsanmälan uppges ämnen för påverkanskommunikation. Ämnena kan vara egna fritt formulerade ämnen (50–600 tecken) eller statsrådets officiella projekt. Ange det officiella projektets projektnummer och namn på det sätt som de anges i Projektfönstret.
Föremål för påverkanskommunikation i anslutning till ämnet väljs från listan som upprätthålls av Statens revisionsverk. Hämta föremålen i gränssnittet antingen per anmälningsperiod eller alla på en gång. GET customer-api/target/all/{termId} ellerGET customer-api/target/targets Föremålets ID-kod är specifik för anmälningsperioden. Eftersom många föremål för påverkanskommunikation ingår i flera anmälningsperioder ska föremålet läggas till med hjälp av ID-koden för den anmälningsperiod för vilken anmälan görs. Statens revisionsverk gör tillägg, ändringar och raderingar i uppgifterna för föremål fram till anmälningsperiodens startdatum. Under anmälningsperioden görs endast nödvändiga korrigeringar eller tillägg i föremålen.
Anmälningsperioderna kan du hämta från gränssnittet GET open-data-term. Det returnerar som resultat uppgifterna för både tidigare och kommande anmälningsperioder. Anmälningarna ska göras i kronologisk ordning för perioderna.
Gör först ett utkast (”draft”) av verksamhetsanmälan. Utkastet valideras inte vid denna tidpunkt. POST customer-api/draft-activity-notification Om du vill uppdatera ett skapat utkast, skicka hela utkastet på nytt med PATCH-metoden. Observera att uppdateringarna överskriver eventuella ändringar som gjorts i användargränssnittet. PATCH customer-api/draft-activity-notification/{draftId}
Validera utkastet innan det publiceras. Om valideringen misslyckas får du som returmeddelande ett felmeddelande och en lista över problem i anmälningen. GET Kontrollera i användargränssnittet efter en lyckad validering att utkastet ser korrekt ut och att ämnena och föremålen har överförts.
Publicera utkastet som godkänts i valideringen. Anmälan valideras också i samband med publiceringen. POST customer-api/activity-notification/publish/{draftId} En publicerad verksamhetsanmälan visas på öppenhetsregistrets webbplats utan inloggning. Kontrollera i användargränssnittet att anmälningen är korrekt. Om du behöver redigera en publicerad anmälan ska du göra det i öppenhetsregistrets användargränssnitt genom att logga in i tjänsteportalen.
Testmiljön har ett överflödigt gränssnitt som underlättar testningen. Med gränssnittet kan man söka och ta bort enskilda eller alla organisationens verksamhetsanmälningar för att kunna testa deras genomförande på nytt. Testmiljö: DELETE customer-api/test-utils/
Övergång till produktionsmiljön
Du kan övergå till att bygga integrationen i produktionsmiljön när du har framgångsrikt testat följande testfall i testmiljön minst en gång:
Skapat ett utkast till verksamhetsanmälan via gränssnittet och validerat det
Uppdaterat utkastet till verksamhetsanmälan via gränssnittet
Publicerat verksamhetsanmälan via gränssnittet eller publicerat en verksamhetsanmälan som gjorts i gränssnittet i tjänsteportalens användargränssnitt
Kontrollerat att den publicerade verksamhetsanmälan syns korrekt i användargränssnittet
Observerat att verksamhetsanmälan även innehåller ekonomiska uppgifter en gång om året.
Före den första anmälningen i produktion ska du meddela revisionsverket (avoimuusrekisteri@vtv.fi) tidpunkten då ni kommer att ta i bruk produktionsgränssnittet.
En verksamhetsanmälan till öppenhetsregistret görs två gånger om året. Uppgifterna i verksamhetsanmälan ska lämnas till öppenhetsregistret när anmälningsperioden är öppen i januari–februari och juli–augusti. De verksamhetsanmälningar som inkommit efter att anmälningsperioden stängts antecknas som försenade.