Huomio: tietomallien rakenne tulee muuttumaan, mutta lainsäädäntöön pohjautuva tietosisältö tulee uudessa mallissa olemaan samankaltainen nykyisen kanssa.
Muutoksista tulee lisätietoja kesän aikana.

Opas

Liittyäksesi testiyhdyskäytävään sinun tulee noudattaa seuraavia vaiheita:

  1. Ilmoita yhdyskäytävän ylläpitäjille, että haluat integroida alustasi yhdyskäytävään
  2. Luo varmenteen allekirjoituspyyntö (CSR) ja lähetä se yhdyskäytävän ylläpitäjille
  3. Toteuta integraatio yhdyskäytävän API‑rajapintaan
  4. Toteuta yhdyskäytävää varten tarvittava oma API
  5. Määritä autentikointi ja yhdyskäytävän URL
  6. Yhteentoimivuustestaus

Jatka lukemista saadaksesi lisätietoja.

Ota yhteyttä yhdyskäytävän ylläpitäjiin

Ota yhteyttä yhdyskäytävän ylläpitäjiin sähköpostitse support.efti@fintraffic.fi ja kerro, että haluat integroitua yhdyskäytävään.

Saat seuraavat tiedot kehittäjiltä:

  1. Yhdyskäytävän alusta‑rajapinnan URL
  2. Varmenteen allekirjoituspyynnön (CSR) malli asiakasvarmennettasi varten
  3. Yhdyskäytävän asiakasvarmenne, jota yhdyskäytävä käyttää mTLS‑autentikointiin kutsuessaan sinun API‑rajapintaasi

Luo ja lähetä CSR omaa asiakasvarmennettasi varten

Käyttämällä saamaasi CSR‑mallia voit luoda oman CSR‑pyyntösi seuraavan esimerkin mukaisesti:

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>"

Korvaa kulmasulkeissa olevat kohdat sopivilla arvoilla.

Lähetä yhdyskäytävän ylläpitäjille:

  1. URL‑osoite alustasi yhdyskäytävälle tarjoamaan API-rajapintaan (Platform API for Gate)
  2. CSR‑tiedosto
  3. Mikäli käytette TLS varmennetta, joka ei ole yleisesti luotettu (esimerkiksi itse allekirjoitettu varmenne), lähetä myös käytetty TLS varmenne. Yhdyskäytävä luottaa Javan (OpenJDK) allekirjoitusvarmenteisiin.

Jonkin ajan kuluttua saat ylläpitäjiltä oman asiakasvarmenteesi.

Toteuta integraatio yhdyskäytävän API-rajapintaan

Alustasi on pystyttävä lähettämään lähetyksen tunnisteet yhdyskäytävälle. Yhdyskäytävän tarjoama API on dokumentoitu Gate API for Platform ‑skeemassa.

Toteuta alustan yhdyskäytävälle tarjoama API

Yhdyskäytävä lähettää alustallesi:

Alustasi on toteutettava API Platform API for Gate -skeeman mukaisesti.

Määritä autentikointi ja yhdyskäytävän URL

Integraatio käyttää kaksisuuntaista Mutual TLS ‑autentikointia (mTLS). Määritä alustasi seuraavasti:

  1. Sisällytä oma asiakasvarmenteesi kaikkiin yhdyskäytävälle lähettämiisi pyyntöihin.
  2. Tunnista saapuvat pyynnöt yhdyskäytävän asiakasvarmenteen avulla.

Määritä lisäksi alusta lähettämään pyynnöt yhdyskäytävän ylläpitäjiltä saamaasi URL‑osoitteeseen (“GATE_URL”).

Yhteyden toimivuuden voi halutessaan testata lähettämällä whoami-pyyntö yhdyskäytävälle, kts. eFTI-yhdyskäytävän eFTI-alustalle tarjoama API.

Yhteentoimivuustestaus

Yhteentoimivuustestauksella varmistetaan, että eFTI-alusta täyttää kaikki integrointia koskevat tekniset vaatimukset eFTI-yhdyskäytävän kanssa. Huomioithan, että testien tarkoituksena ei ole todentaa muiden vaatimusten täyttymistä, mukaan lukien eFTI-asetuksen asettamat vaatimukset.

Testien suorittamiseen käytettävä API on dokumentoitu skeemassa eFTI-yhdyskäytävän tarjoama API yhteentoimivuustestausta varten.
Testien aloittamiseen tarvitaan voimassa oleva asiakasvarmenne, kts. edelliset kohdat.

Alla on ylätason kuvaus yhteentoimivuustestauksen kulusta:

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
Tämä kaavio esittää yhteentoimivuustestauksen kulun numeroituina vaiheina: Valmisteluvaihe (Vaiheet 1-3) Vaihe 1: Alustan kehittäjä luo uuden lähetyksen omaan Alustaansa. Vaihe 2: Alusta lähettää lähetyksen tunnisteet Yhdyskäytävälle. Vaihe 3: Yhdyskäytävä rekisteröi tunnisteet ja palauttaa Unique Identifier Link (UIL) -linkin sisältäen tietoaineiston tunnisteen. Testien käynnistys (Vaiheet 4-5) Vaihe 4: Alustan kehittäjä käynnistää testisuorituksen UIL:stä saadulla tietoaineiston tunnisteella. Vaihe 5: Yhdyskäytävä hyväksyy pyynnön ja palauttaa välittömästi testisuorituksen tunnisteen, samalla kun käynnistää varsinaiset testit asynkronisesti taustalla. Testien suoritus (Taustaprosessi, vaiheiden 5-6 välissä) Yhdyskäytävä suorittaa useita peräkkäisiä testejä Alustaa vastaan varmistaakseen integraation oikean toiminnan. Jos jokin testi epäonnistuu, jäljellä olevat testit ohitetaan. Tulosten hakeminen (Vaiheet 6-7) Vaihe 6: Alustan kehittäjä pollaa testisuorituksen tilaa. Vaihe 7: Yhdyskäytävä palauttaa nykyisen tilan ja yksityiskohtaiset tulokset jokaiselle yksittäiselle testille.

Testauksen aloittaminen

Lähetyksen tunnisteet tulee lähettää eFTI-alustalta eFTI-yhdyskäytävälle ennen testejä. Testausta ei voi aloittaa ilman eFTI-tietojoukon tunnistetta (“DATASET_ID”), mutta samaa tunnistetta voi käyttää useammassa testiajossa.

Aloita yhteentoimivuustestaus lähettämällä POST-pyynnön yhdyskäytävän /v0/test-runs-päätepisteeseen. Liitä pyyntöön sanoma, joka on tarkemmin kuvattu skeemassa eFTI-yhdyskäytävän tarjoama API yhteentoimivuustestausta varten.
Tämän jälkeen testiajo käynnistyy automaattisesti ja se koostuu useista peräkkäisistä testeistä, joista jokainen testaa eri toiminallisuutta.

Testiajojen määrää ei ole rajoitettu.

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>'

Vastaussanomassa palautetaan uniikki testiajotunniste (“testRunId”), jolla haetaan testiajon tulokset.

Testituloksien hakeminen

Hae testiajon testitulokset lähettämällä GET-pyynnön yhdyskäytävän /v0/test-runs/{testRunId} -päätepisteeseen, katso tarkempi kuvaus skeemasta eFTI-yhdyskäytävän tarjoama API yhteentoimivuustestausta varten.

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

Onneksi olkoon! Kun kaikki testit on suoritettu hyväksytysti, eFTI-alusta kommunikoi eFTI-yhdyskäytävän kanssa oikein.