Obs: datamodellernas struktur kommer att förändras, men det regleringsbaserade datainnehållet kommer att vara liknande i den nya modellen jämfört med den nuvarande.
Mer information om förändringarna kommer under sommaren.

Guide

För att integrera med testnätslussen måste du följa dessa steg:

  1. Informera nätslussens administratörer om att du vill integrera din plattform med nätslussen
  2. Generera en begäran om certifikatsignering (CSR) och skicka den till administratörerna
  3. Implementera integrationen mot nätslussens API
  4. Implementera det API som krävs för eFTI‑nätslussen
  5. Konfigurera autentisering och nätslussens URL
  6. Interoperabilitetstestning

Fortsätt läsa för mer information.

Kontakta nätslussens administratörer

Kontakta administratörerna för eFTI‑nätslussen via e-post på support.efti@fintraffic.fi och meddela att du vill integrera med nätslussen.

Du kommer att få följande information från utvecklarna:

  1. URL till nätslussens API för plattformen
  2. En CSR‑mall (Certificate Signing Request) för ditt klientcertifikat
  3. Nätslussens klientcertifikat, som nätslussen använder för mTLS‑autentisering när den anropar ditt API

Generera och skicka en CSR för ditt klientcertifikat

Med hjälp av den CSR‑mall du fått kan du skapa din CSR enligt följande exempel:

openssl x509 -req -new \ 
  -key <private key> \
  -config platform-csr-template.cnf \
  -out <csr file> \
  -subj "/C=<country code>/ST=<state name>/L=<city name>/O=<organisation name>/OU=<organisational unit name>/CN=<platform domain name>"

Ersätt delarna inom och inklusive vinkelparenteserna med rätt värden.

Skicka följande till nätslussens administratörer:

  1. URL:en till ditt Plattforms-API för nätslussen
  2. CSR‑filen
  3. Om du använder ett TLS-certifikat som inte är allmänt pålitligt (till exempel ett självsignerat certifikat), skicka även det TLS-certifikat som används. Nätslussen litar automatiskt på certifikat som är betrodda av Java (OpenJDK).

Efter en tid kommer de att leverera ditt färdiga klientcertifikat till dig.

Implementera integrationen mot nätslussens API

Din plattform måste kunna skicka försändelseidentifierare till nätslussen. API:et som nätslussen tillhandahåller beskrivs i schemat Gate API for platform.

Implementera API:et för nätslussen

Nätslussen kommer att skicka följande till din plattform:

Din plattform måste implementera API:et enligt schemat Platform API for Gate.

Konfigurera autentisering och nätslussens URL

Integrationen använder ömsesidig TLS‑autentisering (mTLS) i båda riktningarna. Konfigurera därför din plattform så att den:

  1. innehåller ditt klientcertifikat i alla anrop till nätslussen
  2. autentiserar inkommande anrop med hjälp av nätslussens klientcertifikat

Konfigurera också plattformen så att den skickar sina anrop till den URL (“GATE_URL”) du fått från nätslussens administratörer.

Du kan testa anslutningen genom att skicka en whoami-förfrågan till nätslussen enligt beskrivningen i eFTI‑nätslussens API för plattformen.

Interoperabilitetstestning

Kör interoperabilitetstester för att verifiera att din plattform uppfyller alla tekniska krav för integration med nätslussen. Det bör noteras att testerna inte verifierar några andra krav på plattformen, inklusive de som definieras av eFTI-förordningen.

Det API som används för att köra testerna är dokumenterat i schema Interoperabilitets-API för plattformar.
Du behöver också ett giltigt klientcertifikat för att starta testerna. Se tidigare avsnitt.

Nedan finns en beskrivning på hög nivå av förloppet för interoperabilitetstestning:

sequenceDiagram autonumber actor Platform Developer Platform Developer ->> Platform: Save a new consignment Platform ->> Gate: Send consignment identifiers Gate -->> Platform: Return unique identifier link (UIL) Platform Developer ->> Gate: Start interoperability tests with the data set identifier from UIL activate Gate par note right of Gate: Run the tests and Gate -->> Platform Developer: Return test run identifier end Platform Developer ->> Gate: Retrieve test results with test run identifier deactivate Gate Gate -->> Platform Developer: Return test results
Detta diagram visar interoperabilitetstestningsarbetsflödet med numrerade steg: Förberedelsefas (Steg 1-3) Steg 1: Plattformsutvecklaren skapar en ny försändelse i sin Plattform. Steg 2: Plattformen skickar försändelseidentifierarna till Nätslussen. Steg 3: Nätslussen registrerar identifierarna och returnerar en Unique Identifier Link (UIL) som innehåller datauppsättnings-ID. Starta tester (Steg 4-5) Steg 4: Plattformsutvecklaren initierar testkörningen med datauppsättnings-ID:t från UIL. Steg 5: Nätslussen accepterar förfrågan och returnerar omedelbart en testkörningsidentifierare, samtidigt som den startar de faktiska testerna asynkront i bakgrunden. Testutförande (Bakgrund, mellan steg 5-6) Nätslussen kör flera sekventiella tester mot Plattformen för att verifiera korrekt integrationsbeteende. Om något test misslyckas hoppas de återstående testerna över. Hämta resultat (Steg 6-7) Steg 6: Plattformsutvecklaren pollar testkörningens status. Steg 7: Nätslussen returnerar aktuell status och detaljerade resultat för varje enskilt test.

Starta testerna

Se till att din plattform har skickat försändelseidentifierare till gaten. Du kommer att behöva identifieraren för eFTI-datasetet (“DATASET_ID”) för att fortsätta med testningen. Observera att samma försändelseidentifierare kan återanvändas i flera testkörningar.

Starta en testkörning genom att skicka en POST-förfrågan till nätslussens /v0/test-runs-endpoint med den kropp i förfrågan som beskrivs i Interoperabilitets-API för plattformar.
En testkörning består av flera tester som körs sekventiellt, där varje test testar olika funktioner i integrationen.

Det finns ingen begränsning för hur många gånger du kan starta testerna.

curl -X POST <GATE_URL>/v0/test-runs \
 --cert platform.pem \
 --key platform.key \
 -H "Content-Type: application/xml" \
 -d '<startTestRunRequest><datasetId>DATASET_ID</datasetId></startTestRunRequest>'

I svarets kropp får du en unik testkörningsidentifierare (“testRunId”) som du kan använda för att hämta testresultaten.

Hämta testresultat

Efter att ha startat en testkörning kan du hämta resultaten genom att skicka en GET-förfrågan till nätslussens /v0/test-runs/{testRunId}-endpoint enligt beskrivningen i Interoperabilitets-API för plattformar.

curl <GATE_URL>/v0/test-runs/<TEST_RUN_ID> \
 --cert platform.pem \
 --key platform.key

Grattis! När alla tester har godkänts kommunicerar din plattform med gaten korrekt.