Notice: the structure of the data models will change, but the regulation-based data content will be similar in the new model to the current one.
More information about the changes will be provided during the autumn.

Guide

To integrate into the test gate, you must follow these steps:

  1. Generate a certificate signing request and contact gate maintainers
  2. Configure your platform connection
  3. Implement integration to gate API
  4. Implement API for gate
  5. Test your platform’s integration with the gate (interoperability tests)

Continue reading for more details.

Generate CSR and Contact the Gate Maintainers

First, generate a private key for your platform:

openssl genrsa -out platform.key 2048

Then, generate a certificate signing request (CSR) using your private key:

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

Please replace the parts between and including angle brackets with appropriate values.

Now, contact the gate maintainers by email at support.efti@fintraffic.fi and include:

  1. Your certificate signing request (CSR)
  2. URL to your Platform API for Gate

Note: Your Platform API must use a TLS certificate issued by a publicly trusted Certificate Authority. The Gate trusts CA certificates included with Java (OpenJDK) and does not accept self-signed certificates.

You will receive the following information from the developers:

  1. URL to the Gate API for Platform
  2. Your signed client certificate
  3. Certificate Authority (CA) certificate that Gate uses to sign its client certificate for mTLS authentication when calling your API

Configure your platform connection

The integration will use Mutual TLS Authentication (mTLS) in both directions. Please configure your platform to:

  1. Include your client certificate in all requests sent to the gate
  2. Authenticate incoming requests from the gate using the provided Certificate Authority (CA) certificate

Also configure your platform to send requests to the URL provided by the gate maintainers.

You can test the connection by sending a whoami request to the gate as described in Gate API for Platform.

Implement Integration to Gate API

Your platform must be able to send consignment identifiers to the gate. The API provided by the gate is documented by the schema Gate API for Platform.

Implement API for Gate

The gate will send your platform:

Your platform must the implement the API as defined by the schema Platform API for Gate.

Test your platform’s integration with the gate (interoperability tests)

Run these tests to verify that your platform integrates correctly with the gate. These tests are referred to as “ interoperability tests” in this guide.

Note that they do not verify any other requirements of the platform, including those defined by the eFTI regulation.

The API used to run the tests is documented in schema Platform Interoperability API for Platform.
You’ll also need a valid client certificate to start the tests. See the previous sections.

Below is a high-level overview of the interoperability testing process

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
This diagram shows the interoperability testing workflow with numbered steps: Setup Phase (Steps 1-3) Step 1: Platform Developer creates a new consignment in their Platform. Step 2: Platform sends the consignment identifiers to the Gate. Step 3: Gate registers the identifiers and returns a Unique Identifier Link (UIL) containing the dataset ID. Starting Tests (Steps 4-5) Step 4: Platform Developer initiates the test run with the dataset ID from the UIL. Step 5: Gate accepts the request and immediately returns a test run identifier, while starting the actual tests asynchronously in the background. Test Execution (Background, between steps 5-6) Gate executes multiple sequential tests against the Platform to verify correct integration behavior. If any test fails, the remaining tests are skipped. Retrieving Results (Steps 6-7) Step 6: Platform Developer polls the test run status. Step 7: Gate returns the current status and detailed results for each individual test.

Starting the tests

Make sure your platform has sent the consignment identifiers to the gate before the tests. You will need the identifier of the eFTI data set (“DATASET_ID”) to proceed with the testing. Furthermore, the same identifier can be reused across multiple test runs.

Start a test run by sending a POST request to the gate’s /v0/test-runs endpoint with the request body described in Platform Interoperability API for Platform.
A test run consists of multiple tests that are executed sequentially, each testing the different functionalities of the integration.

There’s no limit on how many times you can start the tests.

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

In the response body, you’ll receive a unique test run identifier (“testRunId”) that you can use to retrieve the test results.

Retrieving test results

After starting a test run, you can retrieve the results by sending a GET request to the gate’s /v0/test-runs/{testRunId} endpoint as described in Platform Interoperability API for Platform.

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

Congratulations! Once all tests have passed, your platform is communicating with the gate correctly.