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 summer.

Guide

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

  1. Inform gate maintainers that you wish to integrate your platform to the gate
  2. Generate a certificate signing request and send it to gate maintainers
  3. Implement integration to gate API
  4. Implement API for gate
  5. Configure authentication and gate URL
  6. Run interoperability tests

Continue reading for more details.

Contact the Gate Maintainers

Contact the gate maintainers by email at support.efti@fintraffic.fi and tell them you wish to integrate to the gate.

You will receive the following information from the developers:

  1. URL to the Gate API for Platform
  2. A certificate signing request (CSR) template for your client certificate
  3. Gate’s client certificate the gate will use for mTLS authentication when calling your API

Generate and Send a CSR for Your Client Certificate

Using the CSR template you received, you may generate the CSR following this example:

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

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

Send to the gate maintainers:

  1. URL to your Platform API for Gate
  2. The CSR file
  3. If you are using a TLS certificate that is not publicly trusted (for example, a self-signed certificate), also send the TLS certificate being used. The gate trusts CA certificates included with Java (OpenJDK).

After a while they will deliver your client certificate to you.

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.

Configure Authentication and Gate URL

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 using the gate’s client certificate

Also configure you platform to send requests to the URL provided by the gate maintainers (“GATE_URL”).

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

Interoperability testing

Run interoperability tests to verify that your platform meets all the technical requirements for integration with the gate.
It should be noted that the tests 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.