Establishing Integration with Legemiddelregisteret

Example code

FHI has created example code showing how an integration with Legemiddelregisteret can be developed. The example code is available in both C# and PowerShell, and demonstrates the most important functions for secure data transfer to the registry.

You can find the example code here:

• C# example code
• PowerShell example code

IP address allowlisting

To gain access to the API for data transfer, the sender system’s IP address must be registered in LMR’s list of allowlisted addresses. Both individual addresses and address ranges can be allowlisted. Allowlisting is only available in the production environment.

Certificates

Data transferred to the API must be encrypted and signed (see Signed and Encrypted Bundle).

• Signing uses the private key in the sender’s enterprise certificate. The public part of this certificate must be sent to Legemiddelregisteret.
• Encryption of data uses the public key in Legemiddelregisteret’s enterprise certificate. This can be downloaded here.

Maskinporten

The API is protected by Maskinporten and requires clients to authenticate with machine-to-machine authentication.

To gain access:

1. Register an integration in Digdir’s self-service portal (https://sjolvbetjening.test.samarbeid.digdir.no/)
   • Create a client
   • Request access to the scope fhi:lmr/fhirmottak.api
2. Implement OAuth 2.0 Client Credentials flow with JWT bearer token. It is recommended to use the Altinn library: https://github.com/Altinn/altinn-apiclient-maskinporten
   • Generate a signing key directly in the self-service portal (PEM format) or create your own using your enterprise certificate.
   • Generate a signed JWT assertion and send it to Maskinporten’s token endpoint.
   • It is important to include the optional claim Resource in the JWT assertion. This value must be fhi:lmr/fhirmottak.
   • The Scope claim must also be added. This value corresponds to the name of the scope in the self-service portal: fhi:lmr/fhirmottak.api
3. Include the received access token in the Authorization header as a Bearer token when calling the API.

Transferring data to Legemiddelregisteret

Institutions that are to transfer data to Legemiddelregisteret must follow the defined protocol. The protocol describes requirements for transfer frequency, data structure, and security. You can find more information here: Protocol for data transfer.

To build a collection of data to be transferred, a LegemiddelregisterBundle must be created. This is a specialised FHIR Bundle profile developed for submitting data to Legemiddelregisteret. It is limited to transaction-type bundles and only permits POST operations, ensuring consistent data handling and traceability. The bundle may only contain specific resource types relevant to Legemiddelregisteret: Patient, Practitioner, Medication, MedicationAdministration, Condition, Encounter, MedicationRequest, Organization, Substance.

When transferring data, a SignertKryptertBundle must be created, which ensures both encryption and signing of the content. This process involves compressing, encrypting, and signing a FHIR-based LegemiddelregisterBundle before it is sent to the API. Read more about how to create a SignertKryptertBundle in this guide.

URLs for Legemiddelregisteret’s API:

• TEST environment: https://test-fhirmottak.lmr.fhi.no/fhirmottak/v1
• PROD environment: https://fhirmottak.lmr.fhi.no/fhirmottak/v1

Test endpoints

For testing the integration, two dedicated validation endpoints are available. These store no data and are only available in the test environment.

Validation of FHIR bundle:

• /fhirmottak/v1/validateLegemiddelregisterBundle – Validates the content of a FHIR bundle against the LMDI specification. The endpoint expects to receive an unsigned and unencrypted FHIR bundle in JSON format. Does not require authentication, and the sender does not need to be registered. Returns a validation result as OperationOutcome with status 200 (valid) or 400 (invalid).

Validation of signed and encrypted bundle:

• /fhirmottak/v1/validate – Validates that signing and encryption have been performed correctly, and that the content of the encrypted FHIR bundle is in accordance with the LMDI specification. The endpoint expects to receive a signed and encrypted bundle. The sender must be registered and active. Data is validated but not stored. Requires Maskinporten authentication with scope fhi:lmr/fhirmottak.api. Returns status 200 (valid) or 400 (invalid).

Handling responses from the test endpoints

The test endpoints return the following HTTP status codes:

200 OK

• The message was validated without errors
• For /fhirmottak/v1/validate: The message has been validated but not stored
• For /fhirmottak/v1/validateLegemiddelregisterBundle: Returns OperationOutcome confirming that the FHIR bundle is valid

400 Bad Request

• Validation error in the submitted message
• Possible causes (both endpoints):
  • FHIR bundle validation failed (not in accordance with the LMDI specification)
  • Invalid JSON format
• Possible causes only for /fhirmottak/v1/validate:
  • Unknown or inactive sender
  • Organisation number in message does not match the registered sender
  • Signature validation failed
  • Decryption failed

401 Unauthorized

• Authentication failed (applies to /fhirmottak/v1/validate)
• Possible causes:
  • Missing Authorization header or token
  • Expired access token
  • Invalid token signature
  • Invalid issuer or audience
• The response includes a WWW-Authenticate header with an error description

403 Forbidden

• Authorisation failed (applies to /fhirmottak/v1/validate)
• Token is valid, but lacks the required scope (fhi:lmr/fhirmottak.api)
• The response includes a WWW-Authenticate header with an error description

500 Internal Server Error

• An unexpected error occurred during processing of the message
• Server error that should be investigated with FHI