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

Opas

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

  1. Luo varmenteen allekirjoituspyyntö (CSR) ja ota yhteyttä yhdyskäytävän ylläpitäjiin
  2. Määritä alustasi yhteys yhdyskäytävään
  3. Toteuta integraatio yhdyskäytävän API‑rajapintaan
  4. Toteuta yhdyskäytävää varten tarvittava oma API
  5. Testaa alustasi yhteentoimivuutta yhdyskäytävän kanssa (yhteentoimivuustestit)

Jatka lukemista saadaksesi lisätietoja.

Luo CSR ja ota yhteyttä yhdyskäytävän ylläpitäjiin

Luo ensin yksityinen avain alustallesi:

openssl genrsa -out platform.key 2048

Luo sitten varmenteen allekirjoituspyyntö (CSR) käyttäen yksityistä avainta:

openssl req -new \
  -key platform.key \
  -out platform.csr \
  -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.

Nyt ota yhteyttä yhdyskäytävän ylläpitäjiin sähköpostitse support.efti@fintraffic.fi ja liitä:

  1. Varmenteen allekirjoituspyyntö (CSR)
  2. URL‑osoite alustasi yhdyskäytävälle tarjoamaan API-rajapintaan (Platform API for Gate)

Huomio: Alustan API-rajapinnan TLS-varmenteen on oltava yleisesti luotetun sertifikaattiviranomaisen myöntämä. Yhdyskäytävä hyväksyy vain yleisesti luotetut varmenteet eikä hyväksy itse allekirjoitettuja varmenteita.

Saat seuraavat tiedot kehittäjiltä:

  1. Yhdyskäytävän alusta‑rajapinnan URL
  2. Allekirjoitettu asiakasvarmenne
  3. Sertifikaattiviranomaisen (CA) varmenne, jolla yhdyskäytävä allekirjoittaa asiakasvarmenteensa mTLS‑autentikointia varten kutsuessaan sinun API‑rajapintaasi

Määritä alustasi yhteys yhdyskäytävään

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 toimitetun sertifikaattiviranomaisen (CA) varmenteen avulla.

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.

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.

Testaa alustasi yhteentoimivuutta yhdyskäytävän kanssa (yhteentoimivuustestit)

Aja nämä testit varmistaaksesi että alusta integroituu oikein yhdyskäytävään. Näihin testeihin viitataan tässä oppaassa termillä “yhteentoimivuustestit” (engl. “interoperability tests”).

Huomioithan että nämä testit eivät tarkista muita alustan vaatimuksia, 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.